@rangojs/router 0.0.0-experimental.bd6e11bc → 0.0.0-experimental.bdaf10aa

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[]> {
@@ -159,8 +156,6 @@ function deduplicateLoaderSegments(
     }
   }
 
-  // An inherited loader is needed when it shares a namespace with a
-  // loading-bearing segment (its data sits behind that LoaderBoundary).
   const loadersWithLoading = new Set<string>();
   for (const ns of namespacesWithLoading) {
     for (const id of loaderIdsByNamespace.get(ns) ?? []) {
@@ -195,9 +190,6 @@ function deduplicateLoaderSegments(
   return { segments: result, removedIds };
 }
 
-/**
- * Build the final MatchResult from collected segments and context
- */
 export function buildMatchResult<TEnv>(
   allSegments: ResolvedSegment[],
   ctx: MatchContext<TEnv>,
@@ -209,46 +201,47 @@ export function buildMatchResult<TEnv>(
 
   let allIds: string[];
   let segmentsToRender: ResolvedSegment[];
+  let resolvedIds: string[];
 
   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.
+    // One pass over allSegments: dedup by id (segmentsToRender + allIds) while
+    // collecting every id for resolvedIds, which keeps duplicates unlike allIds.
     const seen = new Set<string>();
     segmentsToRender = [];
+    allIds = [];
+    resolvedIds = [];
     for (const s of allSegments) {
+      resolvedIds.push(s.id);
       if (!seen.has(s.id)) {
         seen.add(s.id);
         segmentsToRender.push(s);
+        allIds.push(s.id);
       }
     }
-    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.
+    // One pass over allSegments: keep renderable segments and collect the
+    // handler-ran ids (resolvedIds) together.
     const clientIdSet = new Set(ctx.clientSegmentIds);
-    segmentsToRender = allSegments.filter(
-      (s) =>
-        s.component !== null || s.type === "loader" || !clientIdSet.has(s.id),
-    );
+    segmentsToRender = [];
+    resolvedIds = [];
+    for (const s of allSegments) {
+      if (s._handlerRan) resolvedIds.push(s.id);
+      if (
+        s.component !== null ||
+        s.type === "loader" ||
+        !clientIdSet.has(s.id)
+      ) {
+        segmentsToRender.push(s);
+      }
+    }
   }
 
   const { segments: dedupedSegments, removedIds } = deduplicateLoaderSegments(
@@ -256,44 +249,27 @@ export function buildMatchResult<TEnv>(
     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 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;
-  });
+  // One pass over dedupedSegments: strip the internal _handlerRan marker and
+  // collect the diff ids (id is unchanged by the strip) together.
+  const cleanedSegments: ResolvedSegment[] = [];
+  const diff: string[] = [];
+  for (const s of dedupedSegments) {
+    if (s._handlerRan === undefined) {
+      cleanedSegments.push(s);
+    } else {
+      const { _handlerRan: _drop, ...rest } = s;
+      cleanedSegments.push(rest as ResolvedSegment);
+    }
+    diff.push(s.id);
+  }
 
   return {
     segments: cleanedSegments,
     matched: matchedIds,
-    diff: cleanedSegments.map((s) => s.id),
+    diff,
     resolvedIds,
     params: ctx.matched.params,
     routeName: ctx.routeKey,
@@ -303,12 +279,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>,
@@ -318,7 +288,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;
   }

package/src/router/metrics.ts

@@ -1,9 +1,3 @@
-/**
- * Router Metrics Utilities
- *
- * Performance metrics collection and reporting for Rango.
- */
-
 import type { MetricsStore, PerformanceMetric } from "../server/context";
 
 const BASE_INDENT = 2;
@@ -16,7 +10,6 @@ function formatMs(value: number): string {
 
 function sortMetrics(metrics: PerformanceMetric[]): PerformanceMetric[] {
   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;
@@ -68,11 +61,6 @@ function createTimelineAxis(total: number): string {
   )}${totalLabel}`;
 }
 
-/**
- * Create a metrics store for the request if debugPerformance is enabled.
- * An optional `requestStart` timestamp can anchor the store to an earlier
- * point (e.g. handler start) so that handler:total has startTime=0.
- */
 export function createMetricsStore(
   debugPerformance: boolean,
   requestStart?: number,
@@ -85,9 +73,6 @@ export function createMetricsStore(
   };
 }
 
-/**
- * Append a metric to the request store using an absolute start timestamp.
- */
 export function appendMetric(
   metricsStore: MetricsStore | undefined,
   label: string,
@@ -104,9 +89,6 @@ export function appendMetric(
   });
 }
 
-/**
- * Log the current request metrics and return the corresponding Server-Timing value.
- */
 export function buildMetricsTiming(
   method: string,
   pathname: string,
@@ -117,7 +99,6 @@ export function buildMetricsTiming(
   return generateServerTiming(metricsStore) || undefined;
 }
 
-/** Display row produced by merging :pre/:post metric pairs. */
 interface DisplayRow {
   label: string;
   startTime: number;
@@ -126,12 +107,7 @@ interface DisplayRow {
   spans: Span[];
 }
 
-/**
- * Build display rows from sorted metrics, merging :pre/:post pairs into
- * a single row with disjoint timeline segments.
- */
 function buildDisplayRows(sorted: PerformanceMetric[]): DisplayRow[] {
-  // Index :pre and :post metrics by their base label
   const preMap = new Map<string, PerformanceMetric>();
   const postMap = new Map<string, PerformanceMetric>();
   const consumed = new Set<PerformanceMetric>();
@@ -211,11 +187,6 @@ function buildDisplayRows(sorted: PerformanceMetric[]): DisplayRow[] {
   return rows;
 }
 
-/**
- * Log metrics to console in a formatted way.
- * Uses a shared-axis timeline so overlapping work stays visible.
- * Merges :pre/:post pairs onto one row with disjoint timeline segments.
- */
 export function logMetrics(
   method: string,
   pathname: string,
@@ -267,11 +238,6 @@ export function logMetrics(
   }
 }
 
-/**
- * Generate Server-Timing header value from metrics
- * Format: metric-name;dur=X.XX
- * Depth is encoded as a "d{N}-" prefix for nested metrics.
- */
 export function generateServerTiming(metricsStore: MetricsStore): string {
   return metricsStore.metrics
     .map((m) => {