@rangojs/router 0.0.0-experimental.fa8a383a → 0.0.0-experimental.ffbe1b7f

package/src/cache/cache-runtime.ts

@@ -214,11 +214,21 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
             bgStopCapture = c.stop;
           }
 
-          // Stamp tainted args and RequestContext so request-scoped
-          // reads (cookies, headers) and side effects (ctx.set, etc.)
-          // throw inside background revalidation, same as the miss path.
-          // Uses ref-counted stamp/unstamp so overlapping executions
-          // sharing the same ctx don't clear each other's guards.
+          // Stamp tainted ARGS only — not requestCtx. The args stamp guards
+          // direct ctx method calls (ctx.set, ctx.header, ctx.onResponse, etc.)
+          // which is sufficient for correctness.
+          //
+          // We intentionally skip stamping requestCtx here because:
+          // 1. runBackground starts the async task synchronously (before the
+          //    first await), so stampCacheExec would pollute the shared
+          //    requestCtx while the foreground pipeline is still running.
+          //    This causes assertNotInsideCacheExec to fire when cache-store
+          //    later calls requestCtx.onResponse().
+          // 2. requestCtx methods are closure-bound to the original ctx, so
+          //    neither Object.create() nor a proxy can isolate the stamp.
+          // 3. The foreground miss path already stamps requestCtx and catches
+          //    cookies()/headers() misuse on first execution. The background
+          //    re-runs the same function with the same request.
           const bgTaintedArgs: unknown[] = [];
           for (const arg of args) {
             if (isTainted(arg)) {
@@ -226,9 +236,6 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
               bgTaintedArgs.push(arg);
             }
           }
-          if (requestCtx) {
-            stampCacheExec(requestCtx as object);
-          }
 
           try {
             const freshResult = await fn.apply(this, args);
@@ -249,9 +256,6 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
             for (const arg of bgTaintedArgs) {
               unstampCacheExec(arg as object);
             }
-            if (requestCtx) {
-              unstampCacheExec(requestCtx as object);
-            }
             // Restore original handle store
             if (originalHandleStore && requestCtx) {
               requestCtx._handleStore = originalHandleStore;

package/src/cache/cache-scope.ts

@@ -328,22 +328,59 @@ export class CacheScope {
     // Check if this is a partial request (navigation) vs document request
     const isPartial = requestCtx.originalUrl.searchParams.has("_rsc_partial");
 
+    if (INTERNAL_RANGO_DEBUG) {
+      debugCacheLog(
+        `[CacheScope] cacheRoute: scheduling waitUntil for ${key} (${nonLoaderSegments.length} segments, isPartial=${isPartial})`,
+      );
+    }
+
     requestCtx.waitUntil(async () => {
+      if (INTERNAL_RANGO_DEBUG) {
+        debugCacheLog(
+          `[CacheScope] waitUntil: awaiting handleStore.settled for ${key}`,
+        );
+      }
+
       await handleStore.settled;
 
-      // For document requests: only cache if ALL segments have components (complete render)
-      // For partial requests: null components are expected (client already has them)
+      if (INTERNAL_RANGO_DEBUG) {
+        debugCacheLog(`[CacheScope] waitUntil: handleStore settled for ${key}`);
+      }
+
+      // For document requests: only cache if layout segments have components
+      // (complete render). Parallel and route segments may legitimately have
+      // null components — UI-less @meta parallels return null, and void route
+      // handlers produce null when the UI lives in parallel slots/layouts.
+      // Partial requests always allow null components (client already has them).
       if (!isPartial) {
-        const hasAllComponents = nonLoaderSegments.every(
-          (s) => s.component !== null,
+        const hasIncompleteLayouts = nonLoaderSegments.some(
+          (s) => s.component === null && s.type === "layout",
         );
-        if (!hasAllComponents) return;
+        if (hasIncompleteLayouts) {
+          const nullSegments = nonLoaderSegments
+            .filter((s) => s.component === null && s.type === "layout")
+            .map((s) => s.id);
+          const error = new Error(
+            `[CacheScope] Cache write skipped: layout segments have null components ` +
+              `(${nullSegments.join(", ")}). This indicates an incomplete render — ` +
+              `layout handlers must return JSX for document requests to be cacheable.`,
+          );
+          error.name = "CacheScopeInvariantError";
+          console.error(error.message);
+          return;
+        }
       }
 
       // Collect handle data for non-loader segments only
       const handles = captureHandles(nonLoaderSegments, handleStore);
 
       try {
+        if (INTERNAL_RANGO_DEBUG) {
+          debugCacheLog(
+            `[CacheScope] waitUntil: serializing ${nonLoaderSegments.length} segments for ${key}`,
+          );
+        }
+
         // Serialize non-loader segments only
         const serializedSegments = await serializeSegments(nonLoaderSegments);
 
@@ -353,6 +390,10 @@ export class CacheScope {
           expiresAt: Date.now() + ttl * 1000,
         };
 
+        if (INTERNAL_RANGO_DEBUG) {
+          debugCacheLog(`[CacheScope] waitUntil: calling store.set for ${key}`);
+        }
+
         await store.set(key, data, ttl, swr);
 
         if (INTERNAL_RANGO_DEBUG) {

package/src/cache/taint.ts

@@ -81,6 +81,61 @@ export function assertNotInsideCacheExec(
   }
 }
 
+/**
+ * Symbol stamped on ctx when resolving handlers inside a cache() DSL boundary.
+ * Separate from INSIDE_CACHE_EXEC ("use cache") because cache() allows
+ * ctx.set() (children are also cached) but blocks response-level side effects
+ * (headers, cookies, status) which are lost on cache hit.
+ */
+export const INSIDE_CACHE_SCOPE: unique symbol = Symbol.for(
+  "rango:inside-cache-scope",
+) as any;
+
+/**
+ * Mark ctx as inside a cache() scope. Must be paired with unstampCacheScope.
+ */
+export function stampCacheScope(obj: object): void {
+  const current = (obj as any)[INSIDE_CACHE_SCOPE] ?? 0;
+  (obj as any)[INSIDE_CACHE_SCOPE] = current + 1;
+}
+
+/**
+ * Remove cache() scope mark.
+ */
+export function unstampCacheScope(obj: object): void {
+  const current = (obj as any)[INSIDE_CACHE_SCOPE] ?? 0;
+  if (current <= 1) {
+    delete (obj as any)[INSIDE_CACHE_SCOPE];
+  } else {
+    (obj as any)[INSIDE_CACHE_SCOPE] = current - 1;
+  }
+}
+
+/**
+ * Throw if ctx is inside a cache() DSL boundary.
+ * Call from response-level side effects (header, setCookie, setStatus, etc.)
+ * which are lost on cache hit because the handler body is skipped.
+ * ctx.set() is allowed inside cache() — children are also cached and can
+ * read the value.
+ */
+export function assertNotInsideCacheScope(
+  ctx: unknown,
+  methodName: string,
+): void {
+  if (
+    ctx !== null &&
+    ctx !== undefined &&
+    typeof ctx === "object" &&
+    (INSIDE_CACHE_SCOPE as symbol) in (ctx as Record<symbol, unknown>)
+  ) {
+    throw new Error(
+      `ctx.${methodName}() cannot be called inside a cache() boundary. ` +
+        `On cache hit the handler is skipped, so this side effect would be lost. ` +
+        `Move ctx.${methodName}() to a middleware or layout outside the cache() scope.`,
+    );
+  }
+}
+
 /**
  * Brand symbol for functions wrapped by registerCachedFunction().
  * Used at runtime to detect when a "use cache" function is misused

package/src/context-var.ts

@@ -12,6 +12,9 @@
  * interface PaginationData { current: number; total: number }
  * export const Pagination = createVar<PaginationData>();
  *
+ * // Non-cacheable var — throws if set/get inside cache() or "use cache"
+ * export const User = createVar<UserData>({ cache: false });
+ *
  * // handler
  * ctx.set(Pagination, { current: 1, total: 4 });
  *
@@ -23,18 +26,36 @@
 export interface ContextVar<T> {
   readonly __brand: "context-var";
   readonly key: symbol;
+  /** When false, the var is non-cacheable — throws inside cache() / "use cache" */
+  readonly cache: boolean;
   /** Phantom field to carry the type parameter. Never set at runtime. */
   readonly __type?: T;
 }
 
+export interface ContextVarOptions {
+  /**
+   * When false, marks this variable as non-cacheable.
+   * Setting or getting this var inside a cache() boundary or "use cache"
+   * function will throw. Use for inherently request-specific data (user
+   * sessions, auth tokens, etc.) that must never be baked into cached segments.
+   *
+   * @default true
+   */
+  cache?: boolean;
+}
+
 /**
  * Create a typed context variable token.
  *
  * The returned object is used with ctx.set(token, value) and ctx.get(token)
  * for compile-time-checked data flow between handlers, layouts, and middleware.
  */
-export function createVar<T>(): ContextVar<T> {
-  return { __brand: "context-var" as const, key: Symbol() };
+export function createVar<T>(options?: ContextVarOptions): ContextVar<T> {
+  return {
+    __brand: "context-var" as const,
+    key: Symbol(),
+    cache: options?.cache !== false,
+  };
 }
 
 /**
@@ -49,6 +70,36 @@ export function isContextVar(value: unknown): value is ContextVar<unknown> {
   );
 }
 
+/**
+ * Symbol used as a Set stored on the variables object to track
+ * which keys hold non-cacheable values (from write-level { cache: false }).
+ */
+const NON_CACHEABLE_KEYS: unique symbol = Symbol.for(
+  "rango:non-cacheable-keys",
+) as any;
+
+function getNonCacheableKeys(variables: any): Set<string | symbol> {
+  if (!variables[NON_CACHEABLE_KEYS]) {
+    variables[NON_CACHEABLE_KEYS] = new Set();
+  }
+  return variables[NON_CACHEABLE_KEYS];
+}
+
+/**
+ * Check if a variable value is non-cacheable (either var-level or write-level).
+ */
+export function isNonCacheable(
+  variables: any,
+  keyOrVar: string | ContextVar<any>,
+): boolean {
+  if (typeof keyOrVar !== "string" && !keyOrVar.cache) {
+    return true; // var-level policy
+  }
+  const key = typeof keyOrVar === "string" ? keyOrVar : keyOrVar.key;
+  const set = variables[NON_CACHEABLE_KEYS] as Set<string | symbol> | undefined;
+  return set?.has(key) ?? false; // write-level policy
+}
+
 /**
  * Read a variable from the variables store.
  * Accepts either a string key (legacy) or a ContextVar token (typed).
@@ -64,6 +115,17 @@ export function contextGet(
 /** Keys that must never be used as string variable names */
 const FORBIDDEN_KEYS = new Set(["__proto__", "constructor", "prototype"]);
 
+export interface ContextSetOptions {
+  /**
+   * When false, marks this specific write as non-cacheable.
+   * "Least cacheable wins" — if either the var definition or this option
+   * says cache: false, the value is non-cacheable.
+   *
+   * @default true (inherits from createVar)
+   */
+  cache?: boolean;
+}
+
 /**
  * Write a variable to the variables store.
  * Accepts either a string key (legacy) or a ContextVar token (typed).
@@ -72,6 +134,7 @@ export function contextSet(
   variables: any,
   keyOrVar: string | ContextVar<any>,
   value: any,
+  options?: ContextSetOptions,
 ): void {
   if (typeof keyOrVar === "string") {
     if (FORBIDDEN_KEYS.has(keyOrVar)) {
@@ -80,7 +143,14 @@ export function contextSet(
       );
     }
     variables[keyOrVar] = value;
+    if (options?.cache === false) {
+      getNonCacheableKeys(variables).add(keyOrVar);
+    }
   } else {
     variables[keyOrVar.key] = value;
+    // Track write-level non-cacheable (var-level is checked via keyOrVar.cache)
+    if (options?.cache === false) {
+      getNonCacheableKeys(variables).add(keyOrVar.key);
+    }
   }
 }

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/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";
@@ -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);
           };
         }
@@ -245,13 +258,23 @@ export function createHandlerContext<TEnv>(
     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) => {
+    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

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,11 @@ function createLoaderExecutor<TEnv>(
     pendingLoaders.add(loader.$$id);
 
     const currentLoaderId = loader.$$id;
+    // 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>,
@@ -251,7 +257,7 @@ function createLoaderExecutor<TEnv>(
       url: ctx.url,
       env: ctx.env,
       var: ctx.var,
-      get: ctx.get,
+      get: ((keyOrVar: any) => contextGet(ctx.var, keyOrVar)) as typeof ctx.get,
       use: <TDep, TDepParams = any>(
         dep: LoaderDefinition<TDep, TDepParams>,
       ): Promise<TDep> => {

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

@@ -149,6 +149,13 @@ export function withBackgroundRevalidation<TEnv>(
       : 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,
@@ -179,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,
@@ -187,6 +196,7 @@ export function withBackgroundRevalidation<TEnv>(
             ctx.matched.params,
             freshHandlerContext,
             freshLoaderPromises,
+            { skipLoaders: true },
           ),
         );
 
@@ -234,6 +244,7 @@ export function withBackgroundRevalidation<TEnv>(
         });
       } 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
@@ -261,7 +263,7 @@ async function* yieldFromStore<TEnv>(
       depth: 1,
     });
     ms.metrics.push({
-      label: "pipeline:cache-lookup",
+      label: "pipeline:cache-hit",
       duration: loaderEnd - pipelineStart,
       startTime: pipelineStart - ms.requestStart,
     });
@@ -446,7 +448,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,
         });
@@ -466,7 +468,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,
         });
@@ -518,7 +520,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({
@@ -615,7 +651,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,
           ),
         );
 
@@ -642,7 +682,7 @@ export function withCacheLookup<TEnv>(
         depth: 1,
       });
       ms.metrics.push({
-        label: "pipeline:cache-lookup",
+        label: "pipeline:cache-hit",
         duration: loaderEnd - pipelineStart,
         startTime: pipelineStart - ms.requestStart,
       });

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

@@ -165,10 +165,14 @@ 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();
@@ -195,6 +199,10 @@ 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,
@@ -225,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(
@@ -234,6 +244,7 @@ export function withCacheStore<TEnv>(
                 ctx.matched.params,
                 proactiveHandlerContext,
                 proactiveLoaderPromises,
+                { skipLoaders: true },
               ),
             );
 
@@ -285,11 +296,17 @@ export function withCacheStore<TEnv>(
             });
           } 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(

package/src/router/match-result.ts

@@ -67,10 +67,11 @@
  *   Keep if:
  *     - component !== null (needs rendering)
  *     - type === "loader" (carries data even with null component)
+ *     - client doesn't have the segment (structurally required parent node)
  *
  *   Skip if:
- *     - component === null AND type !== "loader"
- *     - (Client already has this segment's UI)
+ *     - component === null AND type !== "loader" AND client has it cached
+ *     - (Revalidation skip — client already has this segment's UI)
  *
  *
  * INTERCEPT HANDLING
@@ -168,10 +169,15 @@ export function buildMatchResult<TEnv>(
     // Deduplicate allIds (defense-in-depth for partial match path)
     allIds = [...new Set(allIds)];
 
-    // Filter out segments with null components (client already has them)
-    // BUT always include loader segments - they carry data even with null component
+    // Filter out null-component segments only when the client already has
+    // them cached (revalidation skip). If the client doesn't have the segment,
+    // it must be included even with null component — it's structurally required
+    // as a parent node for child layouts/parallels to reconcile against.
+    // Loader segments are always included as they carry data.
+    const clientIdSet = new Set(ctx.clientSegmentIds);
     segmentsToRender = allSegments.filter(
-      (s) => s.component !== null || s.type === "loader",
+      (s) =>
+        s.component !== null || s.type === "loader" || !clientIdSet.has(s.id),
     );
   }