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

package/src/router/content-negotiation.ts

@@ -14,7 +14,6 @@ import { traverseBack } from "./pattern-matching.js";
 import type { RouteMatchResult } from "./pattern-matching.js";
 import type { RouteSnapshot } from "./route-snapshot.js";
 
-// Response type -> MIME type used for Accept header matching
 export const RESPONSE_TYPE_MIME: Record<string, string> = {
   json: "application/json",
   text: "text/plain",
@@ -23,7 +22,6 @@ export const RESPONSE_TYPE_MIME: Record<string, string> = {
   md: "text/markdown",
 };
 
-// Reverse lookup: MIME type -> response type tag (e.g. "text/html" -> "html")
 export const MIME_RESPONSE_TYPE: Record<string, string> = Object.fromEntries(
   Object.entries(RESPONSE_TYPE_MIME).map(([tag, mime]) => [mime, tag]),
 );
@@ -71,12 +69,10 @@ export function parseAcceptTypes(accept: string): AcceptEntry[] {
     }
     entries.push({ mime, q, order: i });
   }
-  // Sort: highest q first, then lowest client order first (stable)
   entries.sort((a, b) => b.q - a.q || a.order - b.order);
   return entries;
 }
 
-// Sentinel response type for RSC routes in negotiation candidates
 export const RSC_RESPONSE_TYPE = "__rsc__";
 
 /**
@@ -89,7 +85,6 @@ export function pickNegotiateVariant(
   acceptEntries: AcceptEntry[],
   candidates: Array<{ routeKey: string; responseType: string }>,
 ): { routeKey: string; responseType: string } {
-  // Build a MIME -> candidate lookup for O(1) matching
   const byCandidateMime = new Map<
     string,
     { routeKey: string; responseType: string }
@@ -106,9 +101,7 @@ export function pickNegotiateVariant(
 
   for (const entry of acceptEntries) {
     if (entry.q === 0) continue;
-    // Wildcard matches first candidate
     if (entry.mime === "*/*") return candidates[0]!;
-    // Type wildcard (e.g. "text/*") -- match first candidate with that type
     if (entry.mime.endsWith("/*")) {
       const typePrefix = entry.mime.slice(0, entry.mime.indexOf("/"));
       for (const [mime, candidate] of byCandidateMime) {
@@ -119,7 +112,6 @@ export function pickNegotiateVariant(
     const match = byCandidateMime.get(entry.mime);
     if (match) return match;
   }
-  // No match -- use first candidate as default
   return candidates[0]!;
 }
 
@@ -173,7 +165,6 @@ export async function negotiateRoute(
 
   const acceptEntries = parseAcceptTypes(request.headers.get("accept") || "");
 
-  // Build candidate list preserving definition order.
   const variants = matched.negotiateVariants;
   let candidates: Array<{ routeKey: string; responseType: string }>;
   if (responseType) {
@@ -190,12 +181,10 @@ export async function negotiateRoute(
 
   const variant = pickNegotiateVariant(acceptEntries, candidates);
 
-  // RSC won negotiation
   if (variant.responseType === RSC_RESPONSE_TYPE) {
     return null;
   }
 
-  // Primary response-type won — use existing manifest entry and middleware
   if (responseType && variant.routeKey === matched.routeKey) {
     return {
       responseType,
@@ -205,8 +194,6 @@ export async function negotiateRoute(
       negotiated: true,
     };
   }
-
-  // Different variant won — load its manifest entry
   const negotiateEntry = await loadManifest(
     matched.entry,
     variant.routeKey,

package/src/router/error-handling.ts

@@ -117,16 +117,10 @@ export function findNearestErrorBoundary(
   let current: EntryData | null = entry;
 
   while (current) {
-    // Check if this entry has error boundaries defined
     if (current.errorBoundary && current.errorBoundary.length > 0) {
-      // Return the last error boundary (most recently defined takes precedence)
       return current.errorBoundary[current.errorBoundary.length - 1];
     }
 
-    // Check orphan layouts for error boundaries
-    // Orphan layouts are siblings that render alongside the main route chain
-    // They can define error boundaries that catch errors from routes in the same route group
-    // Check from first to last (first sibling takes precedence as the "outer" wrapper)
     if (current.layout && current.layout.length > 0) {
       for (const orphan of current.layout) {
         if (orphan.errorBoundary && orphan.errorBoundary.length > 0) {
@@ -153,11 +147,21 @@ export function findNearestNotFoundBoundary(
   let current: EntryData | null = entry;
 
   while (current) {
-    // Check if this entry has notFound boundaries defined
     if (current.notFoundBoundary && current.notFoundBoundary.length > 0) {
-      // Return the last notFound boundary (most recently defined takes precedence)
       return current.notFoundBoundary[current.notFoundBoundary.length - 1];
     }
+
+    // Check orphan layouts mirroring findNearestErrorBoundary: notFoundBoundary
+    // attaches identically (onto parent.notFoundBoundary), and an orphan layout
+    // (parent=null) is reachable only via this scan. First sibling is "outer".
+    if (current.layout && current.layout.length > 0) {
+      for (const orphan of current.layout) {
+        if (orphan.notFoundBoundary && orphan.notFoundBoundary.length > 0) {
+          return orphan.notFoundBoundary[orphan.notFoundBoundary.length - 1];
+        }
+      }
+    }
+
     current = current.parent;
   }
 
@@ -207,22 +211,17 @@ export function createErrorSegment(
   entry: EntryData,
   params: Record<string, string>,
 ): ResolvedSegment {
-  // Determine the component to render
   let component: ReactNode;
 
   if (typeof fallback === "function") {
-    // ErrorBoundaryHandler - call with error info
     const props: ErrorBoundaryFallbackProps = {
       error: errorInfo,
     };
     component = fallback(props);
   } else {
-    // Static ReactNode fallback
     component = fallback;
   }
 
-  // Error segment uses the same ID as the layout that has the error boundary
-  // The error boundary content replaces the layout's outlet content
   return {
     id: entry.shortCode,
     namespace: entry.id,
@@ -261,17 +260,14 @@ export function createNotFoundSegment(
   entry: EntryData,
   params: Record<string, string>,
 ): ResolvedSegment {
-  // Determine the component to render
   let component: ReactNode;
 
   if (typeof fallback === "function") {
-    // NotFoundBoundaryHandler - call with props
     const props: NotFoundBoundaryFallbackProps = {
       notFound: notFoundInfo,
     };
     component = fallback(props);
   } else {
-    // Static ReactNode fallback
     component = fallback;
   }
 

package/src/router/find-match.ts

@@ -8,13 +8,10 @@ import {
 import type { MetricsStore } from "../server/context";
 import type { RouteEntry } from "../types";
 
-// Return a shallow copy with an independent `params` object. The single-entry
-// cache below is module-lifetime and keyed only on pathname, so the same result
-// object is handed to every same-pathname request in the isolate. ctx.params
-// aliases this `params` (see request-context), so without an own copy a handler
-// that mutates ctx.params would corrupt the cached entry for later requests.
-// `entry` and the flags are intentionally shared by reference: they are
-// read-only, and entry identity is compared in match-api (prevMatch.entry).
+// The single-entry cache is module-lifetime, keyed only on pathname, so the same
+// result object is handed to every same-pathname request. ctx.params aliases
+// this object, so handlers mutating it would corrupt the cache for later requests.
+// Clone params; entry/flags are read-only and shared safely.
 function cloneMatchResult<TEnv>(
   r: RouteMatchResult<TEnv> | null,
 ): RouteMatchResult<TEnv> | null {
@@ -40,21 +37,14 @@ export function createFindMatch<TEnv = any>(
   let lastFindMatchPathname: string | null = null;
   let lastFindMatchResult: RouteMatchResult<TEnv> | null = null;
 
-  // Wrapper for findMatch that uses routesEntries
-  // Handles lazy evaluation by evaluating lazy entries on first match.
-  // Phase 1: try O(path_length) trie match.
-  // Phase 2: fall back to regex iteration.
   return function findMatch(
     pathname: string,
     ms?: MetricsStore,
   ): RouteMatchResult<TEnv> | null {
-    // Return cached result if same pathname (avoids double-match per request).
-    // Clone so a caller mutating ctx.params cannot corrupt the shared cache.
     if (lastFindMatchPathname === pathname) {
       return cloneMatchResult(lastFindMatchResult);
     }
 
-    // Helper to push sub-metrics
     const pushMetric = ms
       ? (label: string, start: number) => {
           ms.metrics.push({
@@ -65,16 +55,7 @@ export function createFindMatch<TEnv = any>(
         }
       : undefined;
 
-    // Phase 1: Try trie match (O(path_length))
-    // Only use the per-router trie. The global trie merges routes from ALL
-    // routers and must not be used — in multi-router setups (host routing)
-    // overlapping paths like "/" would match the wrong app's route.
     const routeTrie = getRouterTrie(deps.routerId);
-    // Whether the trie produced a match for this pathname (independent of
-    // whether the owning RouteEntry was resolvable yet). Used to suppress the
-    // R3 dev warning below: if the trie DID match but we fell through to the
-    // regex fallback only because a lazy entry was not spliced in yet, that is
-    // not a trie gap.
     let trieMatched = false;
     if (routeTrie) {
       const trieStart = performance.now();
@@ -104,12 +85,8 @@ export function createFindMatch<TEnv = any>(
           }
         }
 
-        // If no entry had the route in its routes map, use the first matching
-        // entry as fallback (handles main entry with inline routes not yet
-        // reflected in its routes object).
         if (!entry) entry = fallbackEntry;
 
-        // If entry not found (nested include not yet discovered), evaluate parent
         if (!entry) {
           const parent = deps.routesEntries.find(
             (e) =>
@@ -133,7 +110,6 @@ export function createFindMatch<TEnv = any>(
             entry,
             routeKey: trieResult.routeKey,
             params: trieResult.params,
-            optionalParams: new Set(trieResult.optionalParams || []),
             redirectTo: trieResult.redirectTo,
             ...(trieResult.pr ? { pr: true } : {}),
             ...(trieResult.pt ? { pt: true } : {}),
@@ -150,12 +126,9 @@ export function createFindMatch<TEnv = any>(
       }
     }
 
-    // Phase 2: Fall back to existing matching (regex iteration)
     const regexStart = performance.now();
     let result = findRouteMatch(pathname, deps.routesEntries);
 
-    // If we hit a lazy entry that needs evaluation, evaluate and retry.
-    // Cap iterations to prevent infinite loops from pathological nesting.
     const MAX_LAZY_ITERATIONS = 100;
     let iterations = 0;
     while (isLazyEvaluationNeeded(result)) {

package/src/router/intercept-resolution.ts

@@ -21,7 +21,10 @@ import { getRequestContext } from "../server/request-context.js";
 import { executeInterceptMiddleware } from "./middleware.js";
 import { createReverseFunction } from "./handler-context.js";
 import { getGlobalRouteMap } from "../route-map-builder.js";
-import { handleHandlerResult } from "./segment-resolution.js";
+import {
+  handleHandlerResult,
+  warnOnStreamedResponse,
+} from "./segment-resolution.js";
 import type { SegmentResolutionDeps } from "./types.js";
 import { debugLog } from "./logging.js";
 import { runInsideLoaderScope } from "../server/context.js";
@@ -228,6 +231,12 @@ export async function resolveInterceptEntry<TEnv>(
   let loaderDataPromise: Promise<any[]> | any[] | undefined;
 
   if (interceptEntry.loading && loaderPromises.length > 0) {
+    if (handlerResult instanceof Promise) {
+      warnOnStreamedResponse(
+        handlerResult,
+        `intercept ${interceptEntry.slotName}`,
+      );
+    }
     component =
       handlerResult instanceof Promise
         ? handlerResult

package/src/router/lazy-includes.ts

@@ -18,9 +18,6 @@ export interface LazyEvalDeps<TEnv = any> {
   routerId?: string;
 }
 
-// Detect lazy includes in handler result and create placeholder entries
-// Lazy includes are IncludeItem with lazy: true and _lazyContext
-// Moved to outer scope so it can be reused by evaluateLazyEntry for nested includes
 export function findLazyIncludes<TEnv = any>(
   items: AllUseItems[],
 ): Array<{
@@ -56,7 +53,6 @@ export function findLazyIncludes<TEnv = any>(
         });
       }
     }
-    // Recursively check nested items (in layouts, etc.)
     if ((item as any).uses && Array.isArray((item as any).uses)) {
       lazyItems.push(...findLazyIncludes((item as any).uses));
     }
@@ -78,19 +74,6 @@ export function evaluateLazyEntry<TEnv = any>(
     return;
   }
 
-  // Check for pre-computed routes from build-time data.
-  // Only leaf nodes (no nested includes) are precomputed, so entries with
-  // nested lazy includes fall through to the handler below.
-  //
-  // The load-bearing protection against two includes sharing a staticPrefix
-  // lives UPSTREAM in buildPrecomputedByPrefix (build/prefix-tree-utils): a
-  // shared staticPrefix is omitted from the map entirely, so currentPrecomputed
-  // never returns routes for it and the shortcut is skipped. The live-count
-  // check below is a secondary guard only — it is TIMING-BLIND (it counts
-  // routesEntries, which cannot see a nested sibling that has not been spliced
-  // in yet), so it must NOT be relied on alone. Kept as defense-in-depth for the
-  // all-siblings-live case (e.g. several include("/", ...) placeholders created
-  // up front).
   const currentPrecomputed = deps.getPrecomputedByPrefix();
   if (currentPrecomputed) {
     const routes = currentPrecomputed.get(entry.staticPrefix);
@@ -110,33 +93,18 @@ export function evaluateLazyEntry<TEnv = any>(
     }
   }
 
-  // Mark as evaluated immediately to prevent concurrent evaluation.
-  // JS is single-threaded but handlers.handler() could theoretically yield,
-  // and the while-loop in findMatch retries after evaluation.
   entry.lazyEvaluated = true;
 
   const lazyPatterns = entry.lazyPatterns as UrlPatterns<TEnv>;
   const lazyContext = entry.lazyContext;
 
-  // Create a new context for evaluating the lazy patterns.
-  // KNOWN REDUNDANCY (LP3, docs/internal/matching-and-lazy-discovery.md): this
-  // runs lazyPatterns.handler() purely to extract `patterns` (route name ->
-  // pattern) for matching, and DISCARDS the EntryData `manifest` it builds.
-  // loadManifest() then runs the SAME handler again on the first request to
-  // build the EntryData tree for rendering. Unifying the two runs is deferred
-  // (the two run in different contexts — see the LP3 todo in
-  // lazy-include-perf.test.ts). The precomputed-entries shortcut above avoids
-  // THIS run entirely for leaf includes.
   const manifest = new Map<string, EntryData>();
   const patterns = new Map<string, string>();
   const patternsByPrefix = new Map<string, Map<string, string>>();
   const trailingSlashMap = new Map<string, TrailingSlashMode>();
 
-  // Capture the handler result to detect nested lazy includes
   let handlerResult: AllUseItems[] = [];
 
-  // Merge captured counters from include() to maintain consistent
-  // shortCode indices with sibling entries from pattern extraction
   const lazyCounters: Record<string, number> = {};
   if (lazyContext?.counters) {
     for (const [key, value] of Object.entries(lazyContext.counters)) {
@@ -158,11 +126,6 @@ export function evaluateLazyEntry<TEnv = any>(
       includeScope: lazyContext?.includeScope,
     },
     () => {
-      // Run the lazy patterns handler with the original context prefixes.
-      // The prefix comes from the IncludeItem stored in lazyPatterns. Use the
-      // slash-collapsing join so a trailing-slash parent prefix does not bake a
-      // double slash into the registered route patterns (entry.routes,
-      // reverse(), EntryData.pattern, mountPath) when the handler runs.
       const includePrefix = (entry as any)._lazyPrefix || "";
       const fullPrefix = joinPrefix(lazyContext?.urlPrefix, includePrefix);
 
@@ -176,11 +139,9 @@ export function evaluateLazyEntry<TEnv = any>(
     },
   );
 
-  // Populate the entry's routes from the patterns
   const routesObject: Record<string, string> = {};
   for (const [name, pattern] of patterns.entries()) {
     routesObject[name] = pattern;
-    // Also add to merged route map for reverse() support
     const existingPattern = deps.mergedRouteMap[name];
     if (existingPattern !== undefined && existingPattern !== pattern) {
       console.warn(
@@ -191,24 +152,14 @@ export function evaluateLazyEntry<TEnv = any>(
     deps.mergedRouteMap[name] = pattern;
   }
 
-  // Update the entry in-place
   entry.routes = routesObject as ResolvedRouteMap<any>;
 
-  // Note: Do NOT clear lazyPatterns/lazyContext here.
-  // loadManifest() needs them on every request to re-run the handler
-  // in the correct AsyncLocalStorage context (Store.manifest).
-
-  // Update trailing slash config if available
   if (trailingSlashMap.size > 0) {
     entry.trailingSlash = Object.fromEntries(trailingSlashMap);
   }
 
-  // Detect nested lazy includes and register them as new entries
   const nestedLazyIncludes = findLazyIncludes(handlerResult);
   for (const lazyInclude of nestedLazyIncludes) {
-    // Compute the full URL prefix (combining parent prefix if any). Use the
-    // slash-collapsing join so a trailing-slash parent prefix does not produce
-    // a double-slash staticPrefix the trie's sp can never match.
     const fullPrefix = joinPrefix(
       lazyInclude.context.urlPrefix,
       lazyInclude.prefix,
@@ -217,23 +168,17 @@ export function evaluateLazyEntry<TEnv = any>(
     const nestedEntry: RouteEntry<TEnv> & { _lazyPrefix?: string } = {
       prefix: "",
       staticPrefix: extractStaticPrefix(fullPrefix),
-      routes: {} as ResolvedRouteMap<any>, // Empty until first match
+      routes: {} as ResolvedRouteMap<any>,
       trailingSlash: entry.trailingSlash,
       handler: (lazyInclude.patterns as UrlPatterns<TEnv>).handler,
       mountIndex: deps.nextMountIndex(),
       routerId: deps.routerId,
-      // Lazy evaluation fields
       lazy: true,
       lazyPatterns: lazyInclude.patterns,
       lazyContext: lazyInclude.context,
       lazyEvaluated: false,
-      // Store the include prefix for evaluation
       _lazyPrefix: lazyInclude.prefix,
     };
-    // Insert nested lazy entry before any entry whose staticPrefix is a
-    // prefix of (but shorter than) this lazy entry's staticPrefix.
-    // This ensures more specific lazy includes are matched before
-    // less specific eager entries (e.g., "/href/nested" before "/href/:id").
     const nestedPrefix = nestedEntry.staticPrefix;
     let insertIndex = deps.routesEntries.length;
     if (nestedPrefix) {
@@ -251,6 +196,5 @@ export function evaluateLazyEntry<TEnv = any>(
     deps.routesEntries.splice(insertIndex, 0, nestedEntry);
   }
 
-  // Re-register route map for runtime reverse() usage
   registerRouteMap(deps.mergedRouteMap);
 }

package/src/router/loader-resolution.ts

@@ -19,8 +19,8 @@ import type {
   ErrorBoundaryFallbackProps,
   ErrorInfo,
 } from "../types";
-import type { LoaderRevalidationResult, ActionContext } from "./types";
 import { isHandle, collectHandleData, type Handle } from "../handle.js";
+import { withDefer } from "../defer.js";
 import { buildHandleSnapshot } from "../server/handle-store.js";
 import { getFetchableLoader } from "../server/fetchable-loader-store.js";
 import { _getRequestContext } from "../server/request-context.js";
@@ -71,7 +71,9 @@ export function wrapLoaderWithErrorHandling<T>(
   ) => ErrorInfo,
   onError?: LoaderErrorCallback,
 ): Promise<LoaderDataResult<T>> {
-  // Extract loader name from segmentId (format: "M1L0D0.loaderName")
+  // Extract the trailing token from segmentId (format: "<shortCode>D<i>.<loaderId>").
+  // The token is the loader's $$id (hash#export in prod, pathfrag#export in dev),
+  // not a clean display name.
   const loaderName = segmentId.split(".").pop() || "unknown";
 
   return Promise.resolve(promise)
@@ -443,28 +445,28 @@ export function setupLoaderAccess<TEnv>(
         );
       }
 
-      return (
-        dataOrFn: unknown | Promise<unknown> | (() => Promise<unknown>),
-      ) => {
-        if (!store) return;
-
-        if (typeof dataOrFn === "function") {
-          // Run the callback inside the push-callback scope so ctx.use(loader)
-          // calls it makes — including after its own awaits, for an async
-          // callback — are not registered as handler-to-loader deps and do not
-          // trip the deadlock guard. A pushed promise value is not tracked by
-          // handleStore.settled and does not block segment resolution, so it
-          // cannot form a rendered() deadlock. The ALS scope (not a plain
-          // boolean) is what survives the callback's awaits.
-          const result = runInsidePushCallbackScope(() =>
-            (dataOrFn as () => Promise<unknown>)(),
-          );
-          store.push(handle.$$id, segmentId, result);
-          return;
-        }
+      return withDefer(
+        (dataOrFn: unknown | Promise<unknown> | (() => Promise<unknown>)) => {
+          if (!store) return;
+
+          if (typeof dataOrFn === "function") {
+            // Run the callback inside the push-callback scope so ctx.use(loader)
+            // calls it makes — including after its own awaits, for an async
+            // callback — are not registered as handler-to-loader deps and do not
+            // trip the deadlock guard. A pushed promise value is not tracked by
+            // handleStore.settled and does not block segment resolution, so it
+            // cannot form a rendered() deadlock. The ALS scope (not a plain
+            // boolean) is what survives the callback's awaits.
+            const result = runInsidePushCallbackScope(() =>
+              (dataOrFn as () => Promise<unknown>)(),
+            );
+            store.push(handle.$$id, segmentId, result);
+            return;
+          }
 
-        store.push(handle.$$id, segmentId, dataOrFn);
-      };
+          store.push(handle.$$id, segmentId, dataOrFn);
+        },
+      );
     }
 
     // Deadlock guard and handler-to-loader dependency tracking.

package/src/router/logging.ts

@@ -1,8 +1,6 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import { INTERNAL_RANGO_DEBUG } from "../internal-debug.js";
 
-// -- Revalidation trace types --
-
 export interface RevalidationTraceEntry {
   segmentId: string;
   segmentType: string;
@@ -36,8 +34,6 @@ export interface RevalidationTrace {
   entries: RevalidationTraceEntry[];
 }
 
-// -- Log context --
-
 interface RouterLogContext {
   requestId: string;
   transactionId: string;
@@ -195,8 +191,6 @@ export function debugWarn(
   console.warn(`${prefix} ${message}`);
 }
 
-// -- Revalidation trace helpers --
-
 export function isTraceActive(): boolean {
   if (!INTERNAL_RANGO_DEBUG) return false;
   const ctx = routerLogContext.getStore();

package/src/router/manifest.ts

@@ -1,9 +1,3 @@
-/**
- * Router Manifest Loading
- *
- * Handles lazy loading and validation of route manifests.
- */
-
 import { invariant, RouteNotFoundError } from "../errors";
 import { createRouteHelpers } from "../route-definition";
 import {
@@ -37,14 +31,6 @@ import { VERSION } from "@rangojs/router:version";
 // When VERSION changes, this module re-evaluates and the cache is recreated empty.
 const manifestModuleCache = new Map<string, Map<string, EntryData>>();
 
-/**
- * Load manifest from route entry with AsyncLocalStorage context
- * Handles lazy imports, unwrapping, and validation
- *
- * Results are cached at module level after first execution. Subsequent calls
- * for the same (routerId, mountIndex, routeKey, isSSR) within the same isolate
- * return cached data without re-executing the DSL handler.
- */
 /**
  * Clear the module-level manifest cache.
  * Called on HMR to ensure stale handler references are discarded.
@@ -98,20 +84,15 @@ export async function loadManifest(
   const storeSetupStart = performance.now();
   const Store = getContext().getOrCreateStore(routeKey);
 
-  // Set mount index in store for unique shortCode prefixes
   Store.mountIndex = mountIndex;
-
-  // Set isSSR flag so loading() can check if we're in SSR
   Store.isSSR = isSSR;
 
-  // Attach metrics store to context if provided
   if (metricsStore) {
     Store.metrics = metricsStore;
   }
 
   pushMetric?.("manifest:store-setup", storeSetupStart);
 
-  // Clear manifest before rebuilding to prevent stale entry mutations
   const clearStart = performance.now();
   Store.manifest.clear();
   pushMetric?.("manifest:clear", clearStart);
@@ -199,20 +180,16 @@ export async function loadManifest(
           return lazyPatterns.handler();
         }
 
-        // Wrap handler execution in root layout so routes get correct parent
-        // This ensures all routes are registered with the layout as their parent
         let promiseResult: Promise<any> | null = null;
         const wrappedItems = helpers.layout(MapRootLayout, () => {
           const result = entry.handler();
           if (result instanceof Promise) {
-            // Lazy handler detected - capture promise for async handling
             promiseResult = result;
-            return []; // Return empty, we'll discard this wrapped result
+            return [];
           }
           return result;
         });
 
-        // Handle lazy (Promise-based) handlers
         if (promiseResult !== null) {
           const load = await (promiseResult as Promise<any>);
           if (
@@ -246,7 +223,6 @@ export async function loadManifest(
           );
         }
 
-        // Inline handler - routes were registered with correct parent inside layout
         return [wrappedItems].flat(3);
       },
     );

package/src/router/match-api.ts

@@ -1,10 +1,3 @@
-/**
- * Match API
- *
- * Extracted from createRouter closure. Contains match context creation functions
- * and the matchError function for error boundary resolution.
- */
-
 import { CacheScope, createCacheScope } from "../cache/cache-scope.js";
 import { RouteNotFoundError } from "../errors";
 import {
@@ -59,8 +52,6 @@ export async function createMatchContextForFull<TEnv>(
 
   const metricsStore = deps.getMetricsStore();
 
-  // Full renders always resolve fresh with isSSR: true because loadManifest
-  // keys its cache on isSSR and stamps Store.isSSR for downstream behavior.
   const result = await resolveRoute<TEnv>(pathname, {
     findMatch: (p) => deps.findMatch(p, metricsStore),
     metricsStore,
@@ -84,12 +75,10 @@ export async function createMatchContextForFull<TEnv>(
 
   const { matched } = snapshot;
 
-  // Backward compat: downstream middleware reads matched.pt
   if (snapshot.isPassthrough) {
     matched.pt = true;
   }
 
-  // Clean URL without internal _rsc* params for userland access
   const cleanUrl = stripInternalParams(url);
 
   const handlerContext = createHandlerContext(
@@ -231,7 +220,6 @@ export async function createMatchContextForPartial<TEnv>(
     matched.pt = true;
   }
 
-  // Navigation state (prev + intercept-source findMatch calls)
   const nav = resolveNavigation(request, url, matched.routeKey, {
     findMatch: deps.findMatch,
   });
@@ -239,10 +227,6 @@ export async function createMatchContextForPartial<TEnv>(
     return null;
   }
 
-  // Push route-matching metric. On the fresh path this covers all findMatch
-  // calls (current + prev + intercept-source). On the reuse path, current-route
-  // findMatch was already timed during classification, so this only covers
-  // the nav lookups (prev + intercept-source).
   if (metricsStore) {
     const isReuse = !!classifiedRoute;
     metricsStore.metrics.push({
@@ -259,7 +243,6 @@ export async function createMatchContextForPartial<TEnv>(
     });
   }
 
-  // Clean URL without internal _rsc* params for userland access
   const cleanUrl = stripInternalParams(url);
 
   const handlerContext = createHandlerContext(
@@ -304,9 +287,6 @@ export async function createMatchContextForPartial<TEnv>(
     });
   }
 
-  // Store previous route key on the request context for revalidation
-  // fromRouteName. Uses effectiveFromMatch so intercept-source navigations
-  // see the intercept origin route, not the plain previous URL route.
   setRequestContextPrevRouteKey(nav.effectiveFromMatch?.routeKey);
 
   const interceptSelectorContext: InterceptSelectorContext = {