@rangojs/router 0.0.0-experimental.122 → 0.0.0-experimental.125

package/src/router/match-middleware/background-revalidation.ts

@@ -168,8 +168,6 @@ export function withBackgroundRevalidation<TEnv>(
       requestCtx._handleStore = createHandleStore();
 
       try {
-        // Create fresh handler context and loader promises to avoid
-        // reusing memoized results from the foreground pass
         const freshHandlerContext = createHandlerContext(
           ctx.matched.params,
           ctx.request,
@@ -185,10 +183,6 @@ export function withBackgroundRevalidation<TEnv>(
         const freshLoaderPromises = new Map<string, Promise<any>>();
         setupLoaderAccess(freshHandlerContext, freshLoaderPromises);
 
-        // Resolve all segments fresh (without revalidation logic)
-        // to ensure complete components for caching.
-        // Skip DSL loaders — they are never cached (cacheRoute filters them)
-        // and are always resolved fresh on each request.
         const freshSegments = await ctx.Store.run(() =>
           resolveAllSegments(
             ctx.entries,
@@ -200,7 +194,6 @@ export function withBackgroundRevalidation<TEnv>(
           ),
         );
 
-        // Also resolve intercept segments fresh if applicable
         let freshInterceptSegments: ResolvedSegment[] = [];
         if (ctx.interceptResult) {
           freshInterceptSegments = await ctx.Store.run(() =>

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

@@ -103,6 +103,7 @@ import {
   getRequestContext,
   _getRequestContext,
 } from "../../server/request-context.js";
+import { paramsEqual } from "../params-util.js";
 
 // Lazily initialized prerender store singleton and dynamically imported deps.
 // Dynamic imports prevent pulling in @vitejs/plugin-rsc/rsc virtual module at
@@ -124,22 +125,6 @@ let _lazyGetRequestContext:
   | typeof import("../../server/request-context.js").getRequestContext
   | undefined;
 
-function paramsEqual(
-  a: Record<string, string>,
-  b: Record<string, string>,
-): boolean {
-  if (a === b) return true;
-
-  const keysA = Object.keys(a);
-  if (keysA.length !== Object.keys(b).length) return false;
-
-  for (const key of keysA) {
-    if (a[key] !== b[key]) return false;
-  }
-
-  return true;
-}
-
 async function ensurePrerenderDeps() {
   if (!_deserializeSegments) {
     const [codec, snapshot, paramHash, reqCtx, store] = await Promise.all([
@@ -367,10 +352,6 @@ export function withCacheLookup<TEnv>(
       resolveLoadersOnly,
     } = getRouterContext<TEnv>();
 
-    // Prerender lookup: check build-time cached data before runtime cache.
-    // Prerender data is available regardless of runtime cache configuration.
-    // 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();
@@ -385,14 +366,6 @@ export function withCacheLookup<TEnv>(
       }
     }
 
-    // Dev-mode static handler interception for non-Node.js runtimes.
-    // __PRERENDER_DEV_URL is set by the Vite plugin when the RSC environment
-    // lacks a Node.js module runner (e.g. workerd, Deno workers). In those
-    // runtimes, handlers that depend on Node APIs like node:fs can't run
-    // in-process. We redirect them to the /__rsc_prerender endpoint which
-    // resolves segments in a Node.js temp server, same as prerender routes.
-    // In Node.js dev mode this variable is undefined -- handlers run
-    // in-process where Node APIs work, so no interception is needed.
     if (!ctx.isAction && !ctx.matched.pr && globalThis.__PRERENDER_DEV_URL) {
       const hasStatic = ctx.entries.some(
         (e) =>
@@ -415,9 +388,7 @@ export function withCacheLookup<TEnv>(
       }
     }
 
-    // Skip cache during actions
     if (ctx.isAction || !ctx.cacheScope?.enabled) {
-      // Cache miss - pass through to segment resolution
       yield* source;
       if (ms) {
         ms.metrics.push({
@@ -429,7 +400,6 @@ export function withCacheLookup<TEnv>(
       return;
     }
 
-    // Lookup cache
     const cacheResult = await ctx.cacheScope.lookupRoute(
       ctx.pathname,
       ctx.matched.params,
@@ -437,7 +407,6 @@ export function withCacheLookup<TEnv>(
     );
 
     if (!cacheResult) {
-      // Cache miss - pass through to segment resolution
       yield* source;
       if (ms) {
         ms.metrics.push({
@@ -449,16 +418,12 @@ export function withCacheLookup<TEnv>(
       return;
     }
 
-    // Cache HIT
     state.cacheHit = true;
     state.cacheSource = "runtime";
     state.shouldRevalidate = cacheResult.shouldRevalidate;
     state.cachedSegments = cacheResult.segments;
     state.cachedMatchedIds = cacheResult.segments.map((s) => s.id);
 
-    // Apply revalidation to cached segments.
-    // For full matches or empty client segment sets, this map is unnecessary:
-    // we never run segment-level revalidation and can stream segments directly.
     const canCheckSegmentRevalidation =
       !ctx.isFullMatch &&
       ctx.clientSegmentSet.size > 0 &&
@@ -468,7 +433,6 @@ export function withCacheLookup<TEnv>(
       : undefined;
 
     for (const segment of cacheResult.segments) {
-      // Skip segments client doesn't have - they need their component
       if (!ctx.clientSegmentSet.has(segment.id)) {
         if (isTraceActive()) {
           pushRevalidationTraceEntry({
@@ -485,19 +449,13 @@ export function withCacheLookup<TEnv>(
         continue;
       }
 
-      // Skip intercept segments - they're handled separately
       if (segment.namespace?.startsWith("intercept:")) {
         yield segment;
         continue;
       }
 
-      // 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,
@@ -511,7 +469,6 @@ export function withCacheLookup<TEnv>(
 
       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,
@@ -528,7 +485,6 @@ export function withCacheLookup<TEnv>(
           yield segment;
           continue;
         }
-        // No revalidation rules, use default behavior (skip if client has)
         if (isTraceActive()) {
           pushRevalidationTraceEntry({
             segmentId: segment.id,
@@ -546,7 +502,6 @@ export function withCacheLookup<TEnv>(
         continue;
       }
 
-      // Evaluate revalidation rules
       const shouldRevalidate = await evaluateRevalidation({
         segment,
         prevParams: ctx.prevParams,
@@ -580,7 +535,6 @@ export function withCacheLookup<TEnv>(
       }
 
       if (!shouldRevalidate) {
-        // Client has it, no revalidation needed
         segment.component = null;
         segment.loading = undefined;
       }
@@ -588,7 +542,6 @@ export function withCacheLookup<TEnv>(
       yield segment;
     }
 
-    // Set streaming flag (once) and resolve render barrier.
     const barrierReqCtx = _getRequestContext();
     if (barrierReqCtx) {
       if (barrierReqCtx._treeHasStreaming === undefined) {
@@ -597,22 +550,17 @@ export function withCacheLookup<TEnv>(
       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;
     const loaderStart = performance.now();
 
     if (ctx.isFullMatch) {
-      // Full match (document request) - simple loader resolution without revalidation
       if (resolveLoadersOnly) {
         const loaderSegments = await Store.run(() =>
           resolveLoadersOnly(ctx.entries, ctx.handlerContext),
         );
 
-        // Update state - full match doesn't track matchedIds separately
         state.matchedIds = state.cachedMatchedIds!;
 
-        // Yield fresh loader segments
         for (const segment of loaderSegments) {
           yield segment;
         }
@@ -620,7 +568,6 @@ export function withCacheLookup<TEnv>(
         state.matchedIds = state.cachedMatchedIds!;
       }
     } else {
-      // Partial match (navigation) - loader resolution with revalidation
       if (resolveLoadersOnlyWithRevalidation) {
         const loaderResult = await Store.run(() =>
           resolveLoadersOnlyWithRevalidation(

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,13 +155,8 @@ export function withCacheStore<TEnv>(
       createHandleStore,
     } = getRouterContext<TEnv>();
 
-    // Combine main segments with intercept segments
     const allSegmentsToCache = [...allSegments, ...state.interceptSegments];
 
-    // 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 hasNullComponents = allSegmentsToCache.some(
       (s) =>
         s.component === null &&
@@ -184,10 +172,7 @@ export function withCacheStore<TEnv>(
       ? 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,
@@ -197,10 +182,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;
 
@@ -208,15 +190,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,
@@ -231,12 +207,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(
@@ -249,7 +221,6 @@ export function withCacheStore<TEnv>(
               ),
             );
 
-            // Also resolve intercept segments fresh if applicable
             let freshInterceptSegments: ResolvedSegment[] = [];
             if (ctx.interceptResult) {
               freshInterceptSegments = await Store.run(() =>
@@ -301,8 +272,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;
       }

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>,
@@ -211,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) {
@@ -226,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) =>
@@ -256,34 +233,13 @@ 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;
@@ -303,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>,
@@ -318,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;
   }