@rangojs/router 0.0.0-experimental.46 → 0.0.0-experimental.47

package/dist/vite/index.js

@@ -1745,7 +1745,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.0.0-experimental.46",
+  version: "0.0.0-experimental.47",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.0.0-experimental.46",
+  "version": "0.0.0-experimental.47",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",

package/src/browser/partial-update.ts

@@ -259,6 +259,17 @@ export function createPartialUpdater(
             existingSegments,
           );
 
+          // Fix: tx.commit() cached the source page's handleData because
+          // eventController hasn't been updated yet. Overwrite with the
+          // correct cached handleData to prevent cache corruption on
+          // subsequent navigations to this same URL.
+          if (mode.targetCacheHandleData) {
+            store.updateCacheHandleData(
+              store.getHistoryKey(),
+              mode.targetCacheHandleData,
+            );
+          }
+
           // Include cachedHandleData in metadata so NavigationProvider can restore
           // breadcrumbs and other handle data from cache.
           // Remove `handles` from metadata to prevent NavigationProvider from

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/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,12 @@ export function withBackgroundRevalidation<TEnv>(
 
     const requestCtx = getRequestContext();
     const cacheScope = ctx.cacheScope;
+    const reqId = INTERNAL_RANGO_DEBUG
+      ? getOrCreateRequestId(ctx.request)
+      : undefined;
 
     requestCtx?.waitUntil(async () => {
+      const start = performance.now();
       debugLog("backgroundRevalidation", "revalidating stale route", {
         pathname: ctx.pathname,
         fullMatch: ctx.isFullMatch,
@@ -207,10 +212,22 @@ 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),

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,
     });
   }
@@ -437,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,
         });
@@ -457,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,
         });
@@ -509,7 +520,34 @@ 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 search params change — the handler reads
+      // ctx.searchParams so different ?page= values produce different content.
+      const searchChanged = ctx.prevUrl.search !== ctx.url.search;
+      const shouldDefaultRevalidate =
+        searchChanged &&
+        (segment.type === "route" ||
+          (segment.belongsToRoute &&
+            (segment.type === "layout" || segment.type === "parallel")));
+
       if (!entryInfo || entryInfo.revalidate.length === 0) {
+        if (shouldDefaultRevalidate) {
+          // 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: "cached-search-changed",
+            });
+          }
+          yield segment;
+          continue;
+        }
         // No revalidation rules, use default behavior (skip if client has)
         if (isTraceActive()) {
           pushRevalidationTraceEntry({
@@ -573,6 +611,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 +644,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 +667,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;
@@ -172,6 +175,9 @@ export function withCacheStore<TEnv>(
     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 +195,7 @@ export function withCacheStore<TEnv>(
         // Proactive caching: render all segments fresh in background
         // This ensures cache has complete components for future requests
         requestCtx.waitUntil(async () => {
+          const start = performance.now();
           debugLog("cacheStore", "proactive caching started", {
             pathname: ctx.pathname,
           });
@@ -256,10 +263,22 @@ 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),
@@ -272,12 +291,19 @@ export function withCacheStore<TEnv>(
         // All segments have components - cache directly
         // Schedule caching in waitUntil since cacheRoute is now async (key resolution)
         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 +313,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,
       });
     }
   };

package/src/router/match-middleware/intercept-resolution.ts

@@ -123,7 +123,6 @@ export function withInterceptResolution<TEnv>(
   return async function* (
     source: AsyncGenerator<ResolvedSegment>,
   ): AsyncGenerator<ResolvedSegment> {
-    const pipelineStart = performance.now();
     const ms = ctx.metricsStore;
 
     // First, yield all segments from the source (main segment resolution or cache)
@@ -133,13 +132,16 @@ export function withInterceptResolution<TEnv>(
       yield segment;
     }
 
+    // Measure own work only (after source iteration completes)
+    const ownStart = performance.now();
+
     // Skip intercept resolution for full match (document requests don't have intercepts)
     if (ctx.isFullMatch) {
       if (ms) {
         ms.metrics.push({
           label: "pipeline:intercept",
-          duration: performance.now() - pipelineStart,
-          startTime: pipelineStart - ms.requestStart,
+          duration: performance.now() - ownStart,
+          startTime: ownStart - ms.requestStart,
         });
       }
       return;
@@ -163,8 +165,8 @@ export function withInterceptResolution<TEnv>(
       if (ms) {
         ms.metrics.push({
           label: "pipeline:intercept",
-          duration: performance.now() - pipelineStart,
-          startTime: pipelineStart - ms.requestStart,
+          duration: performance.now() - ownStart,
+          startTime: ownStart - ms.requestStart,
         });
       }
       return;
@@ -216,8 +218,8 @@ export function withInterceptResolution<TEnv>(
     if (ms) {
       ms.metrics.push({
         label: "pipeline:intercept",
-        duration: performance.now() - pipelineStart,
-        startTime: pipelineStart - ms.requestStart,
+        duration: performance.now() - ownStart,
+        startTime: ownStart - ms.requestStart,
       });
     }
   };

package/src/router/match-middleware/segment-resolution.ts

@@ -104,7 +104,6 @@ export function withSegmentResolution<TEnv>(
   return async function* (
     source: AsyncGenerator<ResolvedSegment>,
   ): AsyncGenerator<ResolvedSegment> {
-    const pipelineStart = performance.now();
     const ms = ctx.metricsStore;
 
     // IMPORTANT: Always iterate source first to give cache-lookup a chance
@@ -113,13 +112,16 @@ export function withSegmentResolution<TEnv>(
       yield segment;
     }
 
+    // Measure own work only (after source iteration completes)
+    const ownStart = performance.now();
+
     // If cache hit, segments were already yielded by cache lookup
     if (state.cacheHit) {
       if (ms) {
         ms.metrics.push({
           label: "pipeline:segment-resolve",
-          duration: performance.now() - pipelineStart,
-          startTime: pipelineStart - ms.requestStart,
+          duration: performance.now() - ownStart,
+          startTime: ownStart - ms.requestStart,
         });
       }
       return;
@@ -185,8 +187,8 @@ export function withSegmentResolution<TEnv>(
     if (ms) {
       ms.metrics.push({
         label: "pipeline:segment-resolve",
-        duration: performance.now() - pipelineStart,
-        startTime: pipelineStart - ms.requestStart,
+        duration: performance.now() - ownStart,
+        startTime: ownStart - ms.requestStart,
       });
     }
   };

package/src/router/match-result.ts

@@ -109,6 +109,7 @@
 import type { MatchResult, ResolvedSegment } from "../types.js";
 import type { MatchContext, MatchPipelineState } from "./match-context.js";
 import { debugLog } from "./logging.js";
+import { appendMetric } from "./metrics.js";
 
 /**
  * Collect all segments from an async generator
@@ -210,10 +211,19 @@ export async function collectMatchResult<TEnv>(
 ): Promise<MatchResult> {
   const allSegments = await collectSegments(pipeline);
 
+  const buildStart = performance.now();
+
   // Update state with collected segments if not already set
   if (state.segments.length === 0) {
     state.segments = allSegments;
   }
 
-  return buildMatchResult(allSegments, ctx, state);
+  const result = buildMatchResult(allSegments, ctx, state);
+  appendMetric(
+    ctx.metricsStore,
+    "collect-result",
+    buildStart,
+    performance.now() - buildStart,
+  );
+  return result;
 }

package/src/router/metrics.ts

@@ -15,7 +15,12 @@ function formatMs(value: number): string {
 }
 
 function sortMetrics(metrics: PerformanceMetric[]): PerformanceMetric[] {
-  return [...metrics].sort((a, b) => a.startTime - b.startTime);
+  return [...metrics].sort((a, b) => {
+    // handler:total always goes last (it wraps everything)
+    if (a.label === "handler:total") return 1;
+    if (b.label === "handler:total") return -1;
+    return a.startTime - b.startTime;
+  });
 }
 
 interface Span {

package/src/router/segment-resolution/fresh.ts

@@ -19,6 +19,8 @@ import type {
 } from "../../types";
 import type { SegmentResolutionDeps } from "../types.js";
 import { resolveLoaderData } from "./loader-cache.js";
+import { _getRequestContext } from "../../server/request-context.js";
+import { appendMetric } from "../metrics.js";
 import {
   handleHandlerResult,
   tryStaticHandler,
@@ -94,8 +96,12 @@ export async function resolveLoaders<TEnv>(
   const shortCode = shortCodeOverride ?? entry.shortCode;
   const hasLoading = "loading" in entry && entry.loading !== undefined;
   const loadingDisabled = hasLoading && entry.loading === false;
+  const ms = _getRequestContext()?._metricsStore;
 
   if (!loadingDisabled) {
+    // Streaming loaders: promises kick off now, settle during RSC serialization.
+    // No per-loader timing here — settlement happens asynchronously during
+    // RSC/SSR stream consumption, after the perf timeline is logged.
     return loaderEntries.map((loaderEntry, i) => {
       const { loader } = loaderEntry;
       const segmentId = `${shortCode}D${i}.${loader.$$id}`;
@@ -120,14 +126,31 @@ export async function resolveLoaders<TEnv>(
 
   // Loading disabled: still start all loaders in parallel, but only emit
   // settled promises so handlers don't stream loading placeholders.
-  const pendingLoaderData = loaderEntries.map((loaderEntry) =>
-    resolveLoaderData(loaderEntry, ctx, ctx.pathname),
-  );
-  await Promise.all(pendingLoaderData);
+  // We can measure actual execution time here since we await all loaders.
+  const pendingLoaderData = loaderEntries.map((loaderEntry) => {
+    const start = performance.now();
+    const promise = resolveLoaderData(loaderEntry, ctx, ctx.pathname);
+    return { promise, start, loaderId: loaderEntry.loader.$$id };
+  });
+  await Promise.all(pendingLoaderData.map((p) => p.promise));
 
   return loaderEntries.map((loaderEntry, i) => {
     const { loader } = loaderEntry;
     const segmentId = `${shortCode}D${i}.${loader.$$id}`;
+    const pending = pendingLoaderData[i]!;
+    if (ms && !ms.metrics.some((m) => m.label === `loader:${loader.$$id}`)) {
+      // All loaders ran in parallel via Promise.all — each span covers
+      // from its own kickoff to the batch settlement, giving a ceiling
+      // on that loader's contribution to the overall wait.
+      const batchEnd = performance.now();
+      appendMetric(
+        ms,
+        `loader:${loader.$$id}`,
+        pending.start,
+        batchEnd - pending.start,
+        2,
+      );
+    }
     return {
       id: segmentId,
       namespace: entry.id,
@@ -137,7 +160,7 @@ export async function resolveLoaders<TEnv>(
       params: ctx.params,
       loaderId: loader.$$id,
       loaderData: deps.wrapLoaderPromise(
-        pendingLoaderData[i]!,
+        pending.promise,
         entry,
         segmentId,
         ctx.pathname,
@@ -601,20 +624,37 @@ export async function resolveLoadersOnly<TEnv>(
   deps: SegmentResolutionDeps<TEnv>,
 ): Promise<ResolvedSegment[]> {
   const loaderSegments: ResolvedSegment[] = [];
+  const seenIds = new Set<string>();
 
   async function collectEntryLoaders(
     entry: EntryData,
     belongsToRoute: boolean,
     shortCodeOverride?: string,
   ): Promise<void> {
-    const segments = await resolveLoaders(
-      entry,
-      context,
-      belongsToRoute,
-      deps,
-      shortCodeOverride,
-    );
-    loaderSegments.push(...segments);
+    // Skip if all loaders from this entry have already been resolved
+    // via a parent (e.g., cache boundary wrapping a layout with shared loaders).
+    const entryLoaders = entry.loader ?? [];
+    const sc = shortCodeOverride ?? entry.shortCode;
+    const allAlreadySeen =
+      entryLoaders.length > 0 &&
+      entryLoaders.every((le, i) =>
+        seenIds.has(`${sc}D${i}.${le.loader.$$id}`),
+      );
+    if (!allAlreadySeen) {
+      const segments = await resolveLoaders(
+        entry,
+        context,
+        belongsToRoute,
+        deps,
+        shortCodeOverride,
+      );
+      for (const seg of segments) {
+        if (!seenIds.has(seg.id)) {
+          seenIds.add(seg.id);
+          loaderSegments.push(seg);
+        }
+      }
+    }
 
     const seenParallelEntryIds = new Set<string>();
     for (const parallelEntry of getParallelEntries(entry.parallel)) {

package/src/router/segment-resolution/loader-cache.ts

@@ -147,6 +147,7 @@ export function resolveLoaderData<TEnv>(
   }
 
   const loaderId = loaderEntry.loader.$$id;
+
   const ttl = resolveTtl(options.ttl, store.defaults, DEFAULT_ROUTE_TTL);
   const swrWindow = resolveSwrWindow(options.swr, store.defaults);
   const swr = swrWindow || undefined;

package/src/router/segment-resolution/revalidation.ts

@@ -262,29 +262,46 @@ export async function resolveLoadersOnlyWithRevalidation<TEnv>(
 ): Promise<{ segments: ResolvedSegment[]; matchedIds: string[] }> {
   const allLoaderSegments: ResolvedSegment[] = [];
   const allMatchedIds: string[] = [];
+  const seenIds = new Set<string>();
 
   async function collectEntryLoaders(
     entry: EntryData,
     belongsToRoute: boolean,
     shortCodeOverride?: string,
   ): Promise<void> {
-    const { segments, matchedIds } = await resolveLoadersWithRevalidation(
-      entry,
-      context,
-      belongsToRoute,
-      clientSegmentIds,
-      prevParams,
-      request,
-      prevUrl,
-      nextUrl,
-      routeKey,
-      deps,
-      actionContext,
-      shortCodeOverride,
-      stale,
-    );
-    allLoaderSegments.push(...segments);
-    allMatchedIds.push(...matchedIds);
+    // Skip if all loaders from this entry have already been resolved
+    // via a parent (e.g., cache boundary wrapping a layout with shared loaders).
+    const loaderEntries = entry.loader ?? [];
+    const sc = shortCodeOverride ?? entry.shortCode;
+    const allAlreadySeen =
+      loaderEntries.length > 0 &&
+      loaderEntries.every((le, i) =>
+        seenIds.has(`${sc}D${i}.${le.loader.$$id}`),
+      );
+    if (!allAlreadySeen) {
+      const { segments, matchedIds } = await resolveLoadersWithRevalidation(
+        entry,
+        context,
+        belongsToRoute,
+        clientSegmentIds,
+        prevParams,
+        request,
+        prevUrl,
+        nextUrl,
+        routeKey,
+        deps,
+        actionContext,
+        shortCodeOverride,
+        stale,
+      );
+      for (const seg of segments) {
+        if (!seenIds.has(seg.id)) {
+          seenIds.add(seg.id);
+          allLoaderSegments.push(seg);
+        }
+      }
+      allMatchedIds.push(...matchedIds);
+    }
 
     const seenParallelEntryIds = new Set<string>();
     for (const parallelEntry of getParallelEntries(entry.parallel)) {

package/src/types/handler-context.ts

@@ -289,8 +289,12 @@ export type HandlerContext<
   /**
    * Access loader data or push handle data.
    *
+   * Available in route handlers, layout handlers, middleware, server actions,
+   * and server components rendered within the request context.
+   *
    * For loaders: Returns a promise that resolves to the loader data.
-   * Loaders are executed in parallel and memoized per request.
+   * Loaders are executed in parallel and memoized per request — calling
+   * `ctx.use(SameLoader)` multiple times returns the same promise.
    *
    * For handles: Returns a push function to add data for this segment.
    * Handle data accumulates across all matched route segments.
@@ -519,30 +523,112 @@ export type RevalidateParams<TParams = GenericParams, TEnv = any> = Parameters<
  * })
  * ```
  */
+/**
+ * Revalidation function called during client-side navigation to decide whether
+ * a segment (layout, route, parallel slot, or loader) should be re-rendered.
+ *
+ * Return `true` to re-render, `false` to skip (keep client's current version),
+ * or `{ defaultShouldRevalidate: boolean }` to override the default for
+ * downstream segments.
+ *
+ * @example
+ * ```ts
+ * // Re-render only when a cart action happened or browser signals staleness
+ * revalidate(({ actionId, stale }) =>
+ *   actionId?.includes("cart") || stale || false
+ * )
+ *
+ * // Always re-render when params change (default behavior made explicit)
+ * revalidate(({ defaultShouldRevalidate }) => defaultShouldRevalidate)
+ * ```
+ */
 export type ShouldRevalidateFn<TParams = GenericParams, TEnv = any> = (args: {
+  /** Route params from the page being navigated away from. */
   currentParams: TParams;
+  /** Full URL of the page being navigated away from. */
   currentUrl: URL;
+  /** Route params for the navigation target. */
   nextParams: TParams;
+  /** Full URL of the navigation target. */
   nextUrl: URL;
+  /**
+   * The router's default revalidation decision for this segment.
+   * `true` when params changed or the segment is new to the client.
+   * Return this when you want default behavior plus your own conditions.
+   */
   defaultShouldRevalidate: boolean;
+  /** Full handler context — access to `ctx.use()`, `ctx.env`, `ctx.params`, etc. */
   context: HandlerContext<TParams, TEnv>;
-  // Segment metadata (which segment is being evaluated):
+
+  // ── Segment metadata (which segment is being evaluated) ──────────────
+
+  /** The type of segment being revalidated. */
   segmentType: "layout" | "route" | "parallel";
-  layoutName?: string; // Layout name (e.g., "root", "shop", "auth") - only for layouts
-  slotName?: string; // Slot name (e.g., "@sidebar", "@modal") - only for parallels
-  // Action context (populated when revalidation triggered by server action):
-  actionId?: string; // Action identifier (e.g., "src/actions.ts#addToCart")
-  actionUrl?: URL; // URL where action was executed
-  actionResult?: any; // Return value from action execution
-  formData?: FormData; // FormData from action request
-  method?: string; // Request method: 'GET' for navigation, 'POST' for actions
-  routeName?: DefaultRouteName; // Route name of the navigation target (alias for toRouteName)
-  // Named-route identity for both ends of a navigation transition.
-  // Undefined for unnamed internal routes (those without a `name` option).
-  fromRouteName?: DefaultRouteName; // Route name being navigated away from
-  toRouteName?: DefaultRouteName; // Route name being navigated to
-  // Stale cache revalidation (SWR pattern):
-  stale?: boolean; // True if this is a stale cache revalidation request
+  /** Layout name (e.g., `"root"`, `"shop"`, `"auth"`). Only set for layout segments. */
+  layoutName?: string;
+  /** Slot name (e.g., `"@sidebar"`, `"@modal"`). Only set for parallel segments. */
+  slotName?: string;
+
+  // ── Action context (populated when revalidation is triggered by a server action) ──
+
+  /**
+   * Identifier of the server action that triggered revalidation.
+   * `undefined` during normal navigation (no action involved).
+   *
+   * Format: `"src/<path>#<exportName>"` — the file path is the source path
+   * relative to the project root, followed by `#` and the exported function name.
+   *
+   * This is stable and can be used for path-based matching to revalidate
+   * when any action in a module or directory fires:
+   *
+   * @example
+   * ```ts
+   * // Match a specific action
+   * revalidate(({ actionId }) => actionId === "src/actions/cart.ts#addToCart")
+   *
+   * // Match any action in the cart module
+   * revalidate(({ actionId }) => actionId?.includes("cart") ?? false)
+   *
+   * // Match any action under src/apps/store/actions/
+   * revalidate(({ actionId }) => actionId?.startsWith("src/apps/store/actions/") ?? false)
+   * ```
+   */
+  actionId?: string;
+  /** URL where the action was executed (the page the user was on when they triggered the action). */
+  actionUrl?: URL;
+  /** Return value from the action execution. Can be used to conditionally revalidate based on the action's outcome. */
+  actionResult?: any;
+  /** FormData from the action request body. Only set for form-based actions (not inline `"use server"` actions). */
+  formData?: FormData;
+  /** HTTP method: `"GET"` for navigation, `"POST"` for server actions. */
+  method?: string;
+
+  // ── Route identity ───────────────────────────────────────────────────
+
+  /** Route name of the navigation target. Alias for `toRouteName`. */
+  routeName?: DefaultRouteName;
+  /**
+   * Route name being navigated away from.
+   * `undefined` for unnamed internal routes (those without a `name` option).
+   */
+  fromRouteName?: DefaultRouteName;
+  /**
+   * Route name being navigated to.
+   * `undefined` for unnamed internal routes (those without a `name` option).
+   */
+  toRouteName?: DefaultRouteName;
+
+  // ── Staleness signal ─────────────────────────────────────────────────
+
+  /**
+   * `true` when the browser signals that data may be stale — typically because
+   * a server action was executed in this or another tab (`_rsc_stale` header).
+   *
+   * This is NOT segment cache staleness (loaders are never segment-cached).
+   * Use this to decide whether loader data should be re-fetched after an
+   * action that may have mutated backend state.
+   */
+  stale?: boolean;
 }) => boolean | { defaultShouldRevalidate: boolean };
 
 // MiddlewareFn is imported from "../router/middleware.js" and re-exported