@rangojs/router 0.0.0-experimental.124 → 0.0.0-experimental.126

package/src/router/prerender-match.ts

@@ -5,13 +5,13 @@ import {
   runWithRequestContext,
   type RequestContext,
 } from "../server/request-context.js";
-import { contextGet, contextSet } from "../context-var.js";
+import { contextGet, contextSet, hasContextVars } from "../context-var.js";
 import {
   createPrerenderContext,
   createStaticContext,
   createReverseFunction,
 } from "./handler-context.js";
-import { isPrerenderPassthrough } from "../prerender.js";
+import { detectPrerenderPassthrough } from "../prerender.js";
 import { isRouteRootScoped } from "../route-map-builder.js";
 import { setupBuildUse } from "./loader-resolution.js";
 import { loadManifest } from "./manifest.js";
@@ -82,6 +82,17 @@ export async function matchForPrerender<TEnv = any>(
   // Build RouterContext for loadManifest/traverseBack
   const routerCtx = deps.buildRouterContext();
 
+  // Passthrough sentinel result: an unknown-param Passthrough route falls
+  // through to the live handler at runtime, so no artifact is baked. A fresh
+  // object is returned per call (no site mutates or identity-compares it).
+  const passthroughResult = () => ({
+    segments: [],
+    handles: "",
+    routeName: matched.routeKey,
+    params: matchedParams,
+    passthrough: true as const,
+  });
+
   return runWithRouterContext(routerCtx, async () => {
     // 2. Load the manifest entry tree
     const manifestEntry = await loadManifest(
@@ -145,19 +156,10 @@ export async function matchForPrerender<TEnv = any>(
             );
           });
           if (!isKnown) {
-            return {
-              segments: [],
-              handles: "",
-              routeName: matched.routeKey,
-              params: matchedParams,
-              passthrough: true as const,
-            };
+            return passthroughResult();
           }
           // Preserve vars set by getParams() for the render context
-          if (
-            Object.keys(probeBuildVars).length > 0 ||
-            Object.getOwnPropertySymbols(probeBuildVars).length > 0
-          ) {
+          if (hasContextVars(probeBuildVars)) {
             devProbeBuildVars = probeBuildVars;
           }
         } catch (err: any) {
@@ -165,13 +167,7 @@ export async function matchForPrerender<TEnv = any>(
           // Skip errors are intentional — treat as passthrough.
           // All other errors propagate so dev surfaces them.
           if (err?.name === "Skip") {
-            return {
-              segments: [],
-              handles: "",
-              routeName: matched.routeKey,
-              params: matchedParams,
-              passthrough: true as const,
-            };
+            return passthroughResult();
           }
           throw err;
         }
@@ -264,17 +260,13 @@ export async function matchForPrerender<TEnv = any>(
         { skipLoaders: true },
       );
 
-      // 9. Detect passthrough sentinel: handler returned ctx.passthrough()
-      for (const seg of allSegments) {
-        if (isPrerenderPassthrough(seg.component)) {
-          return {
-            segments: [],
-            handles: "",
-            routeName: matched.routeKey,
-            params: matchedParams,
-            passthrough: true as const,
-          };
-        }
+      // 9. Detect passthrough sentinel: handler returned ctx.passthrough().
+      // When the route declares loading(), the handler result is deferred so the
+      // component is a thenable resolving to the sentinel — detectPrerenderPassthrough
+      // resolves thenables before testing (a sync check would miss it and bake a
+      // corrupt artifact).
+      if (await detectPrerenderPassthrough(allSegments)) {
+        return passthroughResult();
       }
 
       // 10. Filter out any loader segments (belt-and-suspenders)
@@ -319,24 +311,14 @@ export async function matchForPrerender<TEnv = any>(
       }[] = [];
       let current: EntryData | null = manifestEntry;
       while (current) {
-        if (current.intercept && current.intercept.length > 0) {
-          for (const ic of current.intercept) {
+        // Flatten the entry and its sibling layouts into one source list, the
+        // same traversal findInterceptForRoute uses; the build keeps ALL matches
+        // (not just the innermost) and skips when(). intercept/layout are
+        // non-optional arrays, so empty ones are a no-op here.
+        for (const source of [current, ...current.layout]) {
+          for (const ic of source.intercept) {
             if (ic.routeName === matched.routeKey) {
-              foundIntercepts.push({ intercept: ic, entry: current });
-            }
-          }
-        }
-        if (current.layout && current.layout.length > 0) {
-          for (const siblingLayout of current.layout) {
-            if (siblingLayout.intercept && siblingLayout.intercept.length > 0) {
-              for (const ic of siblingLayout.intercept) {
-                if (ic.routeName === matched.routeKey) {
-                  foundIntercepts.push({
-                    intercept: ic,
-                    entry: siblingLayout,
-                  });
-                }
-              }
+              foundIntercepts.push({ intercept: ic, entry: source });
             }
           }
         }
@@ -347,6 +329,18 @@ export async function matchForPrerender<TEnv = any>(
         const interceptResolvedSegments: typeof nonLoaderSegments = [];
 
         for (const { intercept, entry: parentEntry } of foundIntercepts) {
+          // setupBuildUse keys handle pushes by ctx._currentSegmentId. The main
+          // resolveAllSegments pass left it on the route's segment id, so pin it
+          // to THIS intercept's slot id before resolving the handler/layout --
+          // otherwise the intercept's ctx.use() handle pushes land in the wrong
+          // bucket and getDataForSegment(seg.id) below drops them from the baked
+          // artifact. Re-pinned per iteration so multiple intercepts targeting
+          // the same route each get their own id (mirrors fresh.ts parallel-slot
+          // pinning).
+          const interceptSegmentId = `${parentEntry.shortCode}.${intercept.slotName}`;
+          (buildCtx as InternalHandlerContext<any, TEnv>)._currentSegmentId =
+            interceptSegmentId;
+
           // Resolve handler
           const handlerRaw =
             typeof intercept.handler === "function"
@@ -373,7 +367,7 @@ export async function matchForPrerender<TEnv = any>(
           }
 
           interceptResolvedSegments.push({
-            id: `${parentEntry.shortCode}.${intercept.slotName}`,
+            id: interceptSegmentId,
             namespace: `intercept:${intercept.routeName}`,
             type: "parallel" as const,
             index: 0,
@@ -503,14 +497,25 @@ export async function renderStaticSegment<TEnv = any>(
     setupBuildUse(buildCtx);
 
     const raw = await handler(buildCtx);
-    const component = raw?.type ? raw : raw;
+
+    // Static handlers must return a ReactNode. A returned Response (e.g. an
+    // accidental redirect()) would otherwise be serialized as a corrupt build
+    // artifact; fail loudly instead. The fresh/revalidation paths route handler
+    // results through handleHandlerResult, which throws Responses; the static
+    // build path bypasses that, so guard here.
+    if (raw instanceof Response) {
+      throw new TypeError(
+        `Static handler "${routeName}" returned a Response. Static handlers must return a ReactNode; ` +
+          `Responses (redirects, file responses) are not supported during static pre-rendering.`,
+      );
+    }
 
     const segment: ResolvedSegment = {
       id: handlerId,
       namespace: handlerId,
       type: "layout",
       index: 0,
-      component,
+      component: raw,
       params: {},
       belongsToRoute: false,
     };

package/src/router/request-classification.ts

@@ -23,10 +23,6 @@ import { negotiateRoute } from "./content-negotiation.js";
 import { stripInternalParams } from "./handler-context.js";
 import { resolveRoute, type RouteSnapshot } from "./route-snapshot.js";
 
-// ---------------------------------------------------------------------------
-// RequestPlan — discriminated union
-// ---------------------------------------------------------------------------
-
 interface RedirectPlan<TEnv = any> {
   mode: "redirect";
   route: RouteSnapshot<TEnv>;
@@ -124,10 +120,6 @@ export type {
   PartialRenderPlan,
 };
 
-// ---------------------------------------------------------------------------
-// classifyRequest — the single authoritative classification step
-// ---------------------------------------------------------------------------
-
 export interface ClassifyRequestDeps<TEnv = any> {
   findMatch: (pathname: string) => RouteMatchResult<TEnv> | null;
   routerVersion: string;
@@ -157,15 +149,12 @@ export async function classifyRequest<TEnv = any>(
   const isAction =
     request.headers.has("rsc-action") || url.searchParams.has("_rsc_action");
 
-  // Version mismatch — runs BEFORE route resolution so stale clients
-  // requesting removed routes get a reload, not a 404.
   const clientVersion = url.searchParams.get("_rsc_v");
   if (
     deps.routerVersion &&
     clientVersion &&
     clientVersion !== deps.routerVersion
   ) {
-    // Strip internal _rsc_* params so the browser reloads to a clean URL
     let reloadUrl = stripInternalParams(url).toString();
     if (isAction) {
       const referer = request.headers.get("referer");
@@ -175,9 +164,7 @@ export async function classifyRequest<TEnv = any>(
           if (refererUrl.origin === url.origin) {
             reloadUrl = referer;
           }
-        } catch {
-          // Malformed referer, fall back to stripped url
-        }
+        } catch {}
       }
     }
 
@@ -187,18 +174,6 @@ export async function classifyRequest<TEnv = any>(
     };
   }
 
-  // App switch — also runs BEFORE route resolution (like version-mismatch
-  // above), and for the same reason: a cross-app SPA navigation must reload
-  // even when the target route does NOT exist in the target app. If we resolved
-  // first, a missing route would throw RouteNotFoundError and the 404 would
-  // render in-place under the SOURCE app's document — violating the invariant
-  // that crossing a host-router app boundary is always a full document load.
-  // A mismatched routerId (_rsc_rid) means the navigation crossed an app
-  // boundary; force a real document navigation. A soft swap can't faithfully
-  // re-establish the target app's document (stylesheets shared across apps are
-  // dropped by React 19's by-href dedup; theme/warmup/prefetch-TTL are
-  // document-lifetime — see browser/app-shell.ts). Only SPA (`_rsc_partial`)
-  // requests need this; a direct full load already IS the document navigation.
   const clientRouterId = url.searchParams.get("_rsc_rid");
   if (
     clientRouterId &&
@@ -211,9 +186,6 @@ export async function classifyRequest<TEnv = any>(
     };
   }
 
-  // No metricsStore — classification is a lightweight gating step.
-  // Route-matching and manifest-loading metrics belong in the match path
-  // (createMatchContextForFull/Partial) which runs the authoritative resolution.
   const result = await resolveRoute<TEnv>(pathname, {
     findMatch: deps.findMatch,
     lite: true,
@@ -225,7 +197,6 @@ export async function classifyRequest<TEnv = any>(
     });
   }
 
-  // Redirect
   if (result.type === "redirect") {
     const snapshot: RouteSnapshot<TEnv> = {
       matched: result as any,
@@ -247,7 +218,6 @@ export async function classifyRequest<TEnv = any>(
 
   const snapshot = result.snapshot;
 
-  // Response route — non-RSC short-circuit (JSON, streaming, etc.)
   const responseResult = await classifyResponseRoute(
     request,
     pathname,
@@ -257,7 +227,6 @@ export async function classifyRequest<TEnv = any>(
     return responseResult;
   }
 
-  // Mode detection from request signals
   const actionId =
     request.headers.get("rsc-action") || url.searchParams.get("_rsc_action");
   const isLoaderFetch = url.searchParams.has("_rsc_loader");
@@ -275,7 +244,6 @@ export async function classifyRequest<TEnv = any>(
     return { mode: "loader", route: snapshot };
   }
 
-  // PE detection: POST with form content-type, but not a server action
   const contentType = request.headers.get("content-type") || "";
   const isFormSubmission =
     contentType.includes("multipart/form-data") ||
@@ -291,10 +259,6 @@ export async function classifyRequest<TEnv = any>(
   return { mode: "full-render", route: snapshot, negotiated };
 }
 
-// ---------------------------------------------------------------------------
-// Content negotiation for response routes
-// ---------------------------------------------------------------------------
-
 /**
  * Check if the route is a response route and perform content negotiation
  * if negotiate variants exist. Returns a ResponseRoutePlan if the route
@@ -305,7 +269,6 @@ async function classifyResponseRoute<TEnv>(
   pathname: string,
   snapshot: RouteSnapshot<TEnv>,
 ): Promise<ResponseRoutePlan<TEnv> | null> {
-  // negotiateRoute returns the response plan (variant or plain) or null for RSC.
   const negotiation = await negotiateRoute(request, pathname, snapshot);
   return negotiation
     ? { mode: "response", route: snapshot, ...negotiation }

package/src/router/revalidation.ts

@@ -14,6 +14,7 @@ import {
 import type { RevalidationTraceEntry } from "./logging.js";
 import { _getRequestContext } from "../server/request-context.js";
 import { isAutoGeneratedRouteName } from "../route-name.js";
+import { paramsEqual } from "./params-util.js";
 
 /**
  * Resolve a server-action reference's stable id, mirroring how the action
@@ -32,16 +33,21 @@ function resolveActionRefId(ref: unknown): string | undefined {
 }
 
 /**
- * Build the `isAction()` helper bound to the current action's id. Matches a
- * single imported action reference, several (variadic), or any export of a
- * namespace import (`import * as Mod`). Returns `false` when there is no action
- * (plain navigation) or nothing matches.
+ * Build the `isAction()` helper bound to the current action's id. Called with no
+ * arguments it answers "is this request an action at all?" (any action) — `true`
+ * during action handling, `false` on plain navigation. Called with one or more
+ * action references it narrows to those: a single imported action, several
+ * (variadic), or any export of a namespace import (`import * as Mod`). Returns
+ * `false` when there is no action (plain navigation) or nothing matches.
  */
 function makeIsAction(
   currentActionId: string | undefined,
 ): (...actions: ActionRef[]) => boolean {
   return (...actions: ActionRef[]): boolean => {
     if (!currentActionId) return false;
+    // Bare isAction(): an action is in flight (currentActionId is set) and the
+    // caller did not narrow to a specific action, so this is "any action".
+    if (actions.length === 0) return true;
     for (const action of actions) {
       if (typeof action === "function") {
         if (resolveActionRefId(action) === currentActionId) return true;
@@ -56,22 +62,6 @@ function makeIsAction(
   };
 }
 
-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;
-}
-
 /**
  * Options for revalidation evaluation
  */
@@ -136,8 +126,6 @@ export async function evaluateRevalidation<TEnv>(
   const paramsChanged = !paramsEqual(nextParams, prevParams);
   const searchChanged = prevUrl.search !== nextUrl.search;
 
-  // Trace helper: push a structured entry to the request-scoped trace buffer.
-  // Guarded by isTraceActive() so object construction is skipped in production.
   function pushTrace(
     defaultVal: boolean,
     finalVal: boolean,
@@ -156,43 +144,28 @@ export async function evaluateRevalidation<TEnv>(
     });
   }
 
-  // Calculate default revalidation based on segment type and request method
   let defaultShouldRevalidate: boolean;
   let defaultReason: string;
 
   if (defaultOverride) {
-    // Caller injected the seed (e.g. parallel slot not in clientSegmentIds).
-    // Skip the type-derived heuristic — caller knows better in this context.
     defaultShouldRevalidate = defaultOverride.value;
     defaultReason = defaultOverride.reason;
   } else if (request.method === "POST") {
-    // Actions: revalidate segments that belong to the route, skip parent chain
     if (segment.type === "route") {
-      // Route segment always revalidates on actions
       defaultShouldRevalidate = true;
       defaultReason = "action:route-segment";
     } else if (segment.type === "loader") {
-      // Loaders always revalidate on actions - they often contain action-sensitive data
-      // (e.g., cart count after add-to-cart action)
       defaultShouldRevalidate = true;
       defaultReason = "action:loader-segment";
     } else if (segment.belongsToRoute) {
-      // Segment belongs to route (orphan layouts/parallels) - revalidate
       defaultShouldRevalidate = true;
       defaultReason = "action:belongs-to-route";
     } else {
-      // Parent chain segment (shared layouts/parallels) - don't revalidate
       defaultShouldRevalidate = false;
       defaultReason = "action:parent-chain-skip";
     }
   } else {
-    // Navigation (GET): Conservative defaults to minimize unnecessary revalidations
-    // Only the route segment revalidates by default - all others require explicit opt-in
-
     if (segment.type === "route") {
-      // Route segments revalidate when path params OR search params change.
-      // Search params (e.g., ?page=2&sort=price) are server-parsed via ctx.search,
-      // so the handler must re-execute to produce updated content.
       const routeChanged = paramsChanged || searchChanged;
       defaultShouldRevalidate = routeChanged;
       defaultReason = paramsChanged
@@ -208,8 +181,6 @@ export async function evaluateRevalidation<TEnv>(
         });
       }
     } else if (segment.belongsToRoute && (paramsChanged || searchChanged)) {
-      // Children of the route path (loaders, orphan layouts/parallels)
-      // revalidate when path params or search params change
       defaultShouldRevalidate = true;
       defaultReason = paramsChanged
         ? "nav:route-child-params-changed"
@@ -221,9 +192,6 @@ export async function evaluateRevalidation<TEnv>(
         searchChanged,
       });
     } else {
-      // Parent layouts and parallels default to no revalidation
-      // Cannot assume these segments depend on params without explicit declaration
-      // Use custom revalidation functions to opt-in when needed
       defaultShouldRevalidate = false;
       defaultReason = "nav:non-route-skip";
       debugLog("revalidation", "non-route segment skipped by default", {
@@ -233,7 +201,6 @@ export async function evaluateRevalidation<TEnv>(
     }
   }
 
-  // No custom revalidations defined - return default behavior without prev segment
   if (revalidations.length === 0) {
     if (defaultShouldRevalidate) {
       debugLog("revalidation", "default revalidate=true", {
@@ -250,14 +217,10 @@ export async function evaluateRevalidation<TEnv>(
     return defaultShouldRevalidate;
   }
 
-  // Custom revalidations exist - may need full prev segment
-  // Lazy load prev segment only if getPrevSegment provided
   const prevSegment = getPrevSegment ? await getPrevSegment() : null;
 
-  // Execute revalidation functions with soft/hard decision pattern
   let currentSuggestion = defaultShouldRevalidate;
 
-  // Compute public route names (filtered: undefined for auto-generated routes)
   const toRouteName =
     routeKey && !isAutoGeneratedRouteName(routeKey) ? routeKey : undefined;
   const reqCtx = _getRequestContext();
@@ -285,20 +248,14 @@ export async function evaluateRevalidation<TEnv>(
       actionUrl: actionContext?.actionUrl,
       actionResult: actionContext?.actionResult,
       formData: actionContext?.formData,
-      method: request.method, // GET for navigation, POST for actions
-      routeName: toRouteName, // Navigation target route name (filtered)
-      fromRouteName, // Navigation source route name (filtered)
-      toRouteName, // Navigation target route name (filtered)
-      // Stale cache context (only true for background revalidation after stale cache render)
+      method: request.method,
+      routeName: toRouteName,
+      fromRouteName,
+      toRouteName,
       stale,
     });
 
-    // Check return type:
-    // - boolean: hard decision, short-circuit immediately
-    // - { defaultShouldRevalidate: boolean }: soft decision, update suggestion and continue
-    // - null/undefined: use default behavior (equivalent to returning { defaultShouldRevalidate })
     if (typeof result === "boolean") {
-      // Hard decision - short-circuit
       debugLog("revalidation", "hard decision", {
         segmentId: segment.id,
         revalidator: name,
@@ -311,7 +268,6 @@ export async function evaluateRevalidation<TEnv>(
       typeof result === "object" &&
       "defaultShouldRevalidate" in result
     ) {
-      // Soft decision - update suggestion and continue
       currentSuggestion = result.defaultShouldRevalidate;
       debugLog("revalidation", "soft decision", {
         segmentId: segment.id,
@@ -319,18 +275,14 @@ export async function evaluateRevalidation<TEnv>(
         revalidate: currentSuggestion,
       });
     } else if (result === null || result === undefined) {
-      // Defer to default - equivalent to { defaultShouldRevalidate: currentSuggestion }
-      // This means "I don't care, use whatever the default is"
       debugLog("revalidation", "deferred to current default", {
         segmentId: segment.id,
         revalidator: name,
         revalidate: currentSuggestion,
       });
-      // currentSuggestion stays the same, continue to next function
     }
   }
 
-  // All revalidators completed - use final suggestion
   debugLog("revalidation", "final decision", {
     segmentId: segment.id,
     revalidate: currentSuggestion,

package/src/router/route-snapshot.ts

@@ -230,7 +230,6 @@ export function createRouteSnapshot<TEnv = any>(
       entry: {} as any,
       routeKey: "test",
       params: {},
-      optionalParams: new Set(),
     } as RouteMatchResult<TEnv>,
     manifestEntry: { type: "route", shortCode: "R0", parent: null } as any,
     entries: [],

package/src/router/router-context.ts

@@ -54,10 +54,8 @@ export interface InterceptResult {
  * Instead of passing 20+ parameters, middleware calls getRouterContext() to access them.
  */
 export interface RouterContext<TEnv = any> {
-  // Route matching
   findMatch: (pathname: string) => RouteMatchResult | null;
 
-  // Manifest loading
   loadManifest: (
     entry: any,
     routeKey: string,
@@ -66,10 +64,8 @@ export interface RouterContext<TEnv = any> {
     isSSR?: boolean,
   ) => Promise<EntryData>;
 
-  // Entry traversal
   traverseBack: (entry: EntryData) => Generator<EntryData>;
 
-  // Handler context creation
   createHandlerContext: (
     params: Record<string, string>,
     request: Request,
@@ -83,7 +79,6 @@ export interface RouterContext<TEnv = any> {
     isPassthroughRoute?: boolean,
   ) => HandlerContext<any, TEnv>;
 
-  // Loader setup
   setupLoaderAccess: (
     ctx: HandlerContext<any, TEnv>,
     loaderPromises: Map<string, Promise<any>>,
@@ -94,7 +89,6 @@ export interface RouterContext<TEnv = any> {
     loaderPromises: Map<string, Promise<any>>,
   ) => void;
 
-  // Context access
   getContext: () => {
     getOrCreateStore: (key: string) => any;
     runWithStore: <T>(
@@ -105,16 +99,13 @@ export interface RouterContext<TEnv = any> {
     ) => T;
   };
 
-  // Metrics
   getMetricsStore: () => MetricsStore | undefined;
 
-  // Cache
   createCacheScope: (
     cacheConfig: any,
     parent: CacheScope | null,
   ) => CacheScope | null;
 
-  // Intercept detection
   findInterceptForRoute: (
     routeKey: string,
     parentEntry: EntryData | null,
@@ -122,7 +113,6 @@ export interface RouterContext<TEnv = any> {
     isAction: boolean,
   ) => InterceptResult | null;
 
-  // Segment resolution (with revalidation)
   resolveAllSegmentsWithRevalidation: (
     entries: EntryData[],
     routeKey: string,
@@ -133,7 +123,6 @@ export interface RouterContext<TEnv = any> {
     request: Request,
     prevUrl: URL,
     nextUrl: URL,
-    loaderPromises: Map<string, Promise<any>>,
     actionContext: any | undefined,
     interceptResult: InterceptResult | null,
     localRouteName: string,
@@ -166,12 +155,10 @@ export interface RouterContext<TEnv = any> {
     revalidationContext?: RevalidationContext,
   ) => Promise<ResolvedSegment[]>;
 
-  // Collect with markers
   collectWithMarkers?: <T>(
     gen: AsyncGenerator<T | { __type: "id"; id: string }>,
   ) => Promise<{ items: T[]; matchedIds: string[] }>;
 
-  // Revalidation evaluation
   evaluateRevalidation: (params: {
     segment: ResolvedSegment;
     prevParams: Record<string, string>;
@@ -195,7 +182,6 @@ export interface RouterContext<TEnv = any> {
       | "intercept-loader";
   }) => Promise<boolean>;
 
-  // Request context
   getRequestContext: () =>
     | {
         waitUntil: (fn: () => Promise<void>) => void;
@@ -203,7 +189,6 @@ export interface RouterContext<TEnv = any> {
       }
     | undefined;
 
-  // Simple segment resolution (without revalidation - for full match)
   resolveAllSegments: (
     entries: EntryData[],
     routeKey: string,
@@ -213,7 +198,6 @@ export interface RouterContext<TEnv = any> {
     options?: { skipLoaders?: boolean },
   ) => Promise<ResolvedSegment[]>;
 
-  // Generator-based simple resolution
   resolveAllSegmentsGenerator?: (
     entries: EntryData[],
     routeKey: string,
@@ -222,21 +206,17 @@ export interface RouterContext<TEnv = any> {
     loaderPromises: Map<string, Promise<any>>,
   ) => AsyncGenerator<ResolvedSegment | { __type: "id"; id: string }>;
 
-  // Collect segments from generator
   collectSegmentsFromGenerator?: <T>(
     gen: AsyncGenerator<T | { __type: "id"; id: string }>,
   ) => Promise<T[]>;
 
-  // Handle store
   createHandleStore: () => any;
 
-  // Loaders-only resolution (for full match cache hit - no revalidation)
   resolveLoadersOnly?: (
     entries: EntryData[],
     handlerContext: HandlerContext<any, TEnv>,
   ) => Promise<ResolvedSegment[]>;
 
-  // Loaders-only resolution (for cache hit scenarios)
   resolveLoadersOnlyWithRevalidation?: (
     entries: EntryData[],
     handlerContext: HandlerContext<any, TEnv>,
@@ -258,10 +238,8 @@ export interface RouterContext<TEnv = any> {
   // Telemetry sink (optional, no-op when undefined)
   telemetry?: TelemetrySink;
 
-  // Request ID for telemetry span correlation (set per-request in match handlers)
   requestId?: string;
 
-  // Intercept loaders only (for cache hit + intercept scenarios)
   resolveInterceptLoadersOnly?: (
     intercept: InterceptEntry,
     entry: EntryData,
@@ -284,7 +262,6 @@ export interface RouterContext<TEnv = any> {
   } | null>;
 }
 
-// AsyncLocalStorage instance for router context
 const routerContext = new AsyncLocalStorage<RouterContext<any>>();
 
 /**
@@ -308,10 +285,6 @@ export function getRouterContext<TEnv = any>(): RouterContext<TEnv> {
  *
  * All async code within fn() can call getRouterContext() to access router closures.
  * This works across async boundaries thanks to AsyncLocalStorage.
- *
- * @param deps Router dependencies to make available
- * @param fn Function to run with dependencies available
- * @returns Result of fn()
  */
 export function runWithRouterContext<T, TEnv = any>(
   deps: RouterContext<TEnv>,