@rangojs/router 0.0.0-experimental.f2d1a2f1 → 0.0.0-experimental.f4a8e8de

package/src/router/manifest.ts

@@ -1,9 +1,3 @@
-/**
- * Router Manifest Loading
- *
- * Handles lazy loading and validation of route manifests.
- */
-
 import { invariant, RouteNotFoundError } from "../errors";
 import { createRouteHelpers } from "../route-definition";
 import {
@@ -14,29 +8,38 @@ import {
   type MetricsStore,
 } from "../server/context";
 import MapRootLayout from "../server/root-layout";
+import { joinPrefix } from "./pattern-matching.js";
 import type { RouteEntry } from "../types";
 import type { UrlPatterns } from "../urls";
+import {
+  isIncludeProvider,
+  resolveIncludeModule,
+} from "../urls/include-provider.js";
 import { VERSION } from "@rangojs/router:version";
 
+// Tags an error thrown while dynamically importing an async include's module
+// (`() => import("./routes")`) so loadManifest's outer catch re-raises it as a
+// server error rather than masking it as a RouteNotFoundError (404).
+const MODULE_LOAD_FAILURE = Symbol.for("rango.moduleLoadFailure");
+
 // Module-level manifest cache: avoids re-executing DSL handler on every request.
 // Handler execution is deterministic (components, loaders, middleware are module-level
 // stable references), so the resulting EntryData tree can be safely cached and reused
 // across requests within the same isolate.
 //
-// Cache is keyed by (VERSION, mountIndex, routeKey, isSSR). VERSION comes from the
+// Cache is keyed by (VERSION, routerId, mountIndex, routeKey, isSSR). routeKey is
+// REQUIRED in the key: loadManifest() runs the handler with forRoute=routeKey, and
+// path-helper.ts prunes (skips registering) every route except forRoute, so the
+// resulting Store.manifest is pruned to the requested route — NOT the full include.
+// Dropping routeKey would make a sibling route miss and overwrite this entry with its
+// own pruned manifest, so alternating sibling requests would thrash (re-run the
+// handler every time). Running the include handler once per isolate instead of once
+// per route is possible but needs an unpruned manifest cache with prune-on-read — see
+// LP1 in docs/internal/matching-and-lazy-discovery.md. VERSION comes from the
 // @rangojs/router:version virtual module which Vite invalidates on RSC module HMR.
 // When VERSION changes, this module re-evaluates and the cache is recreated empty.
-// Including VERSION in the key is additional defense against stale entries.
 const manifestModuleCache = new Map<string, Map<string, EntryData>>();
 
-/**
- * Load manifest from route entry with AsyncLocalStorage context
- * Handles lazy imports, unwrapping, and validation
- *
- * Results are cached at module level after first execution. Subsequent calls
- * for the same (routeKey, isSSR) within the same isolate return cached data
- * without re-executing the DSL handler.
- */
 /**
  * Clear the module-level manifest cache.
  * Called on HMR to ensure stale handler references are discarded.
@@ -65,9 +68,11 @@ export async function loadManifest(
 
   const mountIndex = entry.mountIndex;
 
-  // Check module-level cache (persists across requests within same isolate)
+  // Check module-level cache (persists across requests within same isolate).
   // Include routerId so multi-router setups (host routing) don't share cached
   // EntryData across routers with overlapping mountIndex + routeKey combinations.
+  // routeKey is in the key because loadManifest() builds a manifest pruned to
+  // forRoute=routeKey (see path-helper.ts) — see the cache comment above.
   const cacheKey = `${VERSION}:${entry.routerId ?? ""}:${mountIndex ?? ""}:${routeKey}:${isSSR ? 1 : 0}`;
   const cached = manifestModuleCache.get(cacheKey);
   if (cached) {
@@ -77,10 +82,14 @@ export async function loadManifest(
     Store.mountIndex = mountIndex;
     Store.isSSR = isSSR;
     if (metricsStore) Store.metrics = metricsStore;
-    // Restore cached manifest into Store
-    for (const [k, v] of cached) {
-      Store.manifest.set(k, v);
-    }
+    // Alias the request-scoped Store to the cached Map instead of copying it
+    // entry-by-entry. At request time this Store is throwaway (no ambient
+    // RangoContext store spans classify->match->render, so getOrCreateStore
+    // returns a fresh detached store here), so nothing mutates it in place after
+    // loadManifest returns. The fresh path below REASSIGNS Store.manifest rather
+    // than clearing it in place, so a later fresh load sharing this Store cannot
+    // poison the cached Map.
+    Store.manifest = cached;
     pushMetric?.("manifest:cache-hit", cacheStart);
     return cached.get(routeKey)!;
   }
@@ -88,22 +97,21 @@ export async function loadManifest(
   const storeSetupStart = performance.now();
   const Store = getContext().getOrCreateStore(routeKey);
 
-  // Set mount index in store for unique shortCode prefixes
   Store.mountIndex = mountIndex;
-
-  // Set isSSR flag so loading() can check if we're in SSR
   Store.isSSR = isSSR;
 
-  // Attach metrics store to context if provided
   if (metricsStore) {
     Store.metrics = metricsStore;
   }
 
   pushMetric?.("manifest:store-setup", storeSetupStart);
 
-  // Clear manifest before rebuilding to prevent stale entry mutations
   const clearStart = performance.now();
-  Store.manifest.clear();
+  // Reassign rather than clear() in place: a prior cache-hit may have aliased
+  // Store.manifest to a shared module-cache Map (see cache-hit branch above),
+  // and clearing it in place would poison that cache. A fresh Map isolates this
+  // build; the cache still receives an independent copy at the end.
+  Store.manifest = new Map();
   pushMetric?.("manifest:clear", clearStart);
 
   try {
@@ -174,9 +182,35 @@ export async function loadManifest(
         // not exist in the non-lazy (root handler) path and would produce
         // mismatched shortCodes.
         if (entry.lazy && entry.lazyPatterns) {
+          // Resolve an async include provider (`() => import("./routes")`) before
+          // running its handler. The match-time precomputed shortcut can skip
+          // evaluateLazyEntry's resolution, so render-time must resolve it here;
+          // cache the resolved patterns on the entry so later renders reuse them.
+          if (isIncludeProvider(entry.lazyPatterns)) {
+            try {
+              entry.lazyPatterns = resolveIncludeModule(
+                await entry.lazyPatterns(),
+                entry.staticPrefix,
+              ) as unknown as UrlPatterns<any>;
+            } catch (err) {
+              // A failed dynamic import of a REAL, matched route's module is a
+              // server error, not a missing route. Tag it so the outer catch
+              // surfaces it as a 5xx instead of masking it as a
+              // RouteNotFoundError — which renders the 404 page (monitoring
+              // misses the failure and a CDN could cache the 404).
+              if (err && typeof err === "object") {
+                (err as Record<PropertyKey, unknown>)[MODULE_LOAD_FAILURE] =
+                  true;
+              }
+              throw err;
+            }
+          }
           const lazyPatterns = entry.lazyPatterns as UrlPatterns<any>;
           const includePrefix = (entry as any)._lazyPrefix || "";
-          const fullPrefix = (lazyContext?.urlPrefix || "") + includePrefix;
+          // Slash-collapsing join so a trailing-slash parent prefix does not
+          // bake a double slash into the registered route patterns (must match
+          // the same join in evaluateLazyEntry / the build-time runWithPrefixes).
+          const fullPrefix = joinPrefix(lazyContext?.urlPrefix, includePrefix);
 
           if (fullPrefix || lazyContext?.namePrefix) {
             return runWithPrefixes(fullPrefix, lazyContext?.namePrefix, () =>
@@ -186,28 +220,19 @@ export async function loadManifest(
           return lazyPatterns.handler();
         }
 
-        // Wrap handler execution in root layout so routes get correct parent
-        // This ensures all routes are registered with the layout as their parent
         let promiseResult: Promise<any> | null = null;
         const wrappedItems = helpers.layout(MapRootLayout, () => {
           const result = entry.handler();
           if (result instanceof Promise) {
-            // Lazy handler detected - capture promise for async handling
             promiseResult = result;
-            return []; // Return empty, we'll discard this wrapped result
+            return [];
           }
           return result;
         });
 
-        // Handle lazy (Promise-based) handlers
         if (promiseResult !== null) {
           const load = await (promiseResult as Promise<any>);
-          if (
-            load &&
-            load !== null &&
-            typeof load === "object" &&
-            "default" in load
-          ) {
+          if (load && typeof load === "object" && "default" in load) {
             // Promise<{ default: () => Array }> - e.g., dynamic import
             if (typeof load.default !== "function") {
               throw new Error(
@@ -233,7 +258,6 @@ export async function loadManifest(
           );
         }
 
-        // Inline handler - routes were registered with correct parent inside layout
         return [wrappedItems].flat(3);
       },
     );
@@ -266,6 +290,16 @@ export async function loadManifest(
 
     return Store.manifest.get(routeKey)!;
   } catch (e) {
+    // A tagged async-include module-load failure is a server error for a REAL
+    // matched route — re-raise it unchanged (becomes a 5xx) instead of masking
+    // it as a RouteNotFoundError (which renders/caches a 404).
+    if (
+      e &&
+      typeof e === "object" &&
+      (e as Record<PropertyKey, unknown>)[MODULE_LOAD_FAILURE]
+    ) {
+      throw e;
+    }
     throw new RouteNotFoundError(
       `Failed to load route handlers for ${path}: ${(e as Error).message}`,
       {

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,
@@ -33,6 +30,7 @@ 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";
@@ -54,44 +52,74 @@ 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();
 
-  // 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,
-  });
+  const isHmr = !!request.headers.get("X-RSC-HMR");
+  // HMR: clear the manifest cache so stale handler references are discarded.
+  if (isHmr) {
+    clearManifestCache();
+  }
+
+  // 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;
 
-  if (!result) {
-    throw new RouteNotFoundError(`No route matched for ${pathname}`, {
-      cause: { pathname, method: request.method },
+  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 (result.type === "redirect") {
-    return {
-      type: "redirect",
-      redirectUrl: result.redirectTo + url.search,
-    };
-  }
+    if (!result) {
+      throw new RouteNotFoundError(`No route matched for ${pathname}`, {
+        cause: { pathname, method: request.method },
+      });
+    }
+
+    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,
+      };
+    }
 
-  const snapshot = result.snapshot;
+    snapshot = result.snapshot;
+  }
 
   const { matched } = snapshot;
 
-  // Backward compat: downstream middleware reads matched.pt
   if (snapshot.isPassthrough) {
     matched.pt = true;
   }
 
-  // Clean URL without internal _rsc* params for userland access
-  const cleanUrl = stripInternalParams(url);
-
   const handlerContext = createHandlerContext(
     matched.params,
     request,
@@ -156,7 +184,9 @@ export async function createMatchContextForFull<TEnv>(
     },
     isSameRouteNavigation: false,
     interceptResult: null,
-    cacheScope: snapshot.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,
@@ -175,8 +205,13 @@ 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();
 
@@ -188,11 +223,13 @@ export async function createMatchContextForPartial<TEnv>(
   }
 
   // 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;
+  // 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
@@ -231,18 +268,13 @@ export async function createMatchContextForPartial<TEnv>(
     matched.pt = true;
   }
 
-  // Navigation state (prev + intercept-source findMatch calls)
-  const nav = resolveNavigation(request, url, matched.routeKey, {
+  const nav = await resolveNavigation(request, rawUrl, matched.routeKey, {
     findMatch: deps.findMatch,
   });
   if (!nav) {
     return null;
   }
 
-  // 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({
@@ -259,9 +291,6 @@ export async function createMatchContextForPartial<TEnv>(
     });
   }
 
-  // Clean URL without internal _rsc* params for userland access
-  const cleanUrl = stripInternalParams(url);
-
   const handlerContext = createHandlerContext(
     matched.params,
     request,
@@ -304,10 +333,11 @@ export async function createMatchContextForPartial<TEnv>(
     });
   }
 
-  // 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);
+  setRequestContextPrevRouteKey(
+    nav.effectiveFromMatch?.routeKey,
+    nav.effectiveFromUrl,
+    nav.effectiveFromMatch?.params ?? nav.prevParams,
+  );
 
   const interceptSelectorContext: InterceptSelectorContext = {
     from: nav.effectiveFromUrl,
@@ -395,7 +425,12 @@ export async function createMatchContextForPartial<TEnv>(
     interceptSelectorContext,
     isSameRouteNavigation: nav.isSameRouteNavigation,
     interceptResult,
-    cacheScope: snapshot.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,
@@ -420,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;
@@ -550,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.