@rangojs/router 0.0.0-experimental.124 → 0.0.0-experimental.125

package/src/router/pattern-matching.ts

@@ -33,13 +33,6 @@ export interface ParsedSegment {
  */
 export function parsePattern(pattern: string): ParsedSegment[] {
   const segments: ParsedSegment[] = [];
-  // Match: /segment where segment can be:
-  // - static text
-  // - :param
-  // - :param?
-  // - :param(a|b)
-  // - :param(a|b)?
-  // - *
   const segmentRegex =
     /\/(:([a-zA-Z_][a-zA-Z0-9_]*)(\(([^)]+)\))?(\?)?([^/]*)|(\*)|([^/]+))/g;
 
@@ -183,7 +176,6 @@ export function compilePattern(pattern: string): CompiledPattern {
     }
   }
 
-  // Handle root path
   if (regexPattern === "") {
     regexPattern = "/";
   }
@@ -285,7 +277,6 @@ function buildParamsFromMatch(
 export function extractStaticPrefix(pattern: string): string {
   if (!pattern || pattern === "/") return "";
 
-  // Find the first occurrence of : or *
   const paramIndex = pattern.indexOf(":");
   const wildcardIndex = pattern.indexOf("*");
 
@@ -299,16 +290,13 @@ export function extractStaticPrefix(pattern: string): string {
   }
 
   if (cutIndex === -1) {
-    // No params or wildcards - entire pattern is static
     return pattern;
   }
 
   if (cutIndex === 0) {
-    // Pattern starts with : or * - no static prefix
     return "";
   }
 
-  // Find the last / before the param
   const lastSlash = pattern.lastIndexOf("/", cutIndex - 1);
   if (lastSlash === -1 || lastSlash === 0) {
     return "";
@@ -435,8 +423,6 @@ export function findMatch<TEnv>(
     : pathname + "/";
 
   for (const entry of routesEntries) {
-    // Short-circuit: skip entry if pathname doesn't start with static prefix
-    // staticPrefix is pre-computed at registration time, so this is O(1)
     if (entry.staticPrefix && !pathname.startsWith(entry.staticPrefix)) {
       if (effectiveDebug) {
         debugStats.entriesSkipped++;
@@ -448,8 +434,6 @@ export function findMatch<TEnv>(
       continue;
     }
 
-    // Check if this is a lazy entry that needs evaluation
-    // When staticPrefix matches but routes are not yet populated, signal caller to evaluate
     if (entry.lazy && !entry.lazyEvaluated) {
       if (effectiveDebug) {
         debugLog("findMatch", "lazy entry requires evaluation", {
@@ -470,7 +454,6 @@ export function findMatch<TEnv>(
         debugStats.routesChecked++;
       }
 
-      // Join prefix and pattern, handling edge cases
       let fullPattern: string;
       if (entry.prefix === "" || entry.prefix === "/") {
         fullPattern = pattern;
@@ -488,11 +471,9 @@ export function findMatch<TEnv>(
         constraints,
       } = getCompiledPattern(fullPattern);
 
-      // Get trailing slash mode for this route (per-route config or pattern-based)
       const trailingSlashMode: TrailingSlashMode | undefined =
         entry.trailingSlash?.[routeKey];
 
-      // Prerender flag from entry metadata (set by urls() for prerender handlers)
       const prFlag = entry.prerenderRouteKeys?.has(routeKey)
         ? { pr: true as const }
         : {};
@@ -500,13 +481,10 @@ export function findMatch<TEnv>(
         ? { pt: true as const }
         : {};
 
-      // Try exact match first
       const match = regex.exec(pathname);
       if (match) {
         const params = buildParamsFromMatch(match, paramNames);
 
-        // Validate constraints against decoded values; a failure falls
-        // through to the next route so other patterns can still match.
         if (!satisfiesConstraints(params, constraints)) {
           continue;
         }
@@ -519,13 +497,11 @@ export function findMatch<TEnv>(
           });
         }
 
-        // Check if trailing slash mode requires redirect even on exact match
         if (
           trailingSlashMode === "always" &&
           !pathnameHasTrailingSlash &&
           pathname !== "/"
         ) {
-          // Mode says always have trailing slash, but pathname doesn't have it
           return {
             entry,
             routeKey,
@@ -536,7 +512,6 @@ export function findMatch<TEnv>(
             ...ptFlag,
           };
         } else if (trailingSlashMode === "never" && pathnameHasTrailingSlash) {
-          // Mode says never have trailing slash, but pathname has it
           return {
             entry,
             routeKey,
@@ -558,7 +533,6 @@ export function findMatch<TEnv>(
         };
       }
 
-      // Try alternate pathname (opposite trailing slash)
       const altMatch = regex.exec(alternatePathname);
       if (altMatch) {
         const params = buildParamsFromMatch(altMatch, paramNames);
@@ -567,9 +541,7 @@ export function findMatch<TEnv>(
           continue;
         }
 
-        // Determine redirect behavior based on mode
         if (trailingSlashMode === "ignore") {
-          // Match without redirect
           return {
             entry,
             routeKey,
@@ -579,7 +551,6 @@ export function findMatch<TEnv>(
             ...ptFlag,
           };
         } else if (trailingSlashMode === "never") {
-          // Redirect to no trailing slash
           if (pathnameHasTrailingSlash) {
             return {
               entry,
@@ -600,7 +571,6 @@ export function findMatch<TEnv>(
             ...ptFlag,
           };
         } else if (trailingSlashMode === "always") {
-          // Redirect to with trailing slash
           if (!pathnameHasTrailingSlash) {
             return {
               entry,
@@ -621,8 +591,6 @@ export function findMatch<TEnv>(
             ...ptFlag,
           };
         } else {
-          // No explicit mode - use pattern-based detection
-          // Redirect to canonical form (what the pattern defines)
           const canonicalPath = hasTrailingSlash
             ? alternatePathname
             : pathname.slice(0, -1);
@@ -651,7 +619,7 @@ export function* traverseBack(entry: EntryData): Generator<EntryData> {
   let current: EntryData | null = entry;
   const items = [] as EntryData[];
   while (current !== null) {
-    items.push(current); // Move up to next parent
+    items.push(current);
     current = current.parent;
   }
   for (let i = items.length - 1; i >= 0; i--) {

package/src/router/prerender-match.ts

@@ -11,7 +11,7 @@ import {
   createStaticContext,
   createReverseFunction,
 } from "./handler-context.js";
-import { isPrerenderPassthrough } from "../prerender.js";
+import { detectPrerenderPassthrough } from "../prerender.js";
 import { isRouteRootScoped } from "../route-map-builder.js";
 import { setupBuildUse } from "./loader-resolution.js";
 import { loadManifest } from "./manifest.js";
@@ -82,6 +82,17 @@ export async function matchForPrerender<TEnv = any>(
   // Build RouterContext for loadManifest/traverseBack
   const routerCtx = deps.buildRouterContext();
 
+  // Passthrough sentinel result: an unknown-param Passthrough route falls
+  // through to the live handler at runtime, so no artifact is baked. A fresh
+  // object is returned per call (no site mutates or identity-compares it).
+  const passthroughResult = () => ({
+    segments: [],
+    handles: "",
+    routeName: matched.routeKey,
+    params: matchedParams,
+    passthrough: true as const,
+  });
+
   return runWithRouterContext(routerCtx, async () => {
     // 2. Load the manifest entry tree
     const manifestEntry = await loadManifest(
@@ -145,13 +156,7 @@ export async function matchForPrerender<TEnv = any>(
             );
           });
           if (!isKnown) {
-            return {
-              segments: [],
-              handles: "",
-              routeName: matched.routeKey,
-              params: matchedParams,
-              passthrough: true as const,
-            };
+            return passthroughResult();
           }
           // Preserve vars set by getParams() for the render context
           if (
@@ -165,13 +170,7 @@ export async function matchForPrerender<TEnv = any>(
           // Skip errors are intentional — treat as passthrough.
           // All other errors propagate so dev surfaces them.
           if (err?.name === "Skip") {
-            return {
-              segments: [],
-              handles: "",
-              routeName: matched.routeKey,
-              params: matchedParams,
-              passthrough: true as const,
-            };
+            return passthroughResult();
           }
           throw err;
         }
@@ -264,17 +263,13 @@ export async function matchForPrerender<TEnv = any>(
         { skipLoaders: true },
       );
 
-      // 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,
-          };
-        }
+      // 9. Detect passthrough sentinel: handler returned ctx.passthrough().
+      // When the route declares loading(), the handler result is deferred so the
+      // component is a thenable resolving to the sentinel — detectPrerenderPassthrough
+      // resolves thenables before testing (a sync check would miss it and bake a
+      // corrupt artifact).
+      if (await detectPrerenderPassthrough(allSegments)) {
+        return passthroughResult();
       }
 
       // 10. Filter out any loader segments (belt-and-suspenders)
@@ -319,24 +314,14 @@ export async function matchForPrerender<TEnv = any>(
       }[] = [];
       let current: EntryData | null = manifestEntry;
       while (current) {
-        if (current.intercept && current.intercept.length > 0) {
-          for (const ic of current.intercept) {
+        // Flatten the entry and its sibling layouts into one source list, the
+        // same traversal findInterceptForRoute uses; the build keeps ALL matches
+        // (not just the innermost) and skips when(). intercept/layout are
+        // non-optional arrays, so empty ones are a no-op here.
+        for (const source of [current, ...current.layout]) {
+          for (const ic of source.intercept) {
             if (ic.routeName === matched.routeKey) {
-              foundIntercepts.push({ intercept: ic, entry: current });
-            }
-          }
-        }
-        if (current.layout && current.layout.length > 0) {
-          for (const siblingLayout of current.layout) {
-            if (siblingLayout.intercept && siblingLayout.intercept.length > 0) {
-              for (const ic of siblingLayout.intercept) {
-                if (ic.routeName === matched.routeKey) {
-                  foundIntercepts.push({
-                    intercept: ic,
-                    entry: siblingLayout,
-                  });
-                }
-              }
+              foundIntercepts.push({ intercept: ic, entry: source });
             }
           }
         }
@@ -503,14 +488,13 @@ export async function renderStaticSegment<TEnv = any>(
     setupBuildUse(buildCtx);
 
     const raw = await handler(buildCtx);
-    const component = raw?.type ? raw : raw;
 
     const segment: ResolvedSegment = {
       id: handlerId,
       namespace: handlerId,
       type: "layout",
       index: 0,
-      component,
+      component: raw,
       params: {},
       belongsToRoute: false,
     };

package/src/router/request-classification.ts

@@ -23,10 +23,6 @@ import { negotiateRoute } from "./content-negotiation.js";
 import { stripInternalParams } from "./handler-context.js";
 import { resolveRoute, type RouteSnapshot } from "./route-snapshot.js";
 
-// ---------------------------------------------------------------------------
-// RequestPlan — discriminated union
-// ---------------------------------------------------------------------------
-
 interface RedirectPlan<TEnv = any> {
   mode: "redirect";
   route: RouteSnapshot<TEnv>;
@@ -124,10 +120,6 @@ export type {
   PartialRenderPlan,
 };
 
-// ---------------------------------------------------------------------------
-// classifyRequest — the single authoritative classification step
-// ---------------------------------------------------------------------------
-
 export interface ClassifyRequestDeps<TEnv = any> {
   findMatch: (pathname: string) => RouteMatchResult<TEnv> | null;
   routerVersion: string;
@@ -157,15 +149,12 @@ export async function classifyRequest<TEnv = any>(
   const isAction =
     request.headers.has("rsc-action") || url.searchParams.has("_rsc_action");
 
-  // Version mismatch — runs BEFORE route resolution so stale clients
-  // requesting removed routes get a reload, not a 404.
   const clientVersion = url.searchParams.get("_rsc_v");
   if (
     deps.routerVersion &&
     clientVersion &&
     clientVersion !== deps.routerVersion
   ) {
-    // Strip internal _rsc_* params so the browser reloads to a clean URL
     let reloadUrl = stripInternalParams(url).toString();
     if (isAction) {
       const referer = request.headers.get("referer");
@@ -175,9 +164,7 @@ export async function classifyRequest<TEnv = any>(
           if (refererUrl.origin === url.origin) {
             reloadUrl = referer;
           }
-        } catch {
-          // Malformed referer, fall back to stripped url
-        }
+        } catch {}
       }
     }
 
@@ -187,18 +174,6 @@ export async function classifyRequest<TEnv = any>(
     };
   }
 
-  // App switch — also runs BEFORE route resolution (like version-mismatch
-  // above), and for the same reason: a cross-app SPA navigation must reload
-  // even when the target route does NOT exist in the target app. If we resolved
-  // first, a missing route would throw RouteNotFoundError and the 404 would
-  // render in-place under the SOURCE app's document — violating the invariant
-  // that crossing a host-router app boundary is always a full document load.
-  // A mismatched routerId (_rsc_rid) means the navigation crossed an app
-  // boundary; force a real document navigation. A soft swap can't faithfully
-  // re-establish the target app's document (stylesheets shared across apps are
-  // dropped by React 19's by-href dedup; theme/warmup/prefetch-TTL are
-  // document-lifetime — see browser/app-shell.ts). Only SPA (`_rsc_partial`)
-  // requests need this; a direct full load already IS the document navigation.
   const clientRouterId = url.searchParams.get("_rsc_rid");
   if (
     clientRouterId &&
@@ -211,9 +186,6 @@ export async function classifyRequest<TEnv = any>(
     };
   }
 
-  // No metricsStore — classification is a lightweight gating step.
-  // Route-matching and manifest-loading metrics belong in the match path
-  // (createMatchContextForFull/Partial) which runs the authoritative resolution.
   const result = await resolveRoute<TEnv>(pathname, {
     findMatch: deps.findMatch,
     lite: true,
@@ -225,7 +197,6 @@ export async function classifyRequest<TEnv = any>(
     });
   }
 
-  // Redirect
   if (result.type === "redirect") {
     const snapshot: RouteSnapshot<TEnv> = {
       matched: result as any,
@@ -247,7 +218,6 @@ export async function classifyRequest<TEnv = any>(
 
   const snapshot = result.snapshot;
 
-  // Response route — non-RSC short-circuit (JSON, streaming, etc.)
   const responseResult = await classifyResponseRoute(
     request,
     pathname,
@@ -257,7 +227,6 @@ export async function classifyRequest<TEnv = any>(
     return responseResult;
   }
 
-  // Mode detection from request signals
   const actionId =
     request.headers.get("rsc-action") || url.searchParams.get("_rsc_action");
   const isLoaderFetch = url.searchParams.has("_rsc_loader");
@@ -275,7 +244,6 @@ export async function classifyRequest<TEnv = any>(
     return { mode: "loader", route: snapshot };
   }
 
-  // PE detection: POST with form content-type, but not a server action
   const contentType = request.headers.get("content-type") || "";
   const isFormSubmission =
     contentType.includes("multipart/form-data") ||
@@ -291,10 +259,6 @@ export async function classifyRequest<TEnv = any>(
   return { mode: "full-render", route: snapshot, negotiated };
 }
 
-// ---------------------------------------------------------------------------
-// Content negotiation for response routes
-// ---------------------------------------------------------------------------
-
 /**
  * Check if the route is a response route and perform content negotiation
  * if negotiate variants exist. Returns a ResponseRoutePlan if the route
@@ -305,7 +269,6 @@ async function classifyResponseRoute<TEnv>(
   pathname: string,
   snapshot: RouteSnapshot<TEnv>,
 ): Promise<ResponseRoutePlan<TEnv> | null> {
-  // negotiateRoute returns the response plan (variant or plain) or null for RSC.
   const negotiation = await negotiateRoute(request, pathname, snapshot);
   return negotiation
     ? { mode: "response", route: snapshot, ...negotiation }

package/src/router/revalidation.ts

@@ -14,6 +14,7 @@ import {
 import type { RevalidationTraceEntry } from "./logging.js";
 import { _getRequestContext } from "../server/request-context.js";
 import { isAutoGeneratedRouteName } from "../route-name.js";
+import { paramsEqual } from "./params-util.js";
 
 /**
  * Resolve a server-action reference's stable id, mirroring how the action
@@ -56,22 +57,6 @@ function makeIsAction(
   };
 }
 
-function paramsEqual(
-  a: Record<string, string>,
-  b: Record<string, string>,
-): boolean {
-  if (a === b) return true;
-
-  const keysA = Object.keys(a);
-  if (keysA.length !== Object.keys(b).length) return false;
-
-  for (const key of keysA) {
-    if (a[key] !== b[key]) return false;
-  }
-
-  return true;
-}
-
 /**
  * Options for revalidation evaluation
  */
@@ -136,8 +121,6 @@ export async function evaluateRevalidation<TEnv>(
   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,
@@ -156,43 +139,28 @@ export async function evaluateRevalidation<TEnv>(
     });
   }
 
-  // Calculate default revalidation based on segment type and request method
   let defaultShouldRevalidate: boolean;
   let defaultReason: string;
 
   if (defaultOverride) {
-    // Caller injected the seed (e.g. parallel slot not in clientSegmentIds).
-    // Skip the type-derived heuristic — caller knows better in this context.
     defaultShouldRevalidate = defaultOverride.value;
     defaultReason = defaultOverride.reason;
   } else 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 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
@@ -208,8 +176,6 @@ export async function evaluateRevalidation<TEnv>(
         });
       }
     } 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"
@@ -221,9 +187,6 @@ export async function evaluateRevalidation<TEnv>(
         searchChanged,
       });
     } else {
-      // 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", {
@@ -233,7 +196,6 @@ export async function evaluateRevalidation<TEnv>(
     }
   }
 
-  // No custom revalidations defined - return default behavior without prev segment
   if (revalidations.length === 0) {
     if (defaultShouldRevalidate) {
       debugLog("revalidation", "default revalidate=true", {
@@ -250,14 +212,10 @@ export async function evaluateRevalidation<TEnv>(
     return defaultShouldRevalidate;
   }
 
-  // Custom revalidations exist - may need full prev segment
-  // Lazy load prev segment only if getPrevSegment provided
   const prevSegment = getPrevSegment ? await getPrevSegment() : null;
 
-  // 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();
@@ -285,20 +243,14 @@ export async function evaluateRevalidation<TEnv>(
       actionUrl: actionContext?.actionUrl,
       actionResult: actionContext?.actionResult,
       formData: actionContext?.formData,
-      method: request.method, // GET for navigation, POST for actions
-      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)
+      method: request.method,
+      routeName: toRouteName,
+      fromRouteName,
+      toRouteName,
       stale,
     });
 
-    // Check return type:
-    // - boolean: hard decision, short-circuit immediately
-    // - { defaultShouldRevalidate: boolean }: soft decision, update suggestion and continue
-    // - null/undefined: use default behavior (equivalent to returning { defaultShouldRevalidate })
     if (typeof result === "boolean") {
-      // Hard decision - short-circuit
       debugLog("revalidation", "hard decision", {
         segmentId: segment.id,
         revalidator: name,
@@ -311,7 +263,6 @@ export async function evaluateRevalidation<TEnv>(
       typeof result === "object" &&
       "defaultShouldRevalidate" in result
     ) {
-      // Soft decision - update suggestion and continue
       currentSuggestion = result.defaultShouldRevalidate;
       debugLog("revalidation", "soft decision", {
         segmentId: segment.id,
@@ -319,18 +270,14 @@ export async function evaluateRevalidation<TEnv>(
         revalidate: currentSuggestion,
       });
     } else if (result === null || result === undefined) {
-      // Defer to default - equivalent to { defaultShouldRevalidate: currentSuggestion }
-      // This means "I don't care, use whatever the default is"
       debugLog("revalidation", "deferred to current default", {
         segmentId: segment.id,
         revalidator: name,
         revalidate: currentSuggestion,
       });
-      // currentSuggestion stays the same, continue to next function
     }
   }
 
-  // All revalidators completed - use final suggestion
   debugLog("revalidation", "final decision", {
     segmentId: segment.id,
     revalidate: currentSuggestion,