@rangojs/router 0.0.0-experimental.18 → 0.0.0-experimental.19

package/src/router/match-pipelines.ts

@@ -86,19 +86,14 @@
  *     -> output: cached segments + fresh loader data
  *
  *
- * TWO PIPELINE VARIANTS
- * =====================
- *
- * 1. createMatchPipeline (Full Match)
- *    - Used for document requests (initial page load)
- *    - No revalidation logic (no previous state to compare)
- *    - Simpler segment resolution
- *
- * 2. createMatchPartialPipeline (Partial Match)
- *    - Used for client-side navigation
- *    - Includes revalidation for SWR
- *    - Compares with previous params/URL
- *    - Supports intercepts (soft navigation modals)
+ * PIPELINE VARIANT
+ * ================
+ *
+ * createMatchPartialPipeline handles both full (document) and partial
+ * (navigation) requests. The middleware steps adapt based on ctx.isFullMatch:
+ * - cache-lookup/store work for both
+ * - background-revalidation is a no-op for full matches (no stale state)
+ * - intercept-resolution is a no-op for full matches (no previous navigation)
  */
 import type { ResolvedSegment } from "../types.js";
 import type { MatchContext, MatchPipelineState } from "./match-context.js";
@@ -182,33 +177,3 @@ export function createMatchPartialPipeline<TEnv>(
   // Start with empty source - cache lookup or segment resolution will produce segments
   return pipeline(empty());
 }
-
-/**
- * Create the full match pipeline (simpler, no revalidation)
- *
- * Used for document requests (initial page load) where we don't need
- * revalidation logic since there's no previous state to compare against.
- */
-export function createMatchPipeline<TEnv>(
-  ctx: MatchContext<TEnv>,
-  state: MatchPipelineState,
-): AsyncGenerator<ResolvedSegment> {
-  // For full match, we only need:
-  // 1. Cache lookup
-  // 2. Segment resolution (without revalidation)
-  // 3. Intercept resolution
-  // 4. Cache store
-
-  // Note: Full match uses different resolution logic (resolveAllSegments instead of
-  // resolveAllSegmentsWithRevalidation). This will be handled by the segment resolution
-  // middleware checking ctx.isFullMatch or similar flag.
-
-  const pipeline = compose<ResolvedSegment>(
-    withCacheStore(ctx, state),
-    withInterceptResolution(ctx, state),
-    withSegmentResolution(ctx, state),
-    withCacheLookup(ctx, state),
-  );
-
-  return pipeline(empty());
-}

package/src/router/middleware-types.ts

@@ -8,6 +8,7 @@
 import type { ContextVar } from "../context-var.js";
 import type {
   DefaultReverseRouteMap,
+  DefaultRouteName,
   DefaultVars,
 } from "../types/global-namespace.js";
 import type { ScopedReverseFunction } from "../reverse.js";
@@ -93,6 +94,12 @@ export interface MiddlewareContext<
    */
   header(name: string, value: string): void;
 
+  /**
+   * The matched route name, if available and the route has an explicit name.
+   * Undefined for global middleware (runs before route matching) or unnamed routes.
+   */
+  routeName?: DefaultRouteName;
+
   /**
    * Generate URLs from route names.
    * - `name` — global route, from the named-routes definition

package/src/router/middleware.ts

@@ -19,6 +19,7 @@ import type {
   ResponseHolder,
 } from "./middleware-types.js";
 import { _getRequestContext } from "../server/request-context.js";
+import { isAutoGeneratedRouteName } from "../route-name.js";
 
 // Re-export types and cookie utilities for backward compatibility
 export type {
@@ -32,6 +33,27 @@ export type {
 } from "./middleware-types.js";
 export { parseCookies, serializeCookie } from "./middleware-cookies.js";
 
+// W5: Deduplicate by function reference so each distinct middleware warns once,
+// regardless of whether it is named or anonymous.
+let warnedRedirectMiddleware = new WeakSet<Function>();
+
+function warnCtxSetBeforeRedirect(handler: Function): void {
+  if (warnedRedirectMiddleware.has(handler)) return;
+  warnedRedirectMiddleware.add(handler);
+  const label = handler.name || "(anonymous)";
+  console.warn(
+    `[rango] Route middleware "${label}" called ctx.set() then returned a ` +
+      `redirect. Context variables are per-request and won't be available ` +
+      `on the redirect target. Use cookies to persist state across ` +
+      `redirects, or move ctx.set() to the target route's middleware.`,
+  );
+}
+
+/** Reset W5 deduplication state (for tests only). */
+export function _resetW5Warnings(): void {
+  warnedRedirectMiddleware = new WeakSet();
+}
+
 /**
  * Parse a route pattern into regex and param names
  * Supports: *, /path, /path/*, /path/:param, /path/:param/*
@@ -143,6 +165,15 @@ export function createMiddlewareContext<TEnv>(
     searchParams: url.searchParams,
     env: env as MiddlewareContext<TEnv>["env"],
     params,
+    // Getter: re-derives from request context on each access so that global
+    // middleware sees the matched route name after await next().
+    get routeName(): MiddlewareContext<TEnv>["routeName"] {
+      const reqCtx = _getRequestContext();
+      const raw = reqCtx?._routeName;
+      return (
+        raw && !isAutoGeneratedRouteName(raw) ? raw : undefined
+      ) as MiddlewareContext<TEnv>["routeName"];
+    },
 
     get res(): Response {
       // Before next(): return shared RequestContext stub so headers
@@ -267,8 +298,8 @@ export async function executeMiddleware<TEnv>(
       // End of chain - call actual RSC handler
       const response = await finalHandler();
 
-      // Merge headers set on stub into the real response
-      // Use append for Set-Cookie to preserve multiple cookies
+      // Merge headers set on stub into the real response.
+      // Use append for Set-Cookie to preserve multiple cookies.
       const mergedHeaders = new Headers(response.headers);
       stubResponse.headers.forEach((value, name) => {
         if (name.toLowerCase() === "set-cookie") {
@@ -277,7 +308,9 @@ export async function executeMiddleware<TEnv>(
           mergedHeaders.set(name, value);
         }
       });
-      // Also merge shared RequestContext stub (cookies written via cookies().set())
+      // Also merge shared RequestContext stub (cookies written via cookies().set()).
+      // Set-Cookie duplication is prevented by createResponseWithMergedHeaders
+      // draining Set-Cookie from ctx.res after merging (helpers.ts).
       const reqCtx = _getRequestContext();
       if (reqCtx) {
         reqCtx.res.headers.forEach((value, name) => {
@@ -309,14 +342,30 @@ export async function executeMiddleware<TEnv>(
       reverse,
     );
 
-    // Track if next() was called and capture its Promise
-    // This handles the case where middleware calls next() synchronously without await
+    // Track if next() was called and capture its Promise.
+    // Guard against double-calling: a second call would re-enter the
+    // downstream chain and overwrite responseHolder.response.
     let nextPromise: Promise<Response> | null = null;
     const wrappedNext = (): Promise<Response> => {
+      if (nextPromise) {
+        throw new Error(
+          `[@rangojs/router] Middleware called next() more than once.`,
+        );
+      }
       nextPromise = next();
       return nextPromise;
     };
 
+    // W5: track whether ctx.set() is called during this middleware
+    let ctxSetCalled = false;
+    if (process.env.NODE_ENV !== "production") {
+      const originalSet = ctx.set;
+      ctx.set = ((...args: any[]) => {
+        ctxSetCalled = true;
+        return (originalSet as Function).apply(ctx, args);
+      }) as typeof ctx.set;
+    }
+
     const result = await entry.handler(ctx, wrappedNext);
 
     // Explicit return takes precedence (middleware short-circuit).
@@ -324,6 +373,16 @@ export async function executeMiddleware<TEnv>(
     // RequestContext stub headers (from ctx.setCookie) into the
     // returned Response so they are not lost.
     if (result instanceof Response) {
+      // W5: warn if ctx.set() was called but middleware returned a redirect
+      if (
+        process.env.NODE_ENV !== "production" &&
+        ctxSetCalled &&
+        result.status >= 300 &&
+        result.status < 400
+      ) {
+        warnCtxSetBeforeRedirect(entry.handler);
+      }
+
       const mergedHeaders = new Headers(result.headers);
       stubResponse.headers.forEach((value, name) => {
         if (name.toLowerCase() === "set-cookie") {
@@ -365,6 +424,19 @@ export async function executeMiddleware<TEnv>(
     // If middleware called next(), await it and return the response
     if (nextPromise) {
       await nextPromise;
+
+      // W5: warn if ctx.set() was called but the downstream response is a redirect.
+      // The ctx.set() values will be lost because the redirect navigates away.
+      if (
+        process.env.NODE_ENV !== "production" &&
+        ctxSetCalled &&
+        responseHolder.response &&
+        responseHolder.response.status >= 300 &&
+        responseHolder.response.status < 400
+      ) {
+        warnCtxSetBeforeRedirect(entry.handler);
+      }
+
       return responseHolder.response!;
     }
 
@@ -443,7 +515,18 @@ export async function executeInterceptMiddleware<TEnv>(
       reverse,
     );
 
-    const result = await middleware(ctx, next);
+    let nextCalled = false;
+    const guardedNext = (): Promise<Response> => {
+      if (nextCalled) {
+        throw new Error(
+          `[@rangojs/router] Intercept middleware called next() more than once.`,
+        );
+      }
+      nextCalled = true;
+      return next();
+    };
+
+    const result = await middleware(ctx, guardedNext);
 
     if (result instanceof Response) {
       earlyResponse = result;
@@ -467,12 +550,14 @@ export async function executeInterceptMiddleware<TEnv>(
     });
 
     if (hasStubHeaders) {
-      // Clone and merge headers from stub into early response
+      // Clone and merge headers from stub into early response.
+      // Only fill in missing headers — the returned Response's explicit
+      // headers take precedence, matching executeMiddleware behavior.
       const mergedHeaders = new Headers(response.headers);
       stubResponse.headers.forEach((value, name) => {
         if (name.toLowerCase() === "set-cookie") {
           mergedHeaders.append(name, value);
-        } else {
+        } else if (!mergedHeaders.has(name)) {
           mergedHeaders.set(name, value);
         }
       });

package/src/router/pattern-matching.ts

@@ -140,7 +140,7 @@ export function compilePattern(pattern: string): CompiledPattern {
     } else if (segment.type === "param") {
       paramNames.push(segment.value);
       const valuePattern = segment.constraint
-        ? `(${segment.constraint.join("|")})`
+        ? `(${segment.constraint.map(escapeRegex).join("|")})`
         : "([^/]+)";
 
       if (segment.optional) {
@@ -388,6 +388,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 +422,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 +433,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 +458,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 +476,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 +497,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 +521,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();
@@ -121,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,
       ),
     };
 
@@ -138,6 +145,7 @@ export async function matchForPrerender<TEnv = any>(
         deps.mergedRouteMap,
         matched.routeKey,
         variables,
+        matchedPassthroughRoute,
       );
 
       // 7. Wire use() for handles only (loaders throw)
@@ -154,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);
@@ -176,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.
@@ -332,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,6 +137,9 @@ 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,
@@ -112,6 +150,7 @@ export async function evaluateRevalidation<TEnv>(
       // 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 +171,7 @@ export async function evaluateRevalidation<TEnv>(
         segmentId: segment.id,
       });
     }
+    pushTrace(defaultShouldRevalidate, defaultShouldRevalidate, defaultReason);
     return defaultShouldRevalidate;
   }
 
@@ -142,6 +182,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 +210,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 +228,7 @@ export async function evaluateRevalidation<TEnv>(
         revalidator: name,
         revalidate: result,
       });
+      pushTrace(defaultShouldRevalidate, result, `hard:${name}`);
       return result;
     } else if (
       result &&
@@ -206,5 +259,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;
 }