@rangojs/router 0.0.0-experimental.7 → 0.0.0-experimental.788796d8

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,6 +121,8 @@ export function withCacheStore<TEnv>(
   return async function* (
     source: AsyncGenerator<ResolvedSegment>,
   ): AsyncGenerator<ResolvedSegment> {
+    const ms = ctx.metricsStore;
+
     // Collect all segments while passing them through
     const allSegments: ResolvedSegment[] = [];
     for await (const segment of source) {
@@ -126,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)
@@ -137,14 +144,22 @@ export function withCacheStore<TEnv>(
       state.cacheHit ||
       ctx.request.method !== "GET"
     ) {
+      if (ms) {
+        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
@@ -160,15 +175,19 @@ 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)
     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;
       }
 
@@ -176,31 +195,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(
@@ -209,6 +240,7 @@ export function withCacheStore<TEnv>(
                 ctx.matched.params,
                 proactiveHandlerContext,
                 proactiveLoaderPromises,
+                { skipLoaders: true },
               ),
             );
 
@@ -231,36 +263,67 @@ 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)
         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}`,
+            );
+          }
         });
       }
 
       return response;
     });
+
+    if (ms) {
+      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,11 +118,13 @@ 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 ms = ctx.metricsStore;
+
     // First, yield all segments from the source (main segment resolution or cache)
     const segments: ResolvedSegment[] = [];
     for await (const segment of source) {
@@ -129,8 +132,18 @@ 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() - ownStart,
+          startTime: ownStart - ms.requestStart,
+        });
+      }
       return;
     }
 
@@ -149,6 +162,13 @@ export function withInterceptResolution<TEnv>(
       if (ctx.interceptResult && state.cacheHit && ctx.isIntercept) {
         await handleCacheHitIntercept(ctx, state, segments);
       }
+      if (ms) {
+        ms.metrics.push({
+          label: "pipeline:intercept",
+          duration: performance.now() - ownStart,
+          startTime: ownStart - ms.requestStart,
+        });
+      }
       return;
     }
 
@@ -156,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;
@@ -178,8 +199,8 @@ export function withInterceptResolution<TEnv>(
           routeKey: ctx.routeKey,
           actionContext: ctx.actionContext,
           stale: ctx.stale,
-        }
-      )
+        },
+      ),
     );
 
     // Update state
@@ -193,6 +214,14 @@ export function withInterceptResolution<TEnv>(
     for (const segment of interceptSegments) {
       yield segment;
     }
+
+    if (ms) {
+      ms.metrics.push({
+        label: "pipeline:intercept",
+        duration: performance.now() - ownStart,
+        startTime: ownStart - ms.requestStart,
+      });
+    }
   };
 }
 
@@ -204,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;
 
@@ -214,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;
 
@@ -238,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

@@ -99,19 +99,31 @@ 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 ms = ctx.metricsStore;
+
     // IMPORTANT: Always iterate source first to give cache-lookup a chance
     // to run and set state.cacheHit. Without this, cache-lookup never executes!
     for await (const segment of source) {
       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() - ownStart,
+          startTime: ownStart - ms.requestStart,
+        });
+      }
       return;
     }
 
@@ -128,8 +140,8 @@ export function withSegmentResolution<TEnv>(
           ctx.routeKey,
           ctx.matched.params,
           ctx.handlerContext,
-          ctx.loaderPromises
-        )
+          ctx.loaderPromises,
+        ),
       );
 
       // Update state with resolved segments
@@ -157,8 +169,9 @@ export function withSegmentResolution<TEnv>(
           ctx.actionContext,
           ctx.interceptResult,
           ctx.localRouteName,
-          ctx.pathname
-        )
+          ctx.pathname,
+          ctx.stale,
+        ),
       );
 
       // Update state with resolved segments
@@ -170,5 +183,13 @@ export function withSegmentResolution<TEnv>(
         yield segment;
       }
     }
+
+    if (ms) {
+      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());
-}

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
@@ -108,13 +109,14 @@
  */
 import type { MatchResult, ResolvedSegment } from "../types.js";
 import type { MatchContext, MatchPipelineState } from "./match-context.js";
-import { generateServerTiming, logMetrics } from "./metrics.js";
+import { debugLog } from "./logging.js";
+import { appendMetric } from "./metrics.js";
 
 /**
  * Collect all segments from an async generator
  */
 export async function collectSegments(
-  generator: AsyncGenerator<ResolvedSegment>
+  generator: AsyncGenerator<ResolvedSegment>,
 ): Promise<ResolvedSegment[]> {
   const segments: ResolvedSegment[] = [];
   for await (const segment of generator) {
@@ -129,17 +131,30 @@ export async function collectSegments(
 export function buildMatchResult<TEnv>(
   allSegments: ResolvedSegment[],
   ctx: MatchContext<TEnv>,
-  state: MatchPipelineState
+  state: MatchPipelineState,
 ): MatchResult {
-  const logPrefix = ctx.isFullMatch ? "[Router.match]" : "[Router.matchPartial]";
+  const logPrefix = ctx.isFullMatch
+    ? "[Router.match]"
+    : "[Router.matchPartial]";
 
   let allIds: string[];
   let segmentsToRender: ResolvedSegment[];
 
   if (ctx.isFullMatch) {
     // Full match (document request) - all segments are rendered
-    allIds = allSegments.map((s) => s.id);
-    segmentsToRender = allSegments;
+    // Deduplicate by segment ID (defense-in-depth). The primary dedup is in
+    // resolveAllSegments, but this guards against any path that bypasses it.
+    // include() scopes can produce entries that resolve the same shared layout,
+    // and duplicate IDs change the client's React tree depth causing remounts.
+    const seen = new Set<string>();
+    segmentsToRender = [];
+    for (const s of allSegments) {
+      if (!seen.has(s.id)) {
+        seen.add(s.id);
+        segmentsToRender.push(s);
+      }
+    }
+    allIds = segmentsToRender.map((s) => s.id);
   } else {
     // Partial match (navigation) - filter and handle intercepts
     // When intercepting, tell browser to keep its current segments + add modal
@@ -151,32 +166,31 @@ export function buildMatchResult<TEnv>(
         : allSegments.map((s) => s.id) // Use actual segments, not matchedIds
       : [...state.matchedIds, ...state.interceptSegments.map((s) => s.id)];
 
-    // Filter out segments with null components (client already has them)
-    // BUT always include loader segments - they carry data even with null component
-    segmentsToRender = allSegments.filter(
-      (s) => s.component !== null || s.type === "loader"
-    );
-  }
+    // Deduplicate allIds (defense-in-depth for partial match path)
+    allIds = [...new Set(allIds)];
 
-  if (process.env.NODE_ENV === "development") {
-    console.log(
-      `${logPrefix} All segments:`,
-      allSegments
-        .map((s) => `${s.id}(${s.type}, component=${s.component !== null})`)
-        .join(", ")
-    );
-    console.log(
-      `${logPrefix} Segments to render:`,
-      segmentsToRender.map((s) => s.id).join(", ")
+    // 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" || !clientIdSet.has(s.id),
     );
   }
 
-  // Output metrics if enabled
-  let serverTiming: string | undefined;
-  if (ctx.metricsStore) {
-    logMetrics(ctx.request.method, ctx.pathname, ctx.metricsStore);
-    serverTiming = generateServerTiming(ctx.metricsStore);
-  }
+  debugLog(logPrefix, "all segments", {
+    segments: allSegments.map((s) => ({
+      id: s.id,
+      type: s.type,
+      hasComponent: s.component !== null,
+    })),
+  });
+  debugLog(logPrefix, "segments to render", {
+    segmentIds: segmentsToRender.map((s) => s.id),
+  });
 
   return {
     segments: segmentsToRender,
@@ -184,7 +198,6 @@ export function buildMatchResult<TEnv>(
     diff: segmentsToRender.map((s) => s.id),
     params: ctx.matched.params,
     routeName: ctx.routeKey,
-    serverTiming,
     slots: Object.keys(state.slots).length > 0 ? state.slots : undefined,
     routeMiddleware:
       ctx.routeMiddleware.length > 0 ? ctx.routeMiddleware : undefined,
@@ -200,14 +213,23 @@ export function buildMatchResult<TEnv>(
 export async function collectMatchResult<TEnv>(
   pipeline: AsyncGenerator<ResolvedSegment>,
   ctx: MatchContext<TEnv>,
-  state: MatchPipelineState
+  state: MatchPipelineState,
 ): 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;
 }