@rangojs/router 0.0.0-experimental.7a20d911 → 0.0.0-experimental.7cf4e116

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,6 +8,7 @@ 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 { VERSION } from "@rangojs/router:version";
@@ -23,20 +18,19 @@ import { VERSION } from "@rangojs/router:version";
 // 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 +59,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) {
@@ -88,20 +84,15 @@ 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();
   pushMetric?.("manifest:clear", clearStart);
@@ -126,28 +117,37 @@ export async function loadManifest(
     // were created during pattern extraction.  This prevents shortCode
     // collisions between lazy and non-lazy entries under the same parent
     // (e.g., ArticlesLayout and BlogLayout both under NavLayout).
-    if (lazyContext && (lazyContext as any).counters) {
-      const captured = (lazyContext as any).counters as Record<string, number>;
-      for (const [key, value] of Object.entries(captured)) {
+    if (lazyContext?.counters) {
+      for (const [key, value] of Object.entries(lazyContext.counters)) {
         Store.counters[key] = Math.max(Store.counters[key] ?? 0, value);
       }
     }
 
     // Propagate cache profiles for DSL-time cache("profileName") resolution.
     // Non-lazy entries carry profiles directly; lazy entries carry them
-    // in the captured lazyContext from include() time.
-    const entryProfiles =
-      entry.cacheProfiles ?? (lazyContext as any)?.cacheProfiles;
-    if (entryProfiles) {
-      Store.cacheProfiles = entryProfiles;
-    }
+    // in the captured lazyContext from include() time. Always write
+    // (including clearing to undefined) so a prior lazy build's profile
+    // map cannot leak into a later non-lazy build on the same ALS-backed
+    // Store — which would otherwise let cache("name") resolve a profile
+    // from an unrelated entry.
+    Store.cacheProfiles = entry.cacheProfiles ?? lazyContext?.cacheProfiles;
 
     // Propagate rootScoped from lazyContext so that routes inside
     // nested { name: "sub" } under { name: "" } keep inherited root scope
-    // when the manifest is rebuilt on each request.
-    if (lazyContext && (lazyContext as any).rootScoped !== undefined) {
-      Store.rootScoped = (lazyContext as any).rootScoped;
-    }
+    // when the manifest is rebuilt on each request. Always write
+    // (including clearing to undefined, which makes getRootScoped()
+    // return its true default) so a prior lazy build's scope cannot leak
+    // into a later non-lazy build on the same ALS-backed Store — which
+    // would otherwise mis-register plain routes as non-root-scoped and
+    // break dot-local reverse resolution.
+    Store.rootScoped = lazyContext?.rootScoped;
+
+    // Propagate includeScope from lazyContext so that direct-descendant
+    // shortCodes of this include use the correct scoped counter namespace
+    // on every manifest rebuild. Always write (including clearing to
+    // undefined) so a prior lazy build's scope cannot leak into a later
+    // non-lazy build on the same ALS-backed Store.
+    Store.includeScope = lazyContext?.includeScope;
 
     const handlerExecStart = performance.now();
     const useItems = await getContext().runWithStore(
@@ -167,7 +167,10 @@ export async function loadManifest(
         if (entry.lazy && entry.lazyPatterns) {
           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, () =>
@@ -177,20 +180,16 @@ 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 (
@@ -224,7 +223,6 @@ export async function loadManifest(
           );
         }
 
-        // Inline handler - routes were registered with correct parent inside layout
         return [wrappedItems].flat(3);
       },
     );

package/src/router/match-api.ts

@@ -1,10 +1,3 @@
-/**
- * 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 { RouteNotFoundError } from "../errors";
 import {
@@ -22,10 +15,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";
@@ -59,8 +52,6 @@ export async function createMatchContextForFull<TEnv>(
 
   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,
@@ -84,12 +75,10 @@ export async function createMatchContextForFull<TEnv>(
 
   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(
@@ -231,7 +220,6 @@ export async function createMatchContextForPartial<TEnv>(
     matched.pt = true;
   }
 
-  // Navigation state (prev + intercept-source findMatch calls)
   const nav = resolveNavigation(request, url, matched.routeKey, {
     findMatch: deps.findMatch,
   });
@@ -239,10 +227,6 @@ export async function createMatchContextForPartial<TEnv>(
     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,7 +243,6 @@ export async function createMatchContextForPartial<TEnv>(
     });
   }
 
-  // Clean URL without internal _rsc* params for userland access
   const cleanUrl = stripInternalParams(url);
 
   const handlerContext = createHandlerContext(
@@ -304,9 +287,6 @@ 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);
 
   const interceptSelectorContext: InterceptSelectorContext = {
@@ -550,6 +530,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.

package/src/router/match-handlers.ts

@@ -33,10 +33,13 @@ import type { ErrorBoundaryHandler, NotFoundBoundaryHandler } from "../types";
 import type { MiddlewareFn } from "./middleware.js";
 import {
   type TelemetrySink,
+  type CacheSegmentSignal,
   safeEmit,
   resolveSink,
   getRequestId,
+  buildCacheSignalSegments,
 } from "./telemetry.js";
+import { _getRequestContext } from "../server/request-context.js";
 
 export interface MatchHandlerDeps<TEnv = any> {
   buildRouterContext: () => RouterContext<TEnv>;
@@ -51,6 +54,12 @@ export interface MatchHandlerDeps<TEnv = any> {
     isAction: boolean,
   ) => { intercept: InterceptEntry; entry: EntryData } | null;
   telemetry?: TelemetrySink;
+  /**
+   * DEVELOPMENT/TEST ONLY gate for the X-Rango-Cache debug header. When true,
+   * match/matchPartial stash a coarse route-level cache signal on the request
+   * context for the response-finalization path to emit. Default off.
+   */
+  cacheSignalEnabled?: boolean;
 }
 
 export interface MatchHandlers<TEnv = any> {
@@ -80,20 +89,6 @@ export interface MatchHandlers<TEnv = any> {
     negotiated?: boolean;
     manifestEntry?: EntryData;
   } | null>;
-  createMatchContextForFull: (
-    request: Request,
-    env: TEnv,
-  ) => Promise<MatchContext<TEnv> | { type: "redirect"; redirectUrl: string }>;
-  createMatchContextForPartial: (
-    request: Request,
-    env: TEnv,
-    actionContext?: {
-      actionId?: string;
-      actionUrl?: URL;
-      actionResult?: any;
-      formData?: FormData;
-    },
-  ) => Promise<MatchContext<TEnv> | null>;
 }
 
 /**
@@ -113,6 +108,20 @@ export function createMatchHandlers<TEnv = any>(
   } = deps;
   const hasTelemetry = !!deps.telemetry;
   const telemetry = resolveSink(deps.telemetry);
+  const cacheSignalEnabled = !!deps.cacheSignalEnabled;
+  const buildSignal = (
+    routeKey: string,
+    state: {
+      cacheHit: boolean;
+      cacheSource?: "runtime" | "prerender";
+      shouldRevalidate?: boolean;
+    },
+  ): CacheSegmentSignal[] => buildCacheSignalSegments(routeKey, state);
+  const recordSignalIfEnabled = (segments: CacheSegmentSignal[]): void => {
+    if (!cacheSignalEnabled) return;
+    const reqCtx = _getRequestContext();
+    if (reqCtx) reqCtx._cacheSignal = segments;
+  };
 
   async function createMatchContextForFull(
     request: Request,
@@ -145,15 +154,6 @@ export function createMatchHandlers<TEnv = any>(
     );
   }
 
-  /**
-   * Match request and return segments (document/SSR requests)
-   *
-   * Uses generator middleware pipeline for clean separation of concerns:
-   * - cache-lookup: Check cache first
-   * - segment-resolution: Resolve segments on cache miss
-   * - cache-store: Store results in cache
-   * - background-revalidation: SWR revalidation
-   */
   async function match(request: Request, env: TEnv): Promise<MatchResult> {
     const requestId = hasTelemetry ? getRequestId(request) : undefined;
     return runWithRouterLogContext({ request, transaction: "match" }, () => {
@@ -177,7 +177,6 @@ export function createMatchHandlers<TEnv = any>(
 
           const result = await createMatchContextForFull(request, env);
 
-          // Handle redirect case
           if ("type" in result && result.type === "redirect") {
             if (hasTelemetry) {
               safeEmit(telemetry, {
@@ -196,6 +195,7 @@ export function createMatchHandlers<TEnv = any>(
               segments: [],
               matched: [],
               diff: [],
+              resolvedIds: [],
               params: {},
               redirect: result.redirectUrl,
             };
@@ -207,17 +207,24 @@ export function createMatchHandlers<TEnv = any>(
             const state = createPipelineState();
             const pipeline = createMatchPartialPipeline(ctx, state);
             const matchResult = await collectMatchResult(pipeline, ctx, state);
+            if (hasTelemetry || cacheSignalEnabled) {
+              const signalSegments = buildSignal(ctx.routeKey, state);
+              recordSignalIfEnabled(signalSegments);
+              if (hasTelemetry) {
+                safeEmit(telemetry, {
+                  type: "cache.decision",
+                  timestamp: performance.now(),
+                  requestId,
+                  pathname,
+                  routeKey: ctx.routeKey,
+                  hit: state.cacheHit,
+                  shouldRevalidate: !!state.shouldRevalidate,
+                  source: state.cacheSource,
+                  segments: signalSegments,
+                });
+              }
+            }
             if (hasTelemetry) {
-              safeEmit(telemetry, {
-                type: "cache.decision",
-                timestamp: performance.now(),
-                requestId,
-                pathname,
-                routeKey: ctx.routeKey,
-                hit: state.cacheHit,
-                shouldRevalidate: !!state.shouldRevalidate,
-                source: state.cacheSource,
-              });
               safeEmit(telemetry, {
                 type: "request.end",
                 timestamp: performance.now(),
@@ -248,7 +255,6 @@ export function createMatchHandlers<TEnv = any>(
               });
             }
             if (error instanceof Response) throw error;
-            // Report unhandled errors during full match pipeline
             callOnError(error, "routing", {
               request,
               url: ctx.url,
@@ -283,16 +289,6 @@ export function createMatchHandlers<TEnv = any>(
     );
   }
 
-  /**
-   * Match partial request with revalidation
-   *
-   * Uses generator middleware pipeline for clean separation of concerns:
-   * - cache-lookup: Check cache first
-   * - segment-resolution: Resolve segments on cache miss
-   * - intercept-resolution: Handle intercept routes
-   * - cache-store: Store results in cache
-   * - background-revalidation: SWR revalidation
-   */
   async function matchPartial(
     request: Request,
     context: TEnv,
@@ -362,17 +358,24 @@ export function createMatchHandlers<TEnv = any>(
                 state,
               );
               flushRevalidationTrace();
+              if (hasTelemetry || cacheSignalEnabled) {
+                const signalSegments = buildSignal(ctx.routeKey, state);
+                recordSignalIfEnabled(signalSegments);
+                if (hasTelemetry) {
+                  safeEmit(telemetry, {
+                    type: "cache.decision",
+                    timestamp: performance.now(),
+                    requestId: partialRequestId,
+                    pathname,
+                    routeKey: ctx.routeKey,
+                    hit: state.cacheHit,
+                    shouldRevalidate: !!state.shouldRevalidate,
+                    source: state.cacheSource,
+                    segments: signalSegments,
+                  });
+                }
+              }
               if (hasTelemetry) {
-                safeEmit(telemetry, {
-                  type: "cache.decision",
-                  timestamp: performance.now(),
-                  requestId: partialRequestId,
-                  pathname,
-                  routeKey: ctx.routeKey,
-                  hit: state.cacheHit,
-                  shouldRevalidate: !!state.shouldRevalidate,
-                  source: state.cacheSource,
-                });
                 safeEmit(telemetry, {
                   type: "request.end",
                   timestamp: performance.now(),
@@ -405,7 +408,6 @@ export function createMatchHandlers<TEnv = any>(
                 });
               }
               if (error instanceof Response) throw error;
-              // Report unhandled errors during partial match pipeline
               callOnError(error, actionContext ? "action" : "revalidation", {
                 request,
                 url: ctx.url,
@@ -434,7 +436,5 @@ export function createMatchHandlers<TEnv = any>(
     matchPartial: matchPartial,
     matchError: matchError,
     previewMatch: previewMatch,
-    createMatchContextForFull: createMatchContextForFull,
-    createMatchContextForPartial: createMatchContextForPartial,
   };
 }

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

@@ -168,8 +168,6 @@ export function withBackgroundRevalidation<TEnv>(
       requestCtx._handleStore = createHandleStore();
 
       try {
-        // Create fresh handler context and loader promises to avoid
-        // reusing memoized results from the foreground pass
         const freshHandlerContext = createHandlerContext(
           ctx.matched.params,
           ctx.request,
@@ -185,10 +183,6 @@ export function withBackgroundRevalidation<TEnv>(
         const freshLoaderPromises = new Map<string, Promise<any>>();
         setupLoaderAccess(freshHandlerContext, freshLoaderPromises);
 
-        // Resolve all segments fresh (without revalidation logic)
-        // 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,
@@ -200,7 +194,6 @@ export function withBackgroundRevalidation<TEnv>(
           ),
         );
 
-        // Also resolve intercept segments fresh if applicable
         let freshInterceptSegments: ResolvedSegment[] = [];
         if (ctx.interceptResult) {
           freshInterceptSegments = await ctx.Store.run(() =>
@@ -210,6 +203,12 @@ export function withBackgroundRevalidation<TEnv>(
               ctx.matched.params,
               freshHandlerContext,
               true,
+              undefined,
+              // Skip intercept middleware: this is a post-response background
+              // re-render to refresh a stale cached route. The foreground
+              // already ran the middleware; re-running it would double its side
+              // effects and a short-circuit Response would abort the write.
+              { skipMiddleware: true },
             ),
           );
         }