@rangojs/router 0.0.0-experimental.10 → 0.0.0-experimental.100

package/src/router/match-api.ts

@@ -6,43 +6,44 @@
  */
 
 import { CacheScope, createCacheScope } from "../cache/cache-scope.js";
-import {
-  RouteNotFoundError,
-} from "../errors";
+import { RouteNotFoundError } from "../errors";
 import {
   createErrorInfo,
   createErrorSegment,
   findNearestErrorBoundary as findErrorBoundary,
 } from "./error-handling.js";
-import { createHandlerContext } from "./handler-context.js";
+import {
+  createHandlerContext,
+  stripInternalParams,
+} from "./handler-context.js";
 import { setupLoaderAccess } from "./loader-resolution.js";
 import { loadManifest, clearManifestCache } from "./manifest.js";
 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 MetricsStore,
+  type InterceptSelectorContext,
 } from "../server/context";
-import {
-  getGlobalRouteMap,
-} from "../route-map-builder.js";
-import type {
-  ErrorBoundaryHandler,
-  ErrorInfo,
-  HandlerContext,
-  MatchResult,
-  ResolvedSegment,
-} from "../types";
+import type { ErrorBoundaryHandler, ErrorInfo, MatchResult } from "../types";
 import type { ReactNode } from "react";
-import type { MatchContext, ActionContext as MatchActionContext } from "./match-context.js";
+import type { MatchContext } from "./match-context.js";
 import type { MatchApiDeps, ActionContext } from "./types.js";
-import type { InterceptEntry } from "../server/context";
-import type { RouteMatchResult } from "./pattern-matching.js";
-import { getRequestContext } from "../server/request-context.js";
+import {
+  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).
@@ -58,61 +59,50 @@ 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;
 
-  const routeMiddleware = collectRouteMiddleware(
-    traverseBack(manifestEntry),
-    matched.params,
-  );
+  const { matched } = snapshot;
+
+  // Backward compat: downstream middleware reads matched.pt
+  if (snapshot.isPassthrough) {
+    matched.pt = true;
+  }
 
-  const bindings = (env as any)?.Bindings ?? env;
+  // Clean URL without internal _rsc* params for userland access
+  const cleanUrl = stripInternalParams(url);
 
   const handlerContext = createHandlerContext(
     matched.params,
     request,
-    url.searchParams,
+    cleanUrl.searchParams,
     pathname,
-    url,
-    bindings,
-    getGlobalRouteMap(),
+    cleanUrl,
+    env,
+    deps.getRouteMap(),
     matched.routeKey,
+    matched.responseType,
+    matched.pt === true,
   );
 
   const loaderPromises = new Map<string, Promise<any>>();
@@ -130,54 +120,47 @@ 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,
+    url: cleanUrl,
     pathname,
     env,
-    bindings,
     clientSegmentIds: [],
     clientSegmentSet: new Set(),
     stale: false,
-    prevUrl: url,
+    prevUrl: cleanUrl,
     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: getGlobalRouteMap(),
+    routeMap: deps.getRouteMap(),
     metricsStore,
     Store,
     interceptContextMatch: null,
     interceptSelectorContext: {
-      from: url,
-      to: url,
+      from: cleanUrl,
+      to: cleanUrl,
       params: matched.params,
       request,
       env,
       segments: { path: [], ids: [] },
+      toRouteName:
+        matched.routeKey && !isAutoGeneratedRouteName(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,
   };
 }
@@ -195,104 +178,106 @@ export async function createMatchContextForPartial<TEnv>(
   const url = new URL(request.url);
   const pathname = url.pathname;
 
-  const requestStartTime = performance.now();
   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;
-  }
+  // 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;
 
-  const prevUrl = new URL(previousUrl, url.origin);
-  const interceptContextUrl = interceptSourceUrl
-    ? new URL(interceptSourceUrl, url.origin)
-    : 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) {
-    console.log(
-      `[Router.matchPartial] Route group changed: ${prevMatch.routeKey} → ${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,
     });
   }
 
-  const routeMiddleware = collectRouteMiddleware(
-    traverseBack(manifestEntry),
-    matched.params,
-  );
+  if (nav.prevMatch && nav.prevMatch.entry !== matched.entry && !matched.pr) {
+    debugLog("matchPartial", "route group changed", {
+      from: nav.prevMatch.routeKey,
+      to: matched.routeKey,
+    });
+  }
+
+  // Clean URL without internal _rsc* params for userland access
+  const cleanUrl = stripInternalParams(url);
 
-  const bindings = (env as any)?.Bindings ?? env;
   const handlerContext = createHandlerContext(
     matched.params,
     request,
-    url.searchParams,
+    cleanUrl.searchParams,
     pathname,
-    url,
-    bindings,
-    getGlobalRouteMap(),
+    cleanUrl,
+    env,
+    deps.getRouteMap(),
     matched.routeKey,
+    matched.responseType,
+    matched.pt === true,
   );
 
-  const clientSegmentSet = new Set(clientSegmentIds);
-  console.log(
-    `[Router.matchPartial] Client segments:`,
-    Array.from(clientSegmentSet),
-  );
+  debugLog("matchPartial", "client segments", {
+    segments: Array.from(nav.clientSegmentSet),
+  });
 
   const loaderPromises = new Map<string, Promise<any>>();
   setupLoaderAccess(handlerContext, loaderPromises);
@@ -309,116 +294,112 @@ export async function createMatchContextForPartial<TEnv>(
     Store.metrics = metricsStore;
   }
 
-  const isSameRouteNavigation = !!(
-    interceptContextMatch &&
-    interceptContextMatch.routeKey === matched.routeKey
-  );
-
-  if (interceptSourceUrl) {
-    console.log(`[Router.matchPartial] Intercept context detected:`);
-    console.log(`  - Current URL: ${pathname}`);
-    console.log(`  - Intercept source: ${interceptSourceUrl}`);
-    console.log(`  - Context match: ${interceptContextMatch?.routeKey}`);
-    console.log(`  - Current route: ${matched.routeKey}`);
-    console.log(`  - Same route navigation: ${isSameRouteNavigation}`);
+  if (nav.hasInterceptSource) {
+    debugLog("matchPartial.intercept", "intercept context detected", {
+      currentUrl: pathname,
+      interceptSource: nav.interceptContextUrl.href,
+      contextRoute: nav.interceptContextMatch?.routeKey,
+      currentRoute: matched.routeKey,
+      sameRouteNavigation: nav.isSameRouteNavigation,
+    });
   }
 
-  const localRouteName = matched.routeKey.includes(".")
-    ? matched.routeKey.split(".").pop()!
-    : matched.routeKey;
+  // 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(nav.effectiveFromMatch?.routeKey);
 
-  const filteredSegmentIds = clientSegmentIds.filter((id) => {
-    if (id.includes(".@")) return false;
-    if (/D\d+\./.test(id)) return false;
-    return true;
-  });
   const interceptSelectorContext: InterceptSelectorContext = {
-    from: prevUrl,
-    to: url,
+    from: nav.effectiveFromUrl,
+    to: cleanUrl,
     params: matched.params,
     request,
     env,
     segments: {
-      path: prevUrl.pathname.split("/").filter(Boolean),
-      ids: filteredSegmentIds,
+      path: nav.effectiveFromUrl.pathname.split("/").filter(Boolean),
+      ids: nav.filteredSegmentIds,
     },
+    fromRouteName:
+      nav.effectiveFromMatch?.routeKey &&
+      !isAutoGeneratedRouteName(nav.effectiveFromMatch.routeKey)
+        ? (nav.effectiveFromMatch.routeKey as DefaultRouteName)
+        : undefined,
+    toRouteName:
+      matched.routeKey && !isAutoGeneratedRouteName(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
   ) {
-    console.log(
-      `[Router.matchPartial] Leaving intercept - forcing route segment render: ${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);
-    }
+    debugLog("matchPartial.intercept", "forcing route segment render", {
+      segmentId: snapshot.manifestEntry.shortCode,
+    });
+    clientSegmentSet.delete(snapshot.manifestEntry.shortCode);
   }
 
   const isIntercept = !!interceptResult;
 
   return {
     request,
-    url,
+    url: cleanUrl,
     pathname,
     env,
-    bindings,
-    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: getGlobalRouteMap(),
+    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,
   };
 }
@@ -437,11 +418,11 @@ export async function matchError<TEnv>(
   const url = new URL(request.url);
   const pathname = url.pathname;
 
-  console.log(`[Router.matchError] Matching error for ${pathname}`);
+  debugLog("matchError", "matching error", { pathname });
 
   const matched = deps.findMatch(pathname);
   if (!matched) {
-    console.warn(`[Router.matchError] No route matched for ${pathname}`);
+    debugWarn("matchError", "no route matched", { pathname });
     return null;
   }
 
@@ -545,10 +526,7 @@ export async function matchError<TEnv>(
 
   const reqCtx = getRequestContext();
   if (reqCtx) {
-    reqCtx.res = new Response(null, {
-      status: 500,
-      headers: reqCtx.res.headers,
-    });
+    reqCtx._setStatus(500);
   }
 
   const effectiveFallback = fallback || DefaultErrorFallback;
@@ -560,62 +538,19 @@ export async function matchError<TEnv>(
   );
 
   if (useDefaultFallback) {
-    console.log(
-      `[Router.matchError] Using default error boundary (no user-defined boundary found)`,
-    );
+    debugLog("matchError", "using default error boundary");
   }
 
-  console.log(
-    `[Router.matchError] Boundary: ${boundaryEntry.shortCode}, outlet replaced: ${outletEntry.shortCode}`,
-  );
+  debugLog("matchError", "resolved boundary", {
+    boundarySegmentId: boundaryEntry.shortCode,
+    outletSegmentId: outletEntry.shortCode,
+  });
 
   return {
     segments: [errorSegment],
     matched: matchedIds,
     diff: [errorSegment.id],
+    resolvedIds: [errorSegment.id],
     params: matched.params,
   };
 }
-
-/**
- * Preview match - returns route middleware without segment resolution.
- */
-export async function previewMatch<TEnv>(
-  request: Request,
-  context: TEnv,
-  deps: MatchApiDeps<TEnv>,
-): Promise<{
-  routeMiddleware?: Array<{
-    handler: import("./middleware.js").MiddlewareFn;
-    params: Record<string, string>;
-  }>;
-} | null> {
-  const url = new URL(request.url);
-  const pathname = url.pathname;
-
-  const matched = deps.findMatch(pathname);
-  if (!matched) {
-    return null;
-  }
-
-  if (matched.redirectTo) {
-    return { routeMiddleware: undefined };
-  }
-
-  const manifestEntry = await loadManifest(
-    matched.entry,
-    matched.routeKey,
-    pathname,
-    undefined,
-    false,
-  );
-
-  const routeMiddleware = collectRouteMiddleware(
-    traverseBack(manifestEntry),
-    matched.params,
-  );
-
-  return {
-    routeMiddleware: routeMiddleware.length > 0 ? routeMiddleware : undefined,
-  };
-}

package/src/router/match-context.ts

@@ -45,7 +45,7 @@
  *   - request, url, pathname: The incoming HTTP request
  *
  * Environment:
- *   - env, bindings: Server environment (Cloudflare bindings, etc.)
+ *   - env: Server environment (Cloudflare bindings, etc.)
  *
  * Client State (from RSC request headers):
  *   - clientSegmentIds: Segments the client currently has
@@ -140,7 +140,6 @@ export interface MatchContext<TEnv = any> {
 
   // Environment
   env: TEnv;
-  bindings: TEnv;
 
   // Client state
   clientSegmentIds: string[];
@@ -211,6 +210,9 @@ export interface MatchPipelineState {
   // Whether cache should be revalidated (SWR)
   shouldRevalidate?: boolean;
 
+  // Source of cache hit ("runtime" or "prerender")
+  cacheSource?: "runtime" | "prerender";
+
   // Resolved segments from pipeline
   segments: ResolvedSegment[];
   matchedIds: string[];