@rangojs/router 0.0.0-experimental.35 → 0.0.0-experimental.358c376d

package/src/router/match-api.ts

@@ -1,11 +1,8 @@
-/**
- * Match API
- *
- * Extracted from createRouter closure. Contains match context creation functions
- * and the matchError function for error boundary resolution.
- */
-
-import { CacheScope, createCacheScope } from "../cache/cache-scope.js";
+import {
+  CacheScope,
+  createCacheScope,
+  resolveShellImplicitCacheScope,
+} from "../cache/cache-scope.js";
 import { RouteNotFoundError } from "../errors";
 import {
   createErrorInfo,
@@ -22,10 +19,10 @@ import { collectRouteMiddleware } from "./middleware.js";
 import { traverseBack } from "./pattern-matching.js";
 import { DefaultErrorFallback } from "../default-error-boundary.js";
 import {
-  EntryData,
-  LoaderEntry,
+  type EntryData,
+  type LoaderEntry,
   getContext,
-  InterceptSelectorContext,
+  type InterceptSelectorContext,
 } from "../server/context";
 import type { ErrorBoundaryHandler, ErrorInfo, MatchResult } from "../types";
 import type { ReactNode } from "react";
@@ -33,10 +30,18 @@ import type { MatchContext } from "./match-context.js";
 import type { MatchApiDeps, ActionContext } from "./types.js";
 import {
   getRequestContext,
+  _getRequestContext,
   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).
@@ -47,64 +52,73 @@ export async function createMatchContextForFull<TEnv>(
   deps: MatchApiDeps<TEnv>,
   findInterceptForRoute: MatchApiDeps<TEnv>["findInterceptForRoute"],
 ): Promise<MatchContext<TEnv> | { type: "redirect"; redirectUrl: string }> {
-  const url = new URL(request.url);
-  const pathname = url.pathname;
+  const reqCtx = _getRequestContext();
+  const cleanUrl = reqCtx?.url ?? stripInternalParams(new URL(request.url));
+  const pathname = cleanUrl.pathname;
 
   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,
-    });
+  const isHmr = !!request.headers.get("X-RSC-HMR");
+  // HMR: clear the manifest cache so stale handler references are discarded.
+  if (isHmr) {
+    clearManifestCache();
   }
 
-  if (!matched) {
-    throw new RouteNotFoundError(`No route matched for ${pathname}`, {
-      cause: { pathname, method: request.method },
+  // Reuse the snapshot classifyRequest already resolved when it is a full-render
+  // snapshot (isSSR:true) and HMR has not invalidated it — mirrors the partial
+  // path. A partial-mode snapshot (isSSR:false) carries the wrong loading()
+  // entries and lives in a different manifest partition, so it is NOT reusable.
+  const classified = reqCtx?._classifiedRoute;
+  const classifiedRoute =
+    !isHmr && classified?.isSSR === true ? classified : undefined;
+
+  // On the reuse path, findMatch + manifest-loading already ran during
+  // classifyRequest (which carries no metricsStore), so only the cheap
+  // entries/cacheScope materialization is timed here under a distinct label. On
+  // the fresh path, resolveRoute emits route-matching + manifest-loading as usual.
+  const routeMatchStart = metricsStore ? performance.now() : 0;
+
+  let snapshot: RouteSnapshot<TEnv>;
+  if (classifiedRoute && classifiedRoute.manifestEntry) {
+    snapshot = ensureFullRouteSnapshot(classifiedRoute);
+    if (metricsStore) {
+      metricsStore.metrics.push({
+        label: "route-matching:reuse",
+        duration: performance.now() - routeMatchStart,
+        startTime: routeMatchStart - metricsStore.requestStart,
+      });
+    }
+  } else {
+    const result = await resolveRoute<TEnv>(pathname, {
+      findMatch: (p) => deps.findMatch(p, metricsStore),
+      metricsStore,
+      isSSR: true,
     });
-  }
 
-  if (matched.redirectTo) {
-    return {
-      type: "redirect",
-      redirectUrl: matched.redirectTo + url.search,
-    };
-  }
+    if (!result) {
+      throw new RouteNotFoundError(`No route matched for ${pathname}`, {
+        cause: { pathname, method: request.method },
+      });
+    }
 
-  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,
-    });
-  }
+    if (result.type === "redirect") {
+      // Preserve the raw query string (including internal _rsc* params) on the
+      // redirect target, matching the pre-reuse behavior of `url.search`.
+      const rawSearch = (reqCtx?.originalUrl ?? new URL(request.url)).search;
+      return {
+        type: "redirect",
+        redirectUrl: result.redirectTo + rawSearch,
+      };
+    }
 
-  if (
-    manifestEntry.type === "route" &&
-    manifestEntry.prerenderDef?.options?.passthrough === true
-  ) {
-    matched.pt = true;
+    snapshot = result.snapshot;
   }
 
-  const routeMiddleware = collectRouteMiddleware(
-    traverseBack(manifestEntry),
-    matched.params,
-  );
+  const { matched } = snapshot;
 
-  // Clean URL without internal _rsc* params for userland access
-  const cleanUrl = stripInternalParams(url);
+  if (snapshot.isPassthrough) {
+    matched.pt = true;
+  }
 
   const handlerContext = createHandlerContext(
     matched.params,
@@ -134,14 +148,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 +160,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 +179,18 @@ 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,
+    // Shell fast path: a capture or an eligible document/navigation HIT may
+    // substitute an implicit doc-level scope (a route-derived scope wins).
+    cacheScope: resolveShellImplicitCacheScope(snapshot.cacheScope),
     isIntercept: false,
     actionContext: undefined,
     isAction: false,
-    routeMiddleware,
+    routeMiddleware: snapshot.routeMiddleware,
     isFullMatch: true,
   };
 }
@@ -199,111 +205,92 @@ export async function createMatchContextForPartial<TEnv>(
   findInterceptForRoute: MatchApiDeps<TEnv>["findInterceptForRoute"],
   actionContext?: ActionContext,
 ): Promise<MatchContext<TEnv> | null> {
-  const url = new URL(request.url);
-  const pathname = url.pathname;
+  const reqCtx = _getRequestContext();
+  // resolveNavigation needs the raw URL (reads internal _rsc_segments /
+  // _rsc_stale params that stripInternalParams removes); the clean URL feeds the
+  // handler context. Both come off the request context when present.
+  const rawUrl = reqCtx?.originalUrl ?? new URL(request.url);
+  const cleanUrl = reqCtx?.url ?? stripInternalParams(rawUrl);
+  const pathname = cleanUrl.pathname;
 
   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 resolves a partial request with isSSR=false, matching this
+  // path. Never reuse an isSSR:true (full-render) snapshot — its loading()
+  // entries and manifest partition are wrong here. On HMR, discard to pick up
+  // manifest changes.
+  const classified = reqCtx?._classifiedRoute;
+  const classifiedRoute =
+    !isHmr && classified?.isSSR !== true ? classified : undefined;
+
+  // 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,
-    });
+  const nav = await resolveNavigation(request, rawUrl, 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,
-  );
   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);
-
   const handlerContext = createHandlerContext(
     matched.params,
     request,
@@ -317,9 +304,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 +323,79 @@ 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,
+    nav.effectiveFromUrl,
+    nav.effectiveFromMatch?.params ?? nav.prevParams,
+  );
 
   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 +405,36 @@ 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,
+    // A normal-route navigation may replay a PPR shell's canonical segment
+    // snapshot. Intercepts remain source-dependent and always use their normal
+    // cache path.
+    cacheScope: isIntercept
+      ? snapshot.cacheScope
+      : resolveShellImplicitCacheScope(snapshot.cacheScope),
     isIntercept,
     actionContext,
     isAction,
-    routeMiddleware,
+    routeMiddleware: snapshot.routeMiddleware,
     isFullMatch: false,
   };
 }
@@ -485,7 +455,7 @@ export async function matchError<TEnv>(
 
   debugLog("matchError", "matching error", { pathname });
 
-  const matched = deps.findMatch(pathname);
+  const matched = await deps.findMatch(pathname);
   if (!matched) {
     debugWarn("matchError", "no route matched", { pathname });
     return null;
@@ -615,6 +585,7 @@ export async function matchError<TEnv>(
     segments: [errorSegment],
     matched: matchedIds,
     diff: [errorSegment.id],
+    resolvedIds: [errorSegment.id],
     params: matched.params,
   };
 }

package/src/router/match-context.ts

@@ -242,25 +242,3 @@ export function createPipelineState(): MatchPipelineState {
     slots: {},
   };
 }
-
-/**
- * Input parameters for createMatchContext
- */
-export interface CreateMatchContextInput<TEnv = any> {
-  request: Request;
-  env: TEnv;
-  actionContext?: ActionContext;
-}
-
-/**
- * Result from createMatchContext - either a context or null (fall back to full match)
- */
-export type CreateMatchContextResult<TEnv = any> =
-  | { type: "context"; ctx: MatchContext<TEnv> }
-  | { type: "fallback"; reason: string }
-  | { type: "error"; error: Error };
-
-// Note: createMatchContext() will be implemented in Step J10 when we wire everything together.
-// It requires access to RouterContext (findMatch, loadManifest, etc.) which are closure
-// functions from createRouter(). The implementation will live in router.ts initially
-// and call getRouterContext() to access these dependencies.