@rangojs/router 0.0.0-experimental.dfdb0387 → 0.0.0-experimental.e9c0b2f2

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

@@ -123,21 +123,14 @@ export function withCacheStore<TEnv>(
   ): AsyncGenerator<ResolvedSegment> {
     const ms = ctx.metricsStore;
 
-    // Collect all segments while passing them through
     const allSegments: ResolvedSegment[] = [];
     for await (const segment of source) {
       allSegments.push(segment);
       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)
-    // 3. Cache was already hit (no need to re-cache)
-    // 4. Non-GET request (only cache GET requests)
     if (
       !ctx.cacheScope?.enabled ||
       ctx.isAction ||
@@ -162,31 +155,45 @@ export function withCacheStore<TEnv>(
       createHandleStore,
     } = getRouterContext<TEnv>();
 
-    // Combine main segments with intercept segments
-    const allSegmentsToCache = [...allSegments, ...state.interceptSegments];
+    // On a fresh intercept miss the intercept slot segments flow through
+    // `source` into allSegments AND are also recorded on state.interceptSegments.
+    // Dedup by id so each segment is cached once — cacheRoute serializes the
+    // array verbatim (no id-dedup), so an un-deduped append doubles the intercept
+    // segment in the cached entry, re-rendering the slot twice on the next hit.
+    const seenSegmentIds = new Set(allSegments.map((s) => s.id));
+    const allSegmentsToCache = [
+      ...allSegments,
+      ...state.interceptSegments.filter((s) => !seenSegmentIds.has(s.id)),
+    ];
 
-    // 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" && clientIdSet.has(s.id),
+        s.component === null &&
+        s.type !== "loader" &&
+        ctx.clientSegmentSet.has(s.id),
     );
 
     const requestCtx = getRequestContext();
     if (!requestCtx) return;
 
     const cacheScope = ctx.cacheScope;
+
+    // Record the route's segment-DSL cache tags into the request tag union NOW,
+    // synchronously in the pipeline. The actual store write (cacheRoute) runs in
+    // requestCtx.waitUntil() below — and the proactive path re-resolves the whole
+    // tree first — so cacheRoute's own tag recording races the document cache's
+    // post-body-drain snapshot of _requestTags. On a first-write miss the document
+    // tag union could miss these tags and revalidateTag()/updateTag() would not
+    // invalidate the cached document. Recording here (before the snapshot) closes
+    // the window for both the direct and proactive write paths; the duplicate
+    // record inside cacheRoute is idempotent.
+    cacheScope.recordTags(requestCtx);
+
     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) {
         debugLog("cacheStore", "skipping cache for non-200 response", {
           status: response.status,
@@ -196,10 +203,7 @@ export function withCacheStore<TEnv>(
       }
 
       if (hasNullComponents) {
-        // 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;
 
@@ -207,15 +211,9 @@ export function withCacheStore<TEnv>(
           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
             const proactiveHandlerContext = createHandlerContext(
               ctx.matched.params,
               ctx.request,
@@ -230,12 +228,8 @@ export function withCacheStore<TEnv>(
             );
             const proactiveLoaderPromises = new Map<string, Promise<any>>();
 
-            // Use normal loader access so handle data is captured
             setupLoaderAccess(proactiveHandlerContext, proactiveLoaderPromises);
 
-            // 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(
@@ -248,7 +242,6 @@ export function withCacheStore<TEnv>(
               ),
             );
 
-            // Also resolve intercept segments fresh if applicable
             let freshInterceptSegments: ResolvedSegment[] = [];
             if (ctx.interceptResult) {
               freshInterceptSegments = await Store.run(() =>
@@ -259,6 +252,12 @@ export function withCacheStore<TEnv>(
                   proactiveHandlerContext,
                   true, // belongsToRoute
                   // No revalidationContext = render fresh
+                  undefined,
+                  // Skip intercept middleware: the foreground already ran it
+                  // before the response was sent. Re-running here (post-response,
+                  // background) would fire side effects twice and a short-circuit
+                  // Response would silently abort this cache write.
+                  { skipMiddleware: true },
                 ),
               );
             }
@@ -300,8 +299,6 @@ export function withCacheStore<TEnv>(
           }
         });
       } 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})`,

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

@@ -125,17 +125,14 @@ export function withInterceptResolution<TEnv>(
   ): 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) {
       segments.push(segment);
       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({
@@ -147,18 +144,12 @@ export function withInterceptResolution<TEnv>(
       return;
     }
 
-    // Skip intercept resolution if:
-    // 1. No intercept result
-    // 2. Already have intercept segments (from cache hit with intercept key)
-    // 3. Cache hit with intercept key
     const skipInterceptResolution =
       !ctx.interceptResult ||
       state.interceptSegments.length > 0 ||
       (state.cacheHit && ctx.isIntercept);
 
     if (skipInterceptResolution) {
-      // For cache hit with intercept, extract intercept segments from cached data for slots
-      // and re-resolve loaders for fresh data
       if (ctx.interceptResult && state.cacheHit && ctx.isIntercept) {
         await handleCacheHitIntercept(ctx, state, segments);
       }
@@ -172,7 +163,6 @@ export function withInterceptResolution<TEnv>(
       return;
     }
 
-    // Resolve intercept segments
     const { resolveInterceptEntry } = getRouterContext<TEnv>();
 
     const slotName = ctx.interceptResult!.intercept.slotName;
@@ -181,7 +171,6 @@ export function withInterceptResolution<TEnv>(
       slotName,
     });
 
-    // Resolve intercept entry (middleware, loaders, handler)
     const Store = ctx.Store;
     const interceptSegments = await Store.run(() =>
       resolveInterceptEntry(
@@ -203,14 +192,12 @@ export function withInterceptResolution<TEnv>(
       ),
     );
 
-    // Update state
     state.interceptSegments = interceptSegments;
     state.slots[slotName] = {
       active: true,
       segments: interceptSegments,
     };
 
-    // Yield intercept segments
     for (const segment of interceptSegments) {
       yield segment;
     }
@@ -225,11 +212,6 @@ export function withInterceptResolution<TEnv>(
   };
 }
 
-/**
- * Handle cache hit with intercept scenario
- *
- * Extract intercept segments from cached data and re-resolve loaders for fresh data.
- */
 async function handleCacheHitIntercept<TEnv>(
   ctx: MatchContext<TEnv>,
   state: MatchPipelineState,
@@ -241,14 +223,11 @@ async function handleCacheHitIntercept<TEnv>(
 
   const slotName = ctx.interceptResult.intercept.slotName;
 
-  // Find intercept segments from cached segments (namespace starts with "intercept:")
   const interceptSegments = segments.filter((s) =>
     s.namespace?.startsWith("intercept:"),
   );
   state.interceptSegments = interceptSegments;
 
-  // Re-resolve intercept loaders for fresh data on cache hit
-  // This keeps cached component/layout but fetches fresh loader data
   if (resolveInterceptLoadersOnly) {
     const Store = ctx.Store;
     const freshLoaderResult = await Store.run(() =>
@@ -271,7 +250,6 @@ async function handleCacheHitIntercept<TEnv>(
       ),
     );
 
-    // Update intercept segment's loaderDataPromise with fresh data
     if (freshLoaderResult) {
       const interceptMainSegment = interceptSegments.find(
         (s) => s.type === "parallel" && s.slot,

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

@@ -93,12 +93,6 @@ 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 (
@@ -130,12 +124,6 @@ export function treeHasStreaming(entries: EntryData[]): boolean {
   return false;
 }
 
-/**
- * Creates segment resolution middleware
- *
- * Only runs on cache miss (state.cacheHit === false).
- * Uses resolveAllSegmentsWithRevalidation from RouterContext to resolve segments.
- */
 export function withSegmentResolution<TEnv>(
   ctx: MatchContext<TEnv>,
   state: MatchPipelineState,
@@ -145,17 +133,12 @@ export function withSegmentResolution<TEnv>(
   ): 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
-    // (render barrier is resolved on the cache-hit path)
     if (state.cacheHit) {
       if (ms) {
         ms.metrics.push({
@@ -178,7 +161,6 @@ export function withSegmentResolution<TEnv>(
     const Store = ctx.Store;
 
     if (ctx.isFullMatch) {
-      // Full match (document request) - simple resolution without revalidation
       const segments = await Store.run(() =>
         resolveAllSegments(
           ctx.entries,
@@ -189,15 +171,12 @@ export function withSegmentResolution<TEnv>(
         ),
       );
 
-      // 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;
       }
@@ -214,7 +193,6 @@ export function withSegmentResolution<TEnv>(
           ctx.request,
           ctx.prevUrl,
           ctx.url,
-          ctx.loaderPromises,
           ctx.actionContext,
           ctx.interceptResult,
           ctx.localRouteName,

package/src/router/match-pipelines.ts

@@ -106,16 +106,6 @@ import {
   withSegmentResolution,
 } from "./match-middleware/index.js";
 
-/**
- * Compose multiple async generator middleware into a single middleware
- *
- * Middleware are applied in reverse order (rightmost runs first, innermost).
- * For the pipeline:
- *   compose(A, B, C)(source)
- *
- * The flow is: source -> C -> B -> A -> output
- * Where C is the innermost (runs first on input) and A is outermost (runs last).
- */
 export function compose<T>(
   ...middleware: GeneratorMiddleware<T>[]
 ): GeneratorMiddleware<T> {
@@ -126,54 +116,23 @@ export function compose<T>(
     return middleware[0];
   }
   return (source) => {
-    // Apply middleware in reverse order (rightmost first)
     return middleware.reduceRight((prev, fn) => fn(prev), source);
   };
 }
 
-/**
- * Create an empty async generator (source for pipeline)
- */
-export async function* empty<T>(): AsyncGenerator<T> {
-  // Yields nothing - used as the initial source for the pipeline
-}
+export async function* empty<T>(): AsyncGenerator<T> {}
 
-/**
- * Create the match partial pipeline
- *
- * Pipeline order (innermost to outermost):
- * 1. cache-lookup    - Check cache first, yield cached segments if hit
- * 2. segment-resolution - Resolve segments if cache miss
- * 3. intercept-resolution - Resolve intercept segments
- * 4. cache-store     - Store segments in cache
- * 5. background-revalidation - Trigger SWR if cache was stale
- *
- * Data flow:
- * - empty() produces no segments
- * - cache-lookup either yields cached segments OR passes through to segment-resolution
- * - segment-resolution resolves fresh segments on cache miss
- * - intercept-resolution adds intercept segments
- * - cache-store observes and caches segments
- * - background-revalidation triggers SWR revalidation if needed
- */
 export function createMatchPartialPipeline<TEnv>(
   ctx: MatchContext<TEnv>,
   state: MatchPipelineState,
 ): AsyncGenerator<ResolvedSegment> {
-  // Build the middleware chain
   const pipeline = compose<ResolvedSegment>(
-    // Outermost - observes segments and triggers background revalidation
     withBackgroundRevalidation(ctx, state),
-    // Observes and stores segments in cache
     withCacheStore(ctx, state),
-    // Adds intercept segments after main segments
     withInterceptResolution(ctx, state),
-    // Resolves segments on cache miss
     withSegmentResolution(ctx, state),
-    // Innermost - checks cache first
     withCacheLookup(ctx, state),
   );
 
-  // Start with empty source - cache lookup or segment resolution will produce segments
   return pipeline(empty());
 }

package/src/router/match-result.ts

@@ -112,9 +112,6 @@ 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
- */
 export async function collectSegments(
   generator: AsyncGenerator<ResolvedSegment>,
 ): Promise<ResolvedSegment[]> {
@@ -138,34 +135,36 @@ export async function collectSegments(
 function deduplicateLoaderSegments(
   segments: ResolvedSegment[],
   logPrefix: string,
-): ResolvedSegment[] {
-  // First pass: collect loaderIds of original (non-inherited) segments
-  // and whether their parent entry uses loading()
+): { segments: ResolvedSegment[]; removedIds: Set<string> } {
+  // Single pass: original (non-inherited) loaderIds, all loaderIds grouped by
+  // namespace, and namespaces of segments that declare loading().
   const originalLoaders = new Set<string>();
-  const loadersWithLoading = new Set<string>();
+  const loaderIdsByNamespace = new Map<string, string[]>();
+  const namespacesWithLoading = 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
+    if (s.type === "loader" && s.loaderId) {
+      if (!s._inherited) originalLoaders.add(s.loaderId);
+      const ids = loaderIdsByNamespace.get(s.namespace);
+      if (ids) ids.push(s.loaderId);
+      else loaderIdsByNamespace.set(s.namespace, [s.loaderId]);
+    } else if (
+      s.type !== "loader" &&
+      s.loading !== undefined &&
+      s.loading !== false
+    ) {
+      namespacesWithLoading.add(s.namespace);
     }
   }
-  // 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 loadersWithLoading = new Set<string>();
+  for (const ns of namespacesWithLoading) {
+    for (const id of loaderIdsByNamespace.get(ns) ?? []) {
+      loadersWithLoading.add(id);
     }
   }
 
   const result: ResolvedSegment[] = [];
-  let dedupCount = 0;
+  const removedIds = new Set<string>();
 
   for (const s of segments) {
     if (
@@ -175,22 +174,22 @@ function deduplicateLoaderSegments(
       originalLoaders.has(s.loaderId) &&
       !loadersWithLoading.has(s.loaderId)
     ) {
-      dedupCount++;
+      removedIds.add(s.id);
       continue;
     }
     result.push(s);
   }
 
-  if (dedupCount > 0) {
-    debugLog(logPrefix, `deduped ${dedupCount} inherited loader segment(s)`);
+  if (removedIds.size > 0) {
+    debugLog(
+      logPrefix,
+      `deduped ${removedIds.size} inherited loader segment(s)`,
+    );
   }
 
-  return result;
+  return { segments: result, removedIds };
 }
 
-/**
- * Build the final MatchResult from collected segments and context
- */
 export function buildMatchResult<TEnv>(
   allSegments: ResolvedSegment[],
   ctx: MatchContext<TEnv>,
@@ -204,11 +203,6 @@ export function buildMatchResult<TEnv>(
   let segmentsToRender: ResolvedSegment[];
 
   if (ctx.isFullMatch) {
-    // Full match (document request) - all segments are rendered
-    // 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) {
@@ -219,24 +213,14 @@ export function buildMatchResult<TEnv>(
     }
     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
-    // This prevents the browser from discarding the current page content
-    // If client sent empty segments (HMR recovery), use segment IDs from allSegments
     allIds = ctx.interceptResult
       ? ctx.clientSegmentIds.length > 0
         ? [...ctx.clientSegmentIds, ...state.interceptSegments.map((s) => s.id)]
-        : allSegments.map((s) => s.id) // Use actual segments, not matchedIds
+        : allSegments.map((s) => s.id)
       : [...state.matchedIds, ...state.interceptSegments.map((s) => s.id)];
 
-    // Deduplicate allIds (defense-in-depth for partial match path)
     allIds = [...new Set(allIds)];
 
-    // 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) =>
@@ -244,36 +228,29 @@ export function buildMatchResult<TEnv>(
     );
   }
 
-  const dedupedSegments = deduplicateLoaderSegments(
+  const { segments: dedupedSegments, removedIds } = deduplicateLoaderSegments(
     segmentsToRender,
     logPrefix,
   );
 
-  debugLog(logPrefix, "all segments", {
-    segments: allSegments.map((s) => ({
-      id: s.id,
-      type: s.type,
-      hasComponent: s.component !== null,
-    })),
-  });
-  debugLog(logPrefix, "segments to render", {
-    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;
 
+  const resolvedIds = ctx.isFullMatch
+    ? allSegments.map((s) => s.id)
+    : allSegments.filter((s) => s._handlerRan).map((s) => s.id);
+
+  const cleanedSegments = dedupedSegments.map((s) => {
+    if (s._handlerRan === undefined) return s;
+    const { _handlerRan: _drop, ...rest } = s;
+    return rest as ResolvedSegment;
+  });
+
   return {
-    segments: dedupedSegments,
+    segments: cleanedSegments,
     matched: matchedIds,
-    diff: dedupedSegments.map((s) => s.id),
+    diff: cleanedSegments.map((s) => s.id),
+    resolvedIds,
     params: ctx.matched.params,
     routeName: ctx.routeKey,
     slots: Object.keys(state.slots).length > 0 ? state.slots : undefined,
@@ -282,12 +259,6 @@ export function buildMatchResult<TEnv>(
   };
 }
 
-/**
- * Collect segments from pipeline and build MatchResult
- *
- * This is the main entry point for building the final result after
- * the pipeline has processed all segments.
- */
 export async function collectMatchResult<TEnv>(
   pipeline: AsyncGenerator<ResolvedSegment>,
   ctx: MatchContext<TEnv>,
@@ -297,7 +268,6 @@ export async function collectMatchResult<TEnv>(
 
   const buildStart = performance.now();
 
-  // Update state with collected segments if not already set
   if (state.segments.length === 0) {
     state.segments = allSegments;
   }