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

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
@@ -94,6 +96,7 @@ import type { MatchContext, MatchPipelineState } from "../match-context.js";
 import { getRouterContext } from "../router-context.js";
 import { resolveSink, safeEmit } from "../telemetry.js";
 import { pushRevalidationTraceEntry, isTraceActive } from "../logging.js";
+import { treeHasStreaming } from "./segment-resolution.js";
 import type { PrerenderStore, PrerenderEntry } from "../../prerender/store.js";
 import type { HandleStore } from "../../server/handle-store.js";
 import {
@@ -191,6 +194,16 @@ async function* yieldFromStore<TEnv>(
   state.cachedSegments = segments;
   state.cachedMatchedIds = segments.map((s) => s.id);
 
+  // Set streaming flag (once) and resolve render barrier.
+  const reqCtx = handleStoreRef ? undefined : _lazyGetRequestContext?.();
+  const barrierReqCtx = reqCtx ?? _getRequestContext();
+  if (barrierReqCtx) {
+    if (barrierReqCtx._treeHasStreaming === undefined) {
+      barrierReqCtx._treeHasStreaming = treeHasStreaming(ctx.entries);
+    }
+    barrierReqCtx._resolveRenderBarrier(segments);
+  }
+
   // For partial navigation, nullify components the client already has
   // so parent layouts stay live (client keeps its existing versions).
   // When params changed (e.g., different guide slug), the segments have
@@ -238,6 +251,7 @@ async function* yieldFromStore<TEnv>(
           ctx.url,
           ctx.routeKey,
           ctx.actionContext,
+          ctx.stale || undefined,
         ),
       );
       state.matchedIds = [
@@ -261,7 +275,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,
     });
@@ -314,14 +328,15 @@ 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);
         const isPassthroughPrerenderRoute = ctx.entries.some(
-          (entry) =>
-            entry.type === "route" &&
-            entry.prerenderDef?.options?.passthrough === true,
+          (entry) => entry.type === "route" && entry.isPassthrough === true,
         );
 
         if (ctx.isIntercept) {
@@ -391,9 +406,7 @@ export function withCacheLookup<TEnv>(
         if (prerenderStoreInstance) {
           const paramHash = _hashParams!(ctx.matched.params);
           const isPassthroughPrerenderRoute = ctx.entries.some(
-            (entry) =>
-              entry.type === "route" &&
-              entry.prerenderDef?.options?.passthrough === true,
+            (entry) => entry.type === "route" && entry.isPassthrough === true,
           );
 
           if (ctx.isIntercept) {
@@ -446,7 +459,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 +479,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 +531,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({
@@ -552,7 +599,7 @@ export function withCacheLookup<TEnv>(
         routeKey: ctx.routeKey,
         context: ctx.handlerContext,
         actionContext: ctx.actionContext,
-        stale: cacheResult.shouldRevalidate || undefined,
+        stale: cacheResult.shouldRevalidate || ctx.stale || undefined,
         traceSource: "cache-hit",
       });
 
@@ -579,6 +626,15 @@ export function withCacheLookup<TEnv>(
       yield segment;
     }
 
+    // Set streaming flag (once) and resolve render barrier.
+    const barrierReqCtx = _getRequestContext();
+    if (barrierReqCtx) {
+      if (barrierReqCtx._treeHasStreaming === undefined) {
+        barrierReqCtx._treeHasStreaming = treeHasStreaming(ctx.entries);
+      }
+      barrierReqCtx._resolveRenderBarrier(cacheResult.segments);
+    }
+
     // Resolve loaders fresh (loaders are NOT cached by default)
     // This ensures fresh data even on cache hit
     const Store = ctx.Store;
@@ -615,7 +671,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 +702,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-middleware/segment-resolution.ts

@@ -87,10 +87,49 @@
  *   if (state.cacheHit) return;   // Now we can check
  */
 import type { ResolvedSegment } from "../../types.js";
+import type { EntryData } from "../../server/context.js";
+import { _getRequestContext } from "../../server/request-context.js";
 import type { MatchContext, MatchPipelineState } from "../match-context.js";
 import { getRouterContext } from "../router-context.js";
 import type { GeneratorMiddleware } from "./cache-lookup.js";
 
+/**
+ * Check whether any entry in the tree uses loading() (streaming).
+ * Matches the router's streaming semantics in fresh.ts: streaming is
+ * enabled when `loading` is defined AND not `false`. `loading: false`
+ * explicitly disables streaming; `undefined` means no loading at all.
+ */
+export function treeHasStreaming(entries: EntryData[]): boolean {
+  for (const entry of entries) {
+    if (
+      "loading" in entry &&
+      entry.loading !== undefined &&
+      entry.loading !== false
+    )
+      return true;
+    if (entry.layout) {
+      if (treeHasStreaming(entry.layout)) return true;
+    }
+    if (entry.parallel) {
+      for (const key in entry.parallel) {
+        const parallelEntry = entry.parallel[key as `@${string}`];
+        if (parallelEntry) {
+          if (
+            "loading" in parallelEntry &&
+            parallelEntry.loading !== undefined &&
+            parallelEntry.loading !== false
+          )
+            return true;
+          if (parallelEntry.layout) {
+            if (treeHasStreaming(parallelEntry.layout)) return true;
+          }
+        }
+      }
+    }
+  }
+  return false;
+}
+
 /**
  * Creates segment resolution middleware
  *
@@ -116,6 +155,7 @@ export function withSegmentResolution<TEnv>(
     const ownStart = performance.now();
 
     // If cache hit, segments were already yielded by cache lookup
+    // (render barrier is resolved on the cache-hit path)
     if (state.cacheHit) {
       if (ms) {
         ms.metrics.push({
@@ -127,6 +167,11 @@ export function withSegmentResolution<TEnv>(
       return;
     }
 
+    const reqCtx = _getRequestContext();
+    if (reqCtx && reqCtx._treeHasStreaming === undefined) {
+      reqCtx._treeHasStreaming = treeHasStreaming(ctx.entries);
+    }
+
     const { resolveAllSegmentsWithRevalidation, resolveAllSegments } =
       getRouterContext<TEnv>();
 
@@ -148,6 +193,10 @@ export function withSegmentResolution<TEnv>(
       state.segments = segments;
       state.matchedIds = segments.map((s: { id: string }) => s.id);
 
+      if (reqCtx) {
+        reqCtx._resolveRenderBarrier(segments);
+      }
+
       // Yield all resolved segments
       for (const segment of segments) {
         yield segment;
@@ -178,6 +227,10 @@ export function withSegmentResolution<TEnv>(
       state.segments = result.segments;
       state.matchedIds = result.matchedIds;
 
+      if (reqCtx) {
+        reqCtx._resolveRenderBarrier(result.segments);
+      }
+
       // Yield all resolved segments
       for (const segment of result.segments) {
         yield segment;

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
@@ -124,6 +125,69 @@ export async function collectSegments(
   return segments;
 }
 
+/**
+ * Deduplicate inherited loader segments by loaderId.
+ *
+ * When a route has loaders and a child layout has parallel slots, the same
+ * loader is resolved twice: once for the route and once inherited into the
+ * layout (tagged with `_inherited`). The inherited copy is only needed when
+ * the route uses `loading()` — in that case, the loader data is inside a
+ * LoaderBoundary/Suspense that parallel slots can't reach through. Without
+ * loading(), useLoader() traverses parent contexts and finds the data.
+ */
+function deduplicateLoaderSegments(
+  segments: ResolvedSegment[],
+  logPrefix: string,
+): ResolvedSegment[] {
+  // First pass: collect loaderIds of original (non-inherited) segments
+  // and whether their parent entry uses loading()
+  const originalLoaders = new Set<string>();
+  const loadersWithLoading = new Set<string>();
+  for (const s of segments) {
+    if (s.type === "loader" && s.loaderId && !s._inherited) {
+      originalLoaders.add(s.loaderId);
+      // If the segment has a sibling with loading, the parent uses loading()
+      // We detect this by checking if any non-loader segment in the same
+      // namespace has loading defined
+    }
+  }
+  // Check if any layout/route segment has loading — if a loader's namespace
+  // matches a segment with loading, the inherited copy is needed
+  for (const s of segments) {
+    if (s.type !== "loader" && s.loading !== undefined && s.loading !== false) {
+      // Find loaders in this namespace
+      for (const l of segments) {
+        if (l.type === "loader" && l.namespace === s.namespace && l.loaderId) {
+          loadersWithLoading.add(l.loaderId);
+        }
+      }
+    }
+  }
+
+  const result: ResolvedSegment[] = [];
+  let dedupCount = 0;
+
+  for (const s of segments) {
+    if (
+      s.type === "loader" &&
+      s.loaderId &&
+      s._inherited &&
+      originalLoaders.has(s.loaderId) &&
+      !loadersWithLoading.has(s.loaderId)
+    ) {
+      dedupCount++;
+      continue;
+    }
+    result.push(s);
+  }
+
+  if (dedupCount > 0) {
+    debugLog(logPrefix, `deduped ${dedupCount} inherited loader segment(s)`);
+  }
+
+  return result;
+}
+
 /**
  * Build the final MatchResult from collected segments and context
  */
@@ -168,13 +232,23 @@ 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),
     );
   }
 
+  const dedupedSegments = deduplicateLoaderSegments(
+    segmentsToRender,
+    logPrefix,
+  );
+
   debugLog(logPrefix, "all segments", {
     segments: allSegments.map((s) => ({
       id: s.id,
@@ -183,13 +257,42 @@ export function buildMatchResult<TEnv>(
     })),
   });
   debugLog(logPrefix, "segments to render", {
-    segmentIds: segmentsToRender.map((s) => s.id),
+    segmentIds: dedupedSegments.map((s) => s.id),
+  });
+
+  // Remove deduped loader IDs from matched so the client doesn't treat
+  // them as missing segments and trigger a fallback refetch.
+  const removedIds = new Set(
+    segmentsToRender
+      .filter((s) => !dedupedSegments.includes(s))
+      .map((s) => s.id),
+  );
+  const matchedIds =
+    removedIds.size > 0 ? allIds.filter((id) => !removedIds.has(id)) : allIds;
+
+  // resolvedIds: every segment whose handler actually ran this request.
+  // For full-match every segment is fresh; for partial-match we filter by
+  // the internal `_handlerRan` flag set in revalidation.ts. Drives the
+  // client's handle-bucket cleanup — a slot that re-resolved and pushed
+  // nothing must have its previous handle data cleared, but `diff` won't
+  // carry it because the segment payload skips null-component cached
+  // segments to save bytes.
+  const resolvedIds = ctx.isFullMatch
+    ? allSegments.map((s) => s.id)
+    : allSegments.filter((s) => s._handlerRan).map((s) => s.id);
+
+  // Strip internal-only fields from the segments going on the wire.
+  const cleanedSegments = dedupedSegments.map((s) => {
+    if (s._handlerRan === undefined) return s;
+    const { _handlerRan: _drop, ...rest } = s;
+    return rest as ResolvedSegment;
   });
 
   return {
-    segments: segmentsToRender,
-    matched: allIds,
-    diff: segmentsToRender.map((s) => s.id),
+    segments: cleanedSegments,
+    matched: matchedIds,
+    diff: cleanedSegments.map((s) => s.id),
+    resolvedIds,
     params: ctx.matched.params,
     routeName: ctx.routeKey,
     slots: Object.keys(state.slots).length > 0 ? state.slots : undefined,

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/middleware-types.ts

@@ -14,6 +14,7 @@ import type {
 import type { ScopedReverseFunction } from "../reverse.js";
 import type { Theme } from "../theme/types.js";
 import type { LocationStateEntry } from "../browser/react/location-state-shared.js";
+import type { RequestScope } from "../types/request-scope.js";
 
 /**
  * Get variable function type
@@ -27,8 +28,12 @@ type GetVariableFn = {
  * Set variable function type
  */
 type SetVariableFn = {
-  <T>(contextVar: ContextVar<T>, value: T): void;
-  <K extends keyof DefaultVars>(key: K, value: DefaultVars[K]): void;
+  <T>(contextVar: ContextVar<T>, value: T, options?: { cache?: boolean }): void;
+  <K extends keyof DefaultVars>(
+    key: K,
+    value: DefaultVars[K],
+    options?: { cache?: boolean },
+  ): void;
 };
 
 /**
@@ -48,33 +53,15 @@ export interface CookieOptions {
  * Context passed to middleware
  *
  * @template TEnv - Environment type (bindings, variables) - defaults to any for internal flexibility
- * @template TParams - URL params type (typed for route middleware, Record<string, string> for global middleware)
+ * @template TParams - URL params type (typed for route middleware,
+ *   `Record<string, string | undefined>` for global middleware — absent
+ *   optional segments are omitted from the params record at runtime, so
+ *   the index signature must include `undefined`)
  */
 export interface MiddlewareContext<
   TEnv = any,
-  TParams = Record<string, string>,
-> {
-  /** Original request */
-  request: Request;
-
-  /** Parsed URL (with internal `_rsc*` params stripped) */
-  url: URL;
-
-  /**
-   * The original request URL with all parameters intact, including
-   * internal `_rsc*` transport params.
-   */
-  originalUrl: URL;
-
-  /** URL pathname */
-  pathname: string;
-
-  /** URL search params */
-  searchParams: URLSearchParams;
-
-  /** Platform bindings (Cloudflare, etc.) */
-  env: TEnv;
-
+  TParams = Record<string, string | undefined>,
+> extends RequestScope<TEnv> {
   /** URL params extracted from route/middleware pattern */
   params: TParams;
 
@@ -91,12 +78,6 @@ export interface MiddlewareContext<
   /** Set a context variable (shared with route handlers) */
   set: SetVariableFn;
 
-  /**
-   * Middleware-injected variables.
-   * Same shared dictionary as `ctx.get()`/`ctx.set()`.
-   */
-  var: DefaultVars;
-
   /**
    * Set a response header - can be called before or after `next()`.
    *
@@ -171,7 +152,10 @@ export interface MiddlewareContext<
  * router.use((ctx, next) => {...}) // ctx is typed from router's TEnv
  * ```
  */
-export type MiddlewareFn<TEnv = any, TParams = Record<string, string>> = (
+export type MiddlewareFn<
+  TEnv = any,
+  TParams = Record<string, string | undefined>,
+> = (
   ctx: MiddlewareContext<TEnv, TParams>,
   next: () => Promise<Response>,
 ) => Response | void | Promise<Response | void>;
@@ -218,5 +202,8 @@ export interface MiddlewareCollectableEntry {
  */
 export interface CollectedMiddleware {
   handler: MiddlewareFn<any, any>;
+  // Internal shape only. The user-facing `MiddlewareContext.params` is
+  // typed `Record<string, string | undefined>` to reflect that absent
+  // optional segments are omitted from the params record at runtime.
   params: Record<string, string>;
 }