@rangojs/router 0.0.0-experimental.760a71d9 → 0.0.0-experimental.78

package/src/router/match-api.ts

@@ -36,7 +36,14 @@ import {
   setRequestContextPrevRouteKey,
 } from "../server/request-context.js";
 import { isAutoGeneratedRouteName } from "../route-name.js";
+import type { DefaultRouteName } from "../types/global-namespace.js";
 import { debugLog, debugWarn } from "./logging.js";
+import {
+  resolveRoute,
+  ensureFullRouteSnapshot,
+  type RouteSnapshot,
+} from "./route-snapshot.js";
+import { resolveNavigation } from "./navigation-snapshot.js";
 
 /**
  * Create match context for full requests (document/SSR).
@@ -52,57 +59,36 @@ export async function createMatchContextForFull<TEnv>(
 
   const metricsStore = deps.getMetricsStore();
 
-  const routeMatchStart = metricsStore ? performance.now() : 0;
-  const matched = deps.findMatch(pathname, metricsStore);
-  if (metricsStore) {
-    metricsStore.metrics.push({
-      label: "route-matching",
-      duration: performance.now() - routeMatchStart,
-      startTime: routeMatchStart - metricsStore.requestStart,
-    });
-  }
+  // Full renders always resolve fresh with isSSR: true because loadManifest
+  // keys its cache on isSSR and stamps Store.isSSR for downstream behavior.
+  const result = await resolveRoute<TEnv>(pathname, {
+    findMatch: (p) => deps.findMatch(p, metricsStore),
+    metricsStore,
+    isSSR: true,
+  });
 
-  if (!matched) {
+  if (!result) {
     throw new RouteNotFoundError(`No route matched for ${pathname}`, {
       cause: { pathname, method: request.method },
     });
   }
 
-  if (matched.redirectTo) {
+  if (result.type === "redirect") {
     return {
       type: "redirect",
-      redirectUrl: matched.redirectTo + url.search,
+      redirectUrl: result.redirectTo + url.search,
     };
   }
 
-  const manifestStart = metricsStore ? performance.now() : 0;
-  const manifestEntry = await loadManifest(
-    matched.entry,
-    matched.routeKey,
-    pathname,
-    metricsStore,
-    true,
-  );
-  if (metricsStore) {
-    metricsStore.metrics.push({
-      label: "manifest-loading",
-      duration: performance.now() - manifestStart,
-      startTime: manifestStart - metricsStore.requestStart,
-    });
-  }
+  const snapshot = result.snapshot;
 
-  if (
-    manifestEntry.type === "route" &&
-    manifestEntry.prerenderDef?.options?.passthrough === true
-  ) {
+  const { matched } = snapshot;
+
+  // Backward compat: downstream middleware reads matched.pt
+  if (snapshot.isPassthrough) {
     matched.pt = true;
   }
 
-  const routeMiddleware = collectRouteMiddleware(
-    traverseBack(manifestEntry),
-    matched.params,
-  );
-
   // Clean URL without internal _rsc* params for userland access
   const cleanUrl = stripInternalParams(url);
 
@@ -134,14 +120,6 @@ export async function createMatchContextForFull<TEnv>(
     Store.metrics = metricsStore;
   }
 
-  const entries = [...traverseBack(manifestEntry)];
-  let cacheScope: CacheScope | null = null;
-  for (const entry of entries) {
-    if (entry.cache) {
-      cacheScope = createCacheScope(entry.cache, cacheScope);
-    }
-  }
-
   return {
     request,
     url: cleanUrl,
@@ -154,12 +132,10 @@ export async function createMatchContextForFull<TEnv>(
     prevParams: {},
     prevMatch: null,
     matched,
-    manifestEntry,
-    entries,
+    manifestEntry: snapshot.manifestEntry,
+    entries: snapshot.entries,
     routeKey: matched.routeKey,
-    localRouteName: matched.routeKey.includes(".")
-      ? matched.routeKey.split(".").pop()!
-      : matched.routeKey,
+    localRouteName: snapshot.localRouteName,
     handlerContext,
     loaderPromises,
     routeMap: deps.getRouteMap(),
@@ -175,16 +151,16 @@ export async function createMatchContextForFull<TEnv>(
       segments: { path: [], ids: [] },
       toRouteName:
         matched.routeKey && !isAutoGeneratedRouteName(matched.routeKey)
-          ? matched.routeKey
+          ? (matched.routeKey as DefaultRouteName)
           : undefined,
     },
     isSameRouteNavigation: false,
     interceptResult: null,
-    cacheScope,
+    cacheScope: snapshot.cacheScope,
     isIntercept: false,
     actionContext: undefined,
     isAction: false,
-    routeMiddleware,
+    routeMiddleware: snapshot.routeMiddleware,
     isFullMatch: true,
   };
 }
@@ -204,103 +180,85 @@ export async function createMatchContextForPartial<TEnv>(
 
   const metricsStore = deps.getMetricsStore();
 
-  const clientSegmentIds =
-    url.searchParams.get("_rsc_segments")?.split(",").filter(Boolean) || [];
-  const stale = url.searchParams.get("_rsc_stale") === "true";
-  const previousUrl =
-    request.headers.get("X-RSC-Router-Client-Path") ||
-    request.headers.get("Referer");
-  const interceptSourceUrl = request.headers.get(
-    "X-RSC-Router-Intercept-Source",
-  );
+  const isHmr = !!request.headers.get("X-RSC-HMR");
 
   // HMR: clear manifest cache so stale handler references are discarded
-  if (request.headers.get("X-RSC-HMR")) {
+  if (isHmr) {
     clearManifestCache();
   }
 
-  if (!previousUrl) {
-    return null;
-  }
-
-  let prevUrl: URL;
-  try {
-    prevUrl = new URL(previousUrl, url.origin);
-  } catch {
-    return null;
-  }
+  // Reuse the classified snapshot when available and not invalidated by HMR.
+  // classifyRequest already called resolveRoute(lite) with isSSR=false, which
+  // matches the partial path. On HMR, discard to pick up manifest changes.
+  const classifiedRoute = isHmr
+    ? undefined
+    : getRequestContext()?._classifiedRoute;
+
+  // Time route matching. On the reuse path, only nav findMatch calls are new
+  // (current-route findMatch and manifest-loading were already timed during
+  // classifyRequest via its metricsStore). On the fresh path, all findMatch
+  // calls are measured together.
+  const routeMatchStart = metricsStore ? performance.now() : 0;
 
-  let interceptContextUrl: URL;
-  try {
-    interceptContextUrl = interceptSourceUrl
-      ? new URL(interceptSourceUrl, url.origin)
-      : prevUrl;
-  } catch {
-    interceptContextUrl = prevUrl;
-  }
+  let snapshot: RouteSnapshot<TEnv>;
+  if (classifiedRoute && classifiedRoute.manifestEntry) {
+    snapshot = ensureFullRouteSnapshot(classifiedRoute);
+  } else {
+    const result = await resolveRoute<TEnv>(pathname, {
+      findMatch: (p) => deps.findMatch(p, metricsStore),
+      metricsStore,
+      isSSR: false,
+      skipRouteMatchMetric: true,
+    });
 
-  const routeMatchStart = metricsStore ? performance.now() : 0;
-  const prevMatch = deps.findMatch(prevUrl.pathname);
-  const prevParams = prevMatch?.params || {};
-  const interceptContextMatch = interceptSourceUrl
-    ? deps.findMatch(interceptContextUrl.pathname)
-    : prevMatch;
+    if (!result) {
+      throw new RouteNotFoundError(`No route matched for ${pathname}`, {
+        cause: { pathname, method: request.method },
+      });
+    }
 
-  const matched = deps.findMatch(pathname, metricsStore);
+    if (result.type === "redirect") {
+      return null;
+    }
 
-  if (metricsStore) {
-    metricsStore.metrics.push({
-      label: "route-matching",
-      duration: performance.now() - routeMatchStart,
-      startTime: routeMatchStart - metricsStore.requestStart,
-    });
+    snapshot = result.snapshot;
   }
 
-  if (!matched) {
-    throw new RouteNotFoundError(`No route matched for ${pathname}`, {
-      cause: { pathname, method: request.method, previousUrl },
-    });
-  }
+  const { matched } = snapshot;
 
-  if (matched.redirectTo) {
-    return null;
+  // Backward compat: downstream middleware reads matched.pt
+  if (snapshot.isPassthrough) {
+    matched.pt = true;
   }
 
-  if (prevMatch && prevMatch.entry !== matched.entry && !matched.pr) {
-    debugLog("matchPartial", "route group changed", {
-      from: prevMatch.routeKey,
-      to: matched.routeKey,
-    });
+  // Navigation state (prev + intercept-source findMatch calls)
+  const nav = resolveNavigation(request, url, matched.routeKey, {
+    findMatch: deps.findMatch,
+  });
+  if (!nav) {
+    return null;
   }
 
-  const manifestStart = metricsStore ? performance.now() : 0;
-  const manifestEntry = await loadManifest(
-    matched.entry,
-    matched.routeKey,
-    pathname,
-    metricsStore,
-    false,
-  );
+  // Push route-matching metric. On the fresh path this covers all findMatch
+  // calls (current + prev + intercept-source). On the reuse path, current-route
+  // findMatch was already timed during classification, so this only covers
+  // the nav lookups (prev + intercept-source).
   if (metricsStore) {
+    const isReuse = !!classifiedRoute;
     metricsStore.metrics.push({
-      label: "manifest-loading",
-      duration: performance.now() - manifestStart,
-      startTime: manifestStart - metricsStore.requestStart,
+      label: isReuse ? "route-matching:nav" : "route-matching",
+      duration: performance.now() - routeMatchStart,
+      startTime: routeMatchStart - metricsStore.requestStart,
     });
   }
 
-  if (
-    manifestEntry.type === "route" &&
-    manifestEntry.prerenderDef?.options?.passthrough === true
-  ) {
-    matched.pt = true;
+  if (nav.prevMatch && nav.prevMatch.entry !== matched.entry && !matched.pr) {
+    debugLog("matchPartial", "route group changed", {
+      from: nav.prevMatch.routeKey,
+      to: matched.routeKey,
+    });
   }
 
-  const routeMiddleware = collectRouteMiddleware(
-    traverseBack(manifestEntry),
-    matched.params,
-  );
-
   // Clean URL without internal _rsc* params for userland access
   const cleanUrl = stripInternalParams(url);
 
@@ -317,9 +275,8 @@ export async function createMatchContextForPartial<TEnv>(
     matched.pt === true,
   );
 
-  const clientSegmentSet = new Set(clientSegmentIds);
   debugLog("matchPartial", "client segments", {
-    segments: Array.from(clientSegmentSet),
+    segments: Array.from(nav.clientSegmentSet),
   });
 
   const loaderPromises = new Map<string, Promise<any>>();
@@ -337,100 +294,78 @@ export async function createMatchContextForPartial<TEnv>(
     Store.metrics = metricsStore;
   }
 
-  const isSameRouteNavigation = !!(
-    interceptContextMatch && interceptContextMatch.routeKey === matched.routeKey
-  );
-
-  if (interceptSourceUrl) {
+  if (nav.hasInterceptSource) {
     debugLog("matchPartial.intercept", "intercept context detected", {
       currentUrl: pathname,
-      interceptSource: interceptSourceUrl,
-      contextRoute: interceptContextMatch?.routeKey,
+      interceptSource: nav.interceptContextUrl.href,
+      contextRoute: nav.interceptContextMatch?.routeKey,
       currentRoute: matched.routeKey,
-      sameRouteNavigation: isSameRouteNavigation,
+      sameRouteNavigation: nav.isSameRouteNavigation,
     });
   }
 
-  const localRouteName = matched.routeKey.includes(".")
-    ? matched.routeKey.split(".").pop()!
-    : matched.routeKey;
-
-  const filteredSegmentIds = clientSegmentIds.filter((id) => {
-    if (id.includes(".@")) return false;
-    if (/D\d+\./.test(id)) return false;
-    return true;
-  });
-  const effectiveFromUrl = interceptSourceUrl ? interceptContextUrl : prevUrl;
-  const effectiveFromMatch = interceptSourceUrl
-    ? interceptContextMatch
-    : prevMatch;
-
   // Store previous route key on the request context for revalidation
   // fromRouteName. Uses effectiveFromMatch so intercept-source navigations
   // see the intercept origin route, not the plain previous URL route.
-  setRequestContextPrevRouteKey(effectiveFromMatch?.routeKey);
+  setRequestContextPrevRouteKey(nav.effectiveFromMatch?.routeKey);
 
   const interceptSelectorContext: InterceptSelectorContext = {
-    from: effectiveFromUrl,
+    from: nav.effectiveFromUrl,
     to: cleanUrl,
     params: matched.params,
     request,
     env,
     segments: {
-      path: effectiveFromUrl.pathname.split("/").filter(Boolean),
-      ids: filteredSegmentIds,
+      path: nav.effectiveFromUrl.pathname.split("/").filter(Boolean),
+      ids: nav.filteredSegmentIds,
     },
     fromRouteName:
-      effectiveFromMatch?.routeKey &&
-      !isAutoGeneratedRouteName(effectiveFromMatch.routeKey)
-        ? effectiveFromMatch.routeKey
+      nav.effectiveFromMatch?.routeKey &&
+      !isAutoGeneratedRouteName(nav.effectiveFromMatch.routeKey)
+        ? (nav.effectiveFromMatch.routeKey as DefaultRouteName)
         : undefined,
     toRouteName:
       matched.routeKey && !isAutoGeneratedRouteName(matched.routeKey)
-        ? matched.routeKey
+        ? (matched.routeKey as DefaultRouteName)
         : undefined,
   };
   const isAction = !!actionContext;
 
-  const clientHasInterceptSegments = [...clientSegmentSet].some((id) =>
+  const clientHasInterceptSegments = [...nav.clientSegmentSet].some((id) =>
     id.includes(".@"),
   );
   const skipInterceptForAction = isAction && !clientHasInterceptSegments;
   const interceptResult =
-    isSameRouteNavigation || skipInterceptForAction
+    nav.isSameRouteNavigation || skipInterceptForAction
       ? null
       : findInterceptForRoute(
           matched.routeKey,
-          manifestEntry.parent,
+          snapshot.manifestEntry.parent,
           interceptSelectorContext,
           isAction,
         ) ||
-        (localRouteName !== matched.routeKey
+        (snapshot.localRouteName !== matched.routeKey
           ? findInterceptForRoute(
-              localRouteName,
-              manifestEntry.parent,
+              snapshot.localRouteName,
+              snapshot.manifestEntry.parent,
               interceptSelectorContext,
               isAction,
             )
           : null);
 
+  // Make a mutable copy of clientSegmentSet so we can delete entries
+  // for same-route navigation forcing
+  const clientSegmentSet = new Set(nav.clientSegmentSet);
+
   if (
-    isSameRouteNavigation &&
-    manifestEntry.type === "route" &&
-    interceptSourceUrl
+    nav.isSameRouteNavigation &&
+    snapshot.manifestEntry.type === "route" &&
+    nav.hasInterceptSource
   ) {
     debugLog("matchPartial.intercept", "forcing route segment render", {
-      segmentId: manifestEntry.shortCode,
+      segmentId: snapshot.manifestEntry.shortCode,
     });
-    clientSegmentSet.delete(manifestEntry.shortCode);
-  }
-
-  const entries = [...traverseBack(manifestEntry)];
-  let cacheScope: CacheScope | null = null;
-  for (const entry of entries) {
-    if (entry.cache) {
-      cacheScope = createCacheScope(entry.cache, cacheScope);
-    }
+    clientSegmentSet.delete(snapshot.manifestEntry.shortCode);
   }
 
   const isIntercept = !!interceptResult;
@@ -440,31 +375,31 @@ export async function createMatchContextForPartial<TEnv>(
     url: cleanUrl,
     pathname,
     env,
-    clientSegmentIds,
+    clientSegmentIds: nav.clientSegmentIds,
     clientSegmentSet,
-    stale,
-    prevUrl,
-    prevParams,
-    prevMatch,
+    stale: nav.stale,
+    prevUrl: nav.prevUrl,
+    prevParams: nav.prevParams,
+    prevMatch: nav.prevMatch,
     matched,
-    manifestEntry,
-    entries,
+    manifestEntry: snapshot.manifestEntry,
+    entries: snapshot.entries,
     routeKey: matched.routeKey,
-    localRouteName,
+    localRouteName: snapshot.localRouteName,
     handlerContext,
     loaderPromises,
     routeMap: deps.getRouteMap(),
     metricsStore,
     Store,
-    interceptContextMatch,
+    interceptContextMatch: nav.interceptContextMatch,
     interceptSelectorContext,
-    isSameRouteNavigation,
+    isSameRouteNavigation: nav.isSameRouteNavigation,
     interceptResult,
-    cacheScope,
+    cacheScope: snapshot.cacheScope,
     isIntercept,
     actionContext,
     isAction,
-    routeMiddleware,
+    routeMiddleware: snapshot.routeMiddleware,
     isFullMatch: false,
   };
 }

package/src/router/match-middleware/background-revalidation.ts

@@ -149,6 +149,13 @@ export function withBackgroundRevalidation<TEnv>(
       : undefined;
 
     requestCtx?.waitUntil(async () => {
+      // Prevent background metrics from polluting foreground timeline.
+      // The foreground uses its own metricsStore reference directly (via
+      // appendMetric), so nulling Store.metrics only affects track() calls
+      // inside this background Store.run() scope.
+      const savedMetrics = ctx.Store.metrics;
+      ctx.Store.metrics = undefined;
+
       const start = performance.now();
       debugLog("backgroundRevalidation", "revalidating stale route", {
         pathname: ctx.pathname,
@@ -179,7 +186,9 @@ export function withBackgroundRevalidation<TEnv>(
         setupLoaderAccess(freshHandlerContext, freshLoaderPromises);
 
         // Resolve all segments fresh (without revalidation logic)
-        // to ensure complete components for caching
+        // to ensure complete components for caching.
+        // Skip DSL loaders — they are never cached (cacheRoute filters them)
+        // and are always resolved fresh on each request.
         const freshSegments = await ctx.Store.run(() =>
           resolveAllSegments(
             ctx.entries,
@@ -187,6 +196,7 @@ export function withBackgroundRevalidation<TEnv>(
             ctx.matched.params,
             freshHandlerContext,
             freshLoaderPromises,
+            { skipLoaders: true },
           ),
         );
 
@@ -234,6 +244,7 @@ export function withBackgroundRevalidation<TEnv>(
         });
       } finally {
         requestCtx._handleStore = originalHandleStore;
+        ctx.Store.metrics = savedMetrics;
       }
     });
   };

package/src/router/match-middleware/cache-lookup.ts

@@ -96,6 +96,7 @@ import type { MatchContext, MatchPipelineState } from "../match-context.js";
 import { getRouterContext } from "../router-context.js";
 import { resolveSink, safeEmit } from "../telemetry.js";
 import { pushRevalidationTraceEntry, isTraceActive } from "../logging.js";
+import { treeHasStreaming } from "./segment-resolution.js";
 import type { PrerenderStore, PrerenderEntry } from "../../prerender/store.js";
 import type { HandleStore } from "../../server/handle-store.js";
 import {
@@ -193,6 +194,16 @@ async function* yieldFromStore<TEnv>(
   state.cachedSegments = segments;
   state.cachedMatchedIds = segments.map((s) => s.id);
 
+  // Set streaming flag (once) and resolve render barrier.
+  const reqCtx = handleStoreRef ? undefined : _lazyGetRequestContext?.();
+  const barrierReqCtx = reqCtx ?? _getRequestContext();
+  if (barrierReqCtx) {
+    if (barrierReqCtx._treeHasStreaming === undefined) {
+      barrierReqCtx._treeHasStreaming = treeHasStreaming(ctx.entries);
+    }
+    barrierReqCtx._resolveRenderBarrier(segments);
+  }
+
   // For partial navigation, nullify components the client already has
   // so parent layouts stay live (client keeps its existing versions).
   // When params changed (e.g., different guide slug), the segments have
@@ -240,6 +251,7 @@ async function* yieldFromStore<TEnv>(
           ctx.url,
           ctx.routeKey,
           ctx.actionContext,
+          ctx.stale || undefined,
         ),
       );
       state.matchedIds = [
@@ -316,14 +328,15 @@ export function withCacheLookup<TEnv>(
 
     // Prerender lookup: check build-time cached data before runtime cache.
     // Prerender data is available regardless of runtime cache configuration.
-    if (!ctx.isAction && ctx.matched.pr) {
+    // Skip for HMR requests — the dev prerender endpoint reads from a stale
+    // RouterRegistry snapshot; rendering fresh ensures edits are visible.
+    const isHmr = !!ctx.request.headers.get("X-RSC-HMR");
+    if (!ctx.isAction && !isHmr && ctx.matched.pr) {
       await ensurePrerenderDeps();
       if (prerenderStoreInstance) {
         const paramHash = _hashParams!(ctx.matched.params);
         const isPassthroughPrerenderRoute = ctx.entries.some(
-          (entry) =>
-            entry.type === "route" &&
-            entry.prerenderDef?.options?.passthrough === true,
+          (entry) => entry.type === "route" && entry.isPassthrough === true,
         );
 
         if (ctx.isIntercept) {
@@ -393,9 +406,7 @@ export function withCacheLookup<TEnv>(
         if (prerenderStoreInstance) {
           const paramHash = _hashParams!(ctx.matched.params);
           const isPassthroughPrerenderRoute = ctx.entries.some(
-            (entry) =>
-              entry.type === "route" &&
-              entry.prerenderDef?.options?.passthrough === true,
+            (entry) => entry.type === "route" && entry.isPassthrough === true,
           );
 
           if (ctx.isIntercept) {
@@ -522,18 +533,23 @@ export function withCacheLookup<TEnv>(
       const entryInfo = entryRevalidateMap?.get(segment.id);
 
       // Even without explicit revalidation rules, route segments and their
-      // children must re-render when search params change — the handler reads
-      // ctx.searchParams so different ?page= values produce different content.
+      // children must re-render when params or search params change — the
+      // handler reads ctx.params/ctx.searchParams so different values produce
+      // different content. Matches evaluateRevalidation's default logic.
       const searchChanged = ctx.prevUrl.search !== ctx.url.search;
+      const routeParamsChanged = !paramsEqual(
+        ctx.matched.params,
+        ctx.prevParams,
+      );
       const shouldDefaultRevalidate =
-        searchChanged &&
+        (searchChanged || routeParamsChanged) &&
         (segment.type === "route" ||
           (segment.belongsToRoute &&
             (segment.type === "layout" || segment.type === "parallel")));
 
       if (!entryInfo || entryInfo.revalidate.length === 0) {
         if (shouldDefaultRevalidate) {
-          // Search params changed — must re-render even without custom rules
+          // Params or search params changed — must re-render even without custom rules
           if (isTraceActive()) {
             pushRevalidationTraceEntry({
               segmentId: segment.id,
@@ -542,7 +558,9 @@ export function withCacheLookup<TEnv>(
               source: "cache-hit",
               defaultShouldRevalidate: true,
               finalShouldRevalidate: true,
-              reason: "cached-search-changed",
+              reason: routeParamsChanged
+                ? "cached-params-changed"
+                : "cached-search-changed",
             });
           }
           yield segment;
@@ -581,7 +599,7 @@ export function withCacheLookup<TEnv>(
         routeKey: ctx.routeKey,
         context: ctx.handlerContext,
         actionContext: ctx.actionContext,
-        stale: cacheResult.shouldRevalidate || undefined,
+        stale: cacheResult.shouldRevalidate || ctx.stale || undefined,
         traceSource: "cache-hit",
       });
 
@@ -608,6 +626,15 @@ export function withCacheLookup<TEnv>(
       yield segment;
     }
 
+    // Set streaming flag (once) and resolve render barrier.
+    const barrierReqCtx = _getRequestContext();
+    if (barrierReqCtx) {
+      if (barrierReqCtx._treeHasStreaming === undefined) {
+        barrierReqCtx._treeHasStreaming = treeHasStreaming(ctx.entries);
+      }
+      barrierReqCtx._resolveRenderBarrier(cacheResult.segments);
+    }
+
     // Resolve loaders fresh (loaders are NOT cached by default)
     // This ensures fresh data even on cache hit
     const Store = ctx.Store;