@rangojs/router 0.0.0-experimental.07cdfab0 → 0.0.0-experimental.0b3f4e91

package/src/route-definition/helpers-types.ts

@@ -228,11 +228,12 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
    *   revalidate(({ actionId }) => actionId?.includes("Cart") ?? false),
    * ])
    *
-   * // Access loader data in handlers via ctx.use()
-   * route("products.detail", async (ctx) => {
-   *   const product = await ctx.use(ProductLoader);
-   *   return <ProductPage product={product} />;
-   * })
+   * // Consume in client components with useLoader()
+   * // (preferred — cache-safe, always fresh)
+   * function ProductDetails() {
+   *   const { data } = useLoader(ProductLoader);
+   *   return <div>{data.name}</div>;
+   * }
    * ```
    * @param loaderDef - Loader created with createLoader()
    * @param use - Optional callback for loader-specific revalidation rules

package/src/route-definition/redirect.ts

@@ -2,6 +2,7 @@ import type { LocationStateEntry } from "../browser/react/location-state-shared.
 import {
   requireRequestContext,
   getRequestContext,
+  _getRequestContext,
 } from "../server/request-context.js";
 
 /**
@@ -83,10 +84,17 @@ export function redirect(
     }
   }
 
+  // Auto-prefix root-relative URLs with basename for app-local redirects.
+  const bn = _getRequestContext()?._basename;
+  let resolvedUrl = url;
+  if (bn && url.startsWith("/") && !url.startsWith(bn + "/") && url !== bn) {
+    resolvedUrl = url === "/" ? bn : bn + url;
+  }
+
   return new Response(null, {
     status,
     headers: {
-      Location: url,
+      Location: resolvedUrl,
       "X-RSC-Redirect": "soft",
     },
   });

package/src/router/handler-context.ts

@@ -8,7 +8,13 @@ import type { HandlerContext, InternalHandlerContext } from "../types";
 import { _getRequestContext } from "../server/request-context.js";
 import { getSearchSchema, isRouteRootScoped } from "../route-map-builder.js";
 import { parseSearchParams, serializeSearchParams } from "../search-params.js";
-import { contextGet, contextSet } from "../context-var.js";
+import {
+  contextGet,
+  contextSet,
+  isNonCacheable,
+  type ContextSetOptions,
+} from "../context-var.js";
+import { isInsideCacheScope } from "../server/context.js";
 import { NOCACHE_SYMBOL, assertNotInsideCacheExec } from "../cache/taint.js";
 import { isAutoGeneratedRouteName } from "../route-name.js";
 import { PRERENDER_PASSTHROUGH } from "../prerender.js";
@@ -201,7 +207,7 @@ export function createHandlerContext<TEnv>(
   // Get variables from request context - this is the unified context
   // shared between middleware and route handlers
   const requestContext = _getRequestContext();
-  const variables: any = requestContext?.var ?? {};
+  const variables: any = requestContext?._variables ?? {};
 
   // If route has a search schema, parse URLSearchParams into typed object
   const searchSchema = routeName ? getSearchSchema(routeName) : undefined;
@@ -213,7 +219,7 @@ export function createHandlerContext<TEnv>(
   const stubResponse =
     requestContext?.res ?? new Response(null, { status: 200 });
 
-  // Guard mutating Headers methods so they throw inside "use cache" functions.
+  // Guard mutating Headers methods so they throw inside "use cache" or cache() scope.
   // Uses lazy `ctx` reference (assigned below) — only the specific handler ctx
   // is stamped by cache-runtime, not the shared request context.
   const MUTATING_HEADERS_METHODS = new Set(["set", "append", "delete"]);
@@ -225,6 +231,13 @@ export function createHandlerContext<TEnv>(
         if (MUTATING_HEADERS_METHODS.has(prop as string)) {
           return (...args: any[]) => {
             assertNotInsideCacheExec(ctx, "headers");
+            if (isInsideCacheScope()) {
+              throw new Error(
+                `ctx.headers.${String(prop)}() cannot be called inside a cache() boundary. ` +
+                  `On cache hit the handler is skipped, so this side effect would be lost. ` +
+                  `Move header mutations to a middleware or layout outside the cache() scope.`,
+              );
+            }
             return value.apply(target, args);
           };
         }
@@ -244,14 +257,24 @@ export function createHandlerContext<TEnv>(
     url,
     originalUrl: new URL(request.url),
     env: bindings,
-    var: variables,
-    get: ((keyOrVar: any) => contextGet(variables, keyOrVar)) as HandlerContext<
-      any,
-      TEnv
-    >["get"],
-    set: ((keyOrVar: any, value: any) => {
+    _variables: variables,
+    get: ((keyOrVar: any) => {
+      // Read-time guard: non-cacheable var inside cache() → throw.
+      // Works for both ContextVar tokens and string keys.
+      if (isNonCacheable(variables, keyOrVar) && isInsideCacheScope()) {
+        throw new Error(
+          `ctx.get() for a non-cacheable variable cannot be called inside a cache() boundary. ` +
+            `The variable was created with { cache: false } or set with { cache: false }, ` +
+            `and its value would be stale on cache hit. Move the read outside the cached scope.`,
+        );
+      }
+      return contextGet(variables, keyOrVar);
+    }) as HandlerContext<any, TEnv>["get"],
+    set: ((keyOrVar: any, value: any, options?: ContextSetOptions) => {
       assertNotInsideCacheExec(ctx, "set");
-      contextSet(variables, keyOrVar, value);
+      // Write is dumb: store value + non-cacheable metadata.
+      // Enforcement happens at read time via ctx.get().
+      contextSet(variables, keyOrVar, value, options);
     }) as HandlerContext<any, TEnv>["set"],
     res: stubResponse, // Stub response for setting headers
     headers: guardedHeaders, // Guarded shorthand for res.headers
@@ -297,7 +320,7 @@ export function createHandlerContext<TEnv>(
  *
  * Returns an InternalHandlerContext where params, pathname, url, searchParams,
  * search, reverse, and use(handle) work. Request-time properties
- * (request, env, headers, cookies, var, get, set, res) throw with a clear error.
+ * (request, env, headers, cookies, get, set, res) throw with a clear error.
  */
 export function createPrerenderContext<TEnv>(
   params: Record<string, string>,
@@ -331,9 +354,7 @@ export function createPrerenderContext<TEnv>(
     get env(): TEnv {
       return throwUnavailable("env");
     },
-    get var(): any {
-      return throwUnavailable("var");
-    },
+    _variables: variables,
     get: ((keyOrVar: any) => contextGet(variables, keyOrVar)) as any,
     set: ((keyOrVar: any, value: any) => {
       contextSet(variables, keyOrVar, value);
@@ -415,9 +436,7 @@ export function createStaticContext<TEnv>(
     get env(): TEnv {
       return throwUnavailable("env");
     },
-    get var(): any {
-      return throwUnavailable("var");
-    },
+    _variables: variables,
     get: ((keyOrVar: any) => contextGet(variables, keyOrVar)) as any,
     set: ((keyOrVar: any, value: any) => {
       contextSet(variables, keyOrVar, value);

package/src/router/intercept-resolution.ts

@@ -11,7 +11,11 @@ import type {
   InterceptEntry,
   InterceptSelectorContext,
 } from "../server/context";
-import type { HandlerContext, ResolvedSegment } from "../types";
+import type {
+  HandlerContext,
+  InternalHandlerContext,
+  ResolvedSegment,
+} from "../types";
 import { evaluateRevalidation } from "./revalidation.js";
 import { getRequestContext } from "../server/request-context.js";
 import { executeInterceptMiddleware } from "./middleware.js";
@@ -20,6 +24,7 @@ import { getGlobalRouteMap } from "../route-map-builder.js";
 import { handleHandlerResult } from "./segment-resolution.js";
 import type { SegmentResolutionDeps } from "./types.js";
 import { debugLog } from "./logging.js";
+import { runInsideLoaderScope } from "../server/context.js";
 
 /**
  * Check if an intercept's when conditions are satisfied.
@@ -133,7 +138,7 @@ export async function resolveInterceptEntry<TEnv>(
       context.request,
       context.env,
       params,
-      context.var as Record<string, any>,
+      (context as InternalHandlerContext<any, TEnv>)._variables,
       requestCtx.res,
       createReverseFunction(getGlobalRouteMap()),
     );
@@ -207,7 +212,7 @@ export async function resolveInterceptEntry<TEnv>(
     loaderIds.push(loader.$$id);
     loaderPromises.push(
       deps.wrapLoaderPromise(
-        context.use(loader),
+        runInsideLoaderScope(() => context.use(loader)),
         parentEntry,
         segmentId,
         context.pathname,
@@ -374,7 +379,7 @@ export async function resolveInterceptLoadersOnly<TEnv>(
     loaderIds.push(loader.$$id);
     loaderPromises.push(
       deps.wrapLoaderPromise(
-        context.use(loader),
+        runInsideLoaderScope(() => context.use(loader)),
         parentEntry,
         segmentId,
         context.pathname,

package/src/router/loader-resolution.ts

@@ -7,6 +7,7 @@
 import type { ReactNode } from "react";
 import { track } from "../server/context";
 import type { EntryData } from "../server/context";
+import { contextGet } from "../context-var.js";
 import type {
   ResolvedSegment,
   HandlerContext,
@@ -241,6 +242,12 @@ function createLoaderExecutor<TEnv>(
     pendingLoaders.add(loader.$$id);
 
     const currentLoaderId = loader.$$id;
+    const variables = (ctx as InternalHandlerContext<any, TEnv>)._variables;
+    // Loader functions are always fresh (never cached), so they get an
+    // unguarded get that bypasses non-cacheable read guards. This applies
+    // to ALL loaders — DSL and handler-called — because the loader
+    // function itself always re-executes. Also handles nested deps
+    // (loaderA → use(loaderB)) since all share this unguarded get.
     const loaderCtx: LoaderContext<Record<string, string | undefined>, TEnv> = {
       params: ctx.params,
       routeParams: (ctx.params ?? {}) as Record<string, string>,
@@ -250,8 +257,8 @@ function createLoaderExecutor<TEnv>(
       pathname: ctx.pathname,
       url: ctx.url,
       env: ctx.env,
-      var: ctx.var,
-      get: ctx.get,
+      get: ((keyOrVar: any) =>
+        contextGet(variables, keyOrVar)) as typeof ctx.get,
       use: <TDep, TDepParams = any>(
         dep: LoaderDefinition<TDep, TDepParams>,
       ): Promise<TDep> => {

package/src/router/logging.ts

@@ -74,7 +74,7 @@ function getHeaderRequestId(request: Request): string | null {
   return trimmed.length > 0 ? trimmed : null;
 }
 
-function getOrCreateRequestId(request: Request): string {
+export function getOrCreateRequestId(request: Request): string {
   const existing = requestIds.get(request);
   if (existing) return existing;
 

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

@@ -103,7 +103,8 @@ import type { ResolvedSegment } from "../../types.js";
 import type { MatchContext, MatchPipelineState } from "../match-context.js";
 import { getRouterContext } from "../router-context.js";
 import type { GeneratorMiddleware } from "./cache-lookup.js";
-import { debugLog, debugWarn } from "../logging.js";
+import { debugLog, debugWarn, getOrCreateRequestId } from "../logging.js";
+import { INTERNAL_RANGO_DEBUG } from "../../internal-debug.js";
 
 /**
  * Creates background revalidation middleware
@@ -143,8 +144,19 @@ export function withBackgroundRevalidation<TEnv>(
 
     const requestCtx = getRequestContext();
     const cacheScope = ctx.cacheScope;
+    const reqId = INTERNAL_RANGO_DEBUG
+      ? getOrCreateRequestId(ctx.request)
+      : 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,
         fullMatch: ctx.isFullMatch,
@@ -174,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,
@@ -182,6 +196,7 @@ export function withBackgroundRevalidation<TEnv>(
             ctx.matched.params,
             freshHandlerContext,
             freshLoaderPromises,
+            { skipLoaders: true },
           ),
         );
 
@@ -207,16 +222,29 @@ export function withBackgroundRevalidation<TEnv>(
           completeSegments,
           ctx.isIntercept,
         );
+        if (INTERNAL_RANGO_DEBUG) {
+          const dur = performance.now() - start;
+          console.log(
+            `[RSC Background][req:${reqId}] SWR revalidation ${ctx.pathname} (${dur.toFixed(2)}ms) segments=${completeSegments.length}`,
+          );
+        }
         debugLog("backgroundRevalidation", "revalidation complete", {
           pathname: ctx.pathname,
         });
       } catch (error) {
+        if (INTERNAL_RANGO_DEBUG) {
+          const dur = performance.now() - start;
+          console.log(
+            `[RSC Background][req:${reqId}] SWR revalidation ${ctx.pathname} FAILED (${dur.toFixed(2)}ms) error=${String(error)}`,
+          );
+        }
         debugWarn("backgroundRevalidation", "revalidation failed", {
           pathname: ctx.pathname,
           error: String(error),
         });
       } finally {
         requestCtx._handleStore = originalHandleStore;
+        ctx.Store.metrics = savedMetrics;
       }
     });
   };

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

@@ -70,9 +70,11 @@
  *   - No segments yielded from this middleware
  *
  * Loaders:
- *   - NEVER cached by design
+ *   - NEVER cached in the segment cache
  *   - Always resolved fresh on every request
  *   - Ensures data freshness even with cached UI components
+ *   - Segment cache staleness does NOT propagate to loader revalidation;
+ *     loaders use their own revalidation rules (actionId, user-defined)
  *
  *
  * REVALIDATION RULES
@@ -210,6 +212,9 @@ async function* yieldFromStore<TEnv>(
   }
 
   // Resolve loaders fresh (loaders are never pre-rendered/cached)
+  const ms = ctx.metricsStore;
+  const loaderStart = performance.now();
+
   if (ctx.isFullMatch) {
     if (resolveLoadersOnly) {
       const loaderSegments = await ctx.Store.run(() =>
@@ -249,11 +254,17 @@ async function* yieldFromStore<TEnv>(
     }
   }
 
-  const ms = ctx.metricsStore;
   if (ms) {
+    const loaderEnd = performance.now();
     ms.metrics.push({
-      label: "pipeline:cache-lookup",
-      duration: performance.now() - pipelineStart,
+      label: "pipeline:loader-resolve",
+      duration: loaderEnd - loaderStart,
+      startTime: loaderStart - ms.requestStart,
+      depth: 1,
+    });
+    ms.metrics.push({
+      label: "pipeline:cache-hit",
+      duration: loaderEnd - pipelineStart,
       startTime: pipelineStart - ms.requestStart,
     });
   }
@@ -305,7 +316,10 @@ 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);
@@ -437,7 +451,7 @@ export function withCacheLookup<TEnv>(
       yield* source;
       if (ms) {
         ms.metrics.push({
-          label: "pipeline:cache-lookup",
+          label: "pipeline:cache-miss",
           duration: performance.now() - pipelineStart,
           startTime: pipelineStart - ms.requestStart,
         });
@@ -457,7 +471,7 @@ export function withCacheLookup<TEnv>(
       yield* source;
       if (ms) {
         ms.metrics.push({
-          label: "pipeline:cache-lookup",
+          label: "pipeline:cache-miss",
           duration: performance.now() - pipelineStart,
           startTime: pipelineStart - ms.requestStart,
         });
@@ -509,7 +523,41 @@ export function withCacheLookup<TEnv>(
 
       // Look up revalidation rules for this segment
       const entryInfo = entryRevalidateMap?.get(segment.id);
+
+      // Even without explicit revalidation rules, route segments and their
+      // 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 || routeParamsChanged) &&
+        (segment.type === "route" ||
+          (segment.belongsToRoute &&
+            (segment.type === "layout" || segment.type === "parallel")));
+
       if (!entryInfo || entryInfo.revalidate.length === 0) {
+        if (shouldDefaultRevalidate) {
+          // Params or search params changed — must re-render even without custom rules
+          if (isTraceActive()) {
+            pushRevalidationTraceEntry({
+              segmentId: segment.id,
+              segmentType: segment.type,
+              belongsToRoute: segment.belongsToRoute ?? false,
+              source: "cache-hit",
+              defaultShouldRevalidate: true,
+              finalShouldRevalidate: true,
+              reason: routeParamsChanged
+                ? "cached-params-changed"
+                : "cached-search-changed",
+            });
+          }
+          yield segment;
+          continue;
+        }
         // No revalidation rules, use default behavior (skip if client has)
         if (isTraceActive()) {
           pushRevalidationTraceEntry({
@@ -573,6 +621,7 @@ export function withCacheLookup<TEnv>(
     // Resolve loaders fresh (loaders are NOT cached by default)
     // This ensures fresh data even on cache hit
     const Store = ctx.Store;
+    const loaderStart = performance.now();
 
     if (ctx.isFullMatch) {
       // Full match (document request) - simple loader resolution without revalidation
@@ -605,7 +654,11 @@ export function withCacheLookup<TEnv>(
             ctx.url,
             ctx.routeKey,
             ctx.actionContext,
-            cacheResult.shouldRevalidate || undefined,
+            // Loaders are never cached in the segment cache, so segment
+            // staleness (cacheResult.shouldRevalidate) must not propagate.
+            // But browser-sent staleness (ctx.stale) — indicating an action
+            // happened in this or another tab — must still reach loaders.
+            ctx.stale || undefined,
           ),
         );
 
@@ -624,9 +677,16 @@ export function withCacheLookup<TEnv>(
       }
     }
     if (ms) {
+      const loaderEnd = performance.now();
+      ms.metrics.push({
+        label: "pipeline:loader-resolve",
+        duration: loaderEnd - loaderStart,
+        startTime: loaderStart - ms.requestStart,
+        depth: 1,
+      });
       ms.metrics.push({
-        label: "pipeline:cache-lookup",
-        duration: performance.now() - pipelineStart,
+        label: "pipeline:cache-hit",
+        duration: loaderEnd - pipelineStart,
         startTime: pipelineStart - ms.requestStart,
       });
     }

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

@@ -104,7 +104,8 @@ import type { ResolvedSegment } from "../../types.js";
 import { getRequestContext } from "../../server/request-context.js";
 import type { MatchContext, MatchPipelineState } from "../match-context.js";
 import { getRouterContext } from "../router-context.js";
-import { debugLog, debugWarn } from "../logging.js";
+import { debugLog, debugWarn, getOrCreateRequestId } from "../logging.js";
+import { INTERNAL_RANGO_DEBUG } from "../../internal-debug.js";
 import type { GeneratorMiddleware } from "./cache-lookup.js";
 
 /**
@@ -120,7 +121,6 @@ export function withCacheStore<TEnv>(
   return async function* (
     source: AsyncGenerator<ResolvedSegment>,
   ): AsyncGenerator<ResolvedSegment> {
-    const pipelineStart = performance.now();
     const ms = ctx.metricsStore;
 
     // Collect all segments while passing them through
@@ -130,6 +130,9 @@ export function withCacheStore<TEnv>(
       yield segment;
     }
 
+    // Measure own work only (after source iteration completes)
+    const ownStart = performance.now();
+
     // Skip caching if:
     // 1. Cache miss but cache scope is disabled
     // 2. This is an action (actions don't cache)
@@ -144,8 +147,8 @@ export function withCacheStore<TEnv>(
       if (ms) {
         ms.metrics.push({
           label: "pipeline:cache-store",
-          duration: performance.now() - pipelineStart,
-          startTime: pipelineStart - ms.requestStart,
+          duration: performance.now() - ownStart,
+          startTime: ownStart - ms.requestStart,
         });
       }
       return;
@@ -162,16 +165,23 @@ export function withCacheStore<TEnv>(
     // Combine main segments with intercept segments
     const allSegmentsToCache = [...allSegments, ...state.interceptSegments];
 
-    // Check if any non-loader segments have null components
-    // This happens when client already had those segments (partial navigation)
+    // Check if any non-loader segments have null components from revalidation
+    // skip (client already had them). Segments where the handler intentionally
+    // returned null are not revalidation skips — re-rendering them will still
+    // produce null, so proactive caching would be wasted work.
+    const clientIdSet = new Set(ctx.clientSegmentIds);
     const hasNullComponents = allSegmentsToCache.some(
-      (s) => s.component === null && s.type !== "loader",
+      (s) =>
+        s.component === null && s.type !== "loader" && clientIdSet.has(s.id),
     );
 
     const requestCtx = getRequestContext();
     if (!requestCtx) return;
 
     const cacheScope = ctx.cacheScope;
+    const reqId = INTERNAL_RANGO_DEBUG
+      ? getOrCreateRequestId(ctx.request)
+      : undefined;
 
     // Register onResponse callback to skip caching for non-200 responses
     // Note: error/notFound status codes are set elsewhere (not caching-specific)
@@ -189,6 +199,11 @@ export function withCacheStore<TEnv>(
         // Proactive caching: render all segments fresh in background
         // This ensures cache has complete components for future requests
         requestCtx.waitUntil(async () => {
+          // Prevent background metrics from polluting foreground timeline.
+          const savedMetrics = ctx.Store.metrics;
+          ctx.Store.metrics = undefined;
+
+          const start = performance.now();
           debugLog("cacheStore", "proactive caching started", {
             pathname: ctx.pathname,
           });
@@ -218,7 +233,9 @@ export function withCacheStore<TEnv>(
             // Use normal loader access so handle data is captured
             setupLoaderAccess(proactiveHandlerContext, proactiveLoaderPromises);
 
-            // Re-resolve ALL segments without revalidation
+            // Re-resolve ALL segments without revalidation.
+            // Skip DSL loaders — they are never cached (cacheRoute filters them)
+            // and are always resolved fresh on each request.
             const Store = ctx.Store;
             const freshSegments = await Store.run(() =>
               resolveAllSegments(
@@ -227,6 +244,7 @@ export function withCacheStore<TEnv>(
                 ctx.matched.params,
                 proactiveHandlerContext,
                 proactiveLoaderPromises,
+                { skipLoaders: true },
               ),
             );
 
@@ -256,28 +274,53 @@ export function withCacheStore<TEnv>(
               completeSegments,
               ctx.isIntercept,
             );
+            if (INTERNAL_RANGO_DEBUG) {
+              const dur = performance.now() - start;
+              console.log(
+                `[RSC Background][req:${reqId}] Proactive cache ${ctx.pathname} (${dur.toFixed(2)}ms) segments=${completeSegments.length}`,
+              );
+            }
             debugLog("cacheStore", "proactive caching complete", {
               pathname: ctx.pathname,
             });
           } catch (error) {
+            if (INTERNAL_RANGO_DEBUG) {
+              const dur = performance.now() - start;
+              console.log(
+                `[RSC Background][req:${reqId}] Proactive cache ${ctx.pathname} FAILED (${dur.toFixed(2)}ms) error=${String(error)}`,
+              );
+            }
             debugWarn("cacheStore", "proactive caching failed", {
               pathname: ctx.pathname,
               error: String(error),
             });
           } finally {
             requestCtx._handleStore = originalHandleStore;
+            ctx.Store.metrics = savedMetrics;
           }
         });
       } else {
         // All segments have components - cache directly
         // Schedule caching in waitUntil since cacheRoute is now async (key resolution)
+        if (INTERNAL_RANGO_DEBUG) {
+          console.log(
+            `[RSC CacheStore][req:${reqId}] Direct cache path: scheduling cacheRoute for ${ctx.pathname} (${allSegmentsToCache.length} segments, hasNullComponents=${hasNullComponents})`,
+          );
+        }
         requestCtx.waitUntil(async () => {
+          const start = performance.now();
           await cacheScope.cacheRoute(
             ctx.pathname,
             ctx.matched.params,
             allSegmentsToCache,
             ctx.isIntercept,
           );
+          if (INTERNAL_RANGO_DEBUG) {
+            const dur = performance.now() - start;
+            console.log(
+              `[RSC Background][req:${reqId}] Cache store ${ctx.pathname} (${dur.toFixed(2)}ms) segments=${allSegmentsToCache.length}`,
+            );
+          }
         });
       }
 
@@ -287,8 +330,8 @@ export function withCacheStore<TEnv>(
     if (ms) {
       ms.metrics.push({
         label: "pipeline:cache-store",
-        duration: performance.now() - pipelineStart,
-        startTime: pipelineStart - ms.requestStart,
+        duration: performance.now() - ownStart,
+        startTime: ownStart - ms.requestStart,
       });
     }
   };