@rangojs/router 0.0.0-experimental.9 → 0.0.0-experimental.91

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

@@ -104,6 +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, getOrCreateRequestId } from "../logging.js";
+import { INTERNAL_RANGO_DEBUG } from "../../internal-debug.js";
 import type { GeneratorMiddleware } from "./cache-lookup.js";
 
 /**
@@ -119,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
@@ -129,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)
@@ -141,40 +145,53 @@ export function withCacheStore<TEnv>(
       ctx.request.method !== "GET"
     ) {
       if (ms) {
-        ms.metrics.push({ label: "pipeline:cache-store", duration: performance.now() - pipelineStart, startTime: pipelineStart - ms.requestStart });
+        ms.metrics.push({
+          label: "pipeline:cache-store",
+          duration: performance.now() - ownStart,
+          startTime: ownStart - ms.requestStart,
+        });
       }
       return;
     }
 
     const {
       createHandlerContext,
-      setupLoaderAccessSilent,
+      setupLoaderAccess,
       resolveAllSegments,
       resolveInterceptEntry,
+      createHandleStore,
     } = getRouterContext<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)
     requestCtx.onResponse((response) => {
       // Only cache successful responses
       if (response.status !== 200) {
-        console.log(
-          `[CacheStore] Skipping cache: non-200 status ${response.status} for ${ctx.pathname}`,
-        );
+        debugLog("cacheStore", "skipping cache for non-200 response", {
+          status: response.status,
+          pathname: ctx.pathname,
+        });
         return response;
       }
 
@@ -182,31 +199,43 @@ export function withCacheStore<TEnv>(
         // Proactive caching: render all segments fresh in background
         // This ensures cache has complete components for future requests
         requestCtx.waitUntil(async () => {
-          console.log(
-            `[Router.matchPartial] Proactive caching: ${ctx.pathname} (rendering null-component segments)`,
-          );
+          // 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,
+          });
+          // Swap to a fresh HandleStore so handle.push() calls from
+          // proactive resolution are captured (not silenced). The original
+          // store's stream is already sent by waitUntil time.
+          // cacheRoute reads from requestCtx._handleStore, so this ensures
+          // complete handle data (e.g. breadcrumbs) is cached.
+          const originalHandleStore = requestCtx._handleStore;
+          requestCtx._handleStore = createHandleStore();
           try {
             // Create fresh context for proactive caching
-            // This prevents handle data from polluting the response stream
             const proactiveHandlerContext = createHandlerContext(
               ctx.matched.params,
               ctx.request,
               ctx.url.searchParams,
               ctx.pathname,
               ctx.url,
-              ctx.bindings,
+              ctx.env,
               ctx.routeMap,
-              ctx.matched.routeKey
+              ctx.matched.routeKey,
+              ctx.matched.responseType,
+              ctx.matched.pt === true,
             );
             const proactiveLoaderPromises = new Map<string, Promise<any>>();
 
-            // Set up loader access that ignores handle pushes
-            setupLoaderAccessSilent(
-              proactiveHandlerContext,
-              proactiveLoaderPromises,
-            );
+            // 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(
@@ -215,6 +244,7 @@ export function withCacheStore<TEnv>(
                 ctx.matched.params,
                 proactiveHandlerContext,
                 proactiveLoaderPromises,
+                { skipLoaders: true },
               ),
             );
 
@@ -237,32 +267,60 @@ export function withCacheStore<TEnv>(
               ...freshSegments,
               ...freshInterceptSegments,
             ];
+            requestCtx._handleStore.seal();
             await cacheScope.cacheRoute(
               ctx.pathname,
               ctx.matched.params,
               completeSegments,
               ctx.isIntercept,
             );
-            console.log(
-              `[Router.matchPartial] Proactive caching complete: ${ctx.pathname}`,
-            );
+            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) {
-            console.error(
-              `[Router.matchPartial] Proactive caching failed:`,
-              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}`,
+            );
+          }
         });
       }
 
@@ -270,7 +328,11 @@ export function withCacheStore<TEnv>(
     });
 
     if (ms) {
-      ms.metrics.push({ label: "pipeline:cache-store", duration: performance.now() - pipelineStart, startTime: pipelineStart - ms.requestStart });
+      ms.metrics.push({
+        label: "pipeline:cache-store",
+        duration: performance.now() - ownStart,
+        startTime: ownStart - ms.requestStart,
+      });
     }
   };
 }

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

@@ -105,6 +105,7 @@ 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 } from "../logging.js";
 
 /**
  * Creates intercept resolution middleware
@@ -117,12 +118,11 @@ import type { GeneratorMiddleware } from "./cache-lookup.js";
  */
 export function withInterceptResolution<TEnv>(
   ctx: MatchContext<TEnv>,
-  state: MatchPipelineState
+  state: MatchPipelineState,
 ): GeneratorMiddleware<ResolvedSegment> {
   return async function* (
-    source: AsyncGenerator<ResolvedSegment>
+    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)
@@ -132,10 +132,17 @@ 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 });
+        ms.metrics.push({
+          label: "pipeline:intercept",
+          duration: performance.now() - ownStart,
+          startTime: ownStart - ms.requestStart,
+        });
       }
       return;
     }
@@ -156,7 +163,11 @@ export function withInterceptResolution<TEnv>(
         await handleCacheHitIntercept(ctx, state, segments);
       }
       if (ms) {
-        ms.metrics.push({ label: "pipeline:intercept", duration: performance.now() - pipelineStart, startTime: pipelineStart - ms.requestStart });
+        ms.metrics.push({
+          label: "pipeline:intercept",
+          duration: performance.now() - ownStart,
+          startTime: ownStart - ms.requestStart,
+        });
       }
       return;
     }
@@ -165,9 +176,10 @@ export function withInterceptResolution<TEnv>(
     const { resolveInterceptEntry } = getRouterContext<TEnv>();
 
     const slotName = ctx.interceptResult!.intercept.slotName;
-    console.log(
-      `[Router.matchPartial] Found intercept for "${ctx.localRouteName}" -> slot "${slotName}"`
-    );
+    debugLog("matchPartial.intercept", "intercept resolved", {
+      routeName: ctx.localRouteName,
+      slotName,
+    });
 
     // Resolve intercept entry (middleware, loaders, handler)
     const Store = ctx.Store;
@@ -187,8 +199,8 @@ export function withInterceptResolution<TEnv>(
           routeKey: ctx.routeKey,
           actionContext: ctx.actionContext,
           stale: ctx.stale,
-        }
-      )
+        },
+      ),
     );
 
     // Update state
@@ -204,7 +216,11 @@ export function withInterceptResolution<TEnv>(
     }
 
     if (ms) {
-      ms.metrics.push({ label: "pipeline:intercept", duration: performance.now() - pipelineStart, startTime: pipelineStart - ms.requestStart });
+      ms.metrics.push({
+        label: "pipeline:intercept",
+        duration: performance.now() - ownStart,
+        startTime: ownStart - ms.requestStart,
+      });
     }
   };
 }
@@ -217,7 +233,7 @@ export function withInterceptResolution<TEnv>(
 async function handleCacheHitIntercept<TEnv>(
   ctx: MatchContext<TEnv>,
   state: MatchPipelineState,
-  segments: ResolvedSegment[]
+  segments: ResolvedSegment[],
 ): Promise<void> {
   if (!ctx.interceptResult) return;
 
@@ -227,7 +243,7 @@ async function handleCacheHitIntercept<TEnv>(
 
   // Find intercept segments from cached segments (namespace starts with "intercept:")
   const interceptSegments = segments.filter((s) =>
-    s.namespace?.startsWith("intercept:")
+    s.namespace?.startsWith("intercept:"),
   );
   state.interceptSegments = interceptSegments;
 
@@ -251,25 +267,36 @@ async function handleCacheHitIntercept<TEnv>(
           routeKey: ctx.routeKey,
           actionContext: ctx.actionContext,
           stale: ctx.stale,
-        }
-      )
+        },
+      ),
     );
 
     // Update intercept segment's loaderDataPromise with fresh data
     if (freshLoaderResult) {
       const interceptMainSegment = interceptSegments.find(
-        (s) => s.type === "parallel" && s.slot
+        (s) => s.type === "parallel" && s.slot,
       );
       if (interceptMainSegment) {
-        interceptMainSegment.loaderDataPromise = freshLoaderResult.loaderDataPromise;
+        interceptMainSegment.loaderDataPromise =
+          freshLoaderResult.loaderDataPromise;
         interceptMainSegment.loaderIds = freshLoaderResult.loaderIds;
-        console.log(
-          `[Router.matchPartial] Cache HIT + fresh loaders for intercept "${ctx.localRouteName}" -> slot "${slotName}"`
+        debugLog(
+          "matchPartial.intercept",
+          "cache hit with fresh intercept loaders",
+          {
+            routeName: ctx.localRouteName,
+            slotName,
+          },
         );
       }
     } else {
-      console.log(
-        `[Router.matchPartial] Cache HIT for intercept "${ctx.localRouteName}" -> slot "${slotName}" (no loader revalidation)`
+      debugLog(
+        "matchPartial.intercept",
+        "cache hit without intercept loader revalidation",
+        {
+          routeName: ctx.localRouteName,
+          slotName,
+        },
       );
     }
   }

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
  *
@@ -99,12 +138,11 @@ import type { GeneratorMiddleware } from "./cache-lookup.js";
  */
 export function withSegmentResolution<TEnv>(
   ctx: MatchContext<TEnv>,
-  state: MatchPipelineState
+  state: MatchPipelineState,
 ): GeneratorMiddleware<ResolvedSegment> {
   return async function* (
-    source: AsyncGenerator<ResolvedSegment>
+    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,14 +151,27 @@ 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
+    // (render barrier is resolved on the cache-hit path)
     if (state.cacheHit) {
       if (ms) {
-        ms.metrics.push({ label: "pipeline:segment-resolve", duration: performance.now() - pipelineStart, startTime: pipelineStart - ms.requestStart });
+        ms.metrics.push({
+          label: "pipeline:segment-resolve",
+          duration: performance.now() - ownStart,
+          startTime: ownStart - ms.requestStart,
+        });
       }
       return;
     }
 
+    const reqCtx = _getRequestContext();
+    if (reqCtx && reqCtx._treeHasStreaming === undefined) {
+      reqCtx._treeHasStreaming = treeHasStreaming(ctx.entries);
+    }
+
     const { resolveAllSegmentsWithRevalidation, resolveAllSegments } =
       getRouterContext<TEnv>();
 
@@ -134,14 +185,18 @@ export function withSegmentResolution<TEnv>(
           ctx.routeKey,
           ctx.matched.params,
           ctx.handlerContext,
-          ctx.loaderPromises
-        )
+          ctx.loaderPromises,
+        ),
       );
 
       // Update state with resolved segments
       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;
@@ -163,14 +218,19 @@ export function withSegmentResolution<TEnv>(
           ctx.actionContext,
           ctx.interceptResult,
           ctx.localRouteName,
-          ctx.pathname
-        )
+          ctx.pathname,
+          ctx.stale,
+        ),
       );
 
       // Update state with resolved segments
       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;
@@ -178,7 +238,11 @@ export function withSegmentResolution<TEnv>(
     }
 
     if (ms) {
-      ms.metrics.push({ label: "pipeline:segment-resolve", duration: performance.now() - pipelineStart, startTime: pipelineStart - ms.requestStart });
+      ms.metrics.push({
+        label: "pipeline:segment-resolve",
+        duration: performance.now() - ownStart,
+        startTime: ownStart - ms.requestStart,
+      });
     }
   };
 }

package/src/router/match-pipelines.ts

@@ -86,19 +86,14 @@
  *     -> output: cached segments + fresh loader data
  *
  *
- * TWO PIPELINE VARIANTS
- * =====================
- *
- * 1. createMatchPipeline (Full Match)
- *    - Used for document requests (initial page load)
- *    - No revalidation logic (no previous state to compare)
- *    - Simpler segment resolution
- *
- * 2. createMatchPartialPipeline (Partial Match)
- *    - Used for client-side navigation
- *    - Includes revalidation for SWR
- *    - Compares with previous params/URL
- *    - Supports intercepts (soft navigation modals)
+ * PIPELINE VARIANT
+ * ================
+ *
+ * createMatchPartialPipeline handles both full (document) and partial
+ * (navigation) requests. The middleware steps adapt based on ctx.isFullMatch:
+ * - cache-lookup/store work for both
+ * - background-revalidation is a no-op for full matches (no stale state)
+ * - intercept-resolution is a no-op for full matches (no previous navigation)
  */
 import type { ResolvedSegment } from "../types.js";
 import type { MatchContext, MatchPipelineState } from "./match-context.js";
@@ -163,7 +158,7 @@ export async function* empty<T>(): AsyncGenerator<T> {
  */
 export function createMatchPartialPipeline<TEnv>(
   ctx: MatchContext<TEnv>,
-  state: MatchPipelineState
+  state: MatchPipelineState,
 ): AsyncGenerator<ResolvedSegment> {
   // Build the middleware chain
   const pipeline = compose<ResolvedSegment>(
@@ -176,39 +171,9 @@ export function createMatchPartialPipeline<TEnv>(
     // Resolves segments on cache miss
     withSegmentResolution(ctx, state),
     // Innermost - checks cache first
-    withCacheLookup(ctx, state)
+    withCacheLookup(ctx, state),
   );
 
   // Start with empty source - cache lookup or segment resolution will produce segments
   return pipeline(empty());
 }
-
-/**
- * Create the full match pipeline (simpler, no revalidation)
- *
- * Used for document requests (initial page load) where we don't need
- * revalidation logic since there's no previous state to compare against.
- */
-export function createMatchPipeline<TEnv>(
-  ctx: MatchContext<TEnv>,
-  state: MatchPipelineState
-): AsyncGenerator<ResolvedSegment> {
-  // For full match, we only need:
-  // 1. Cache lookup
-  // 2. Segment resolution (without revalidation)
-  // 3. Intercept resolution
-  // 4. Cache store
-
-  // Note: Full match uses different resolution logic (resolveAllSegments instead of
-  // resolveAllSegmentsWithRevalidation). This will be handled by the segment resolution
-  // middleware checking ctx.isFullMatch or similar flag.
-
-  const pipeline = compose<ResolvedSegment>(
-    withCacheStore(ctx, state),
-    withInterceptResolution(ctx, state),
-    withSegmentResolution(ctx, state),
-    withCacheLookup(ctx, state)
-  );
-
-  return pipeline(empty());
-}