@rangojs/router 0.0.0-experimental.136 → 0.0.0-experimental.138

package/src/router/lazy-includes.ts

@@ -9,6 +9,10 @@ import {
 import type { UrlPatterns } from "../urls.js";
 import type { AllUseItems, IncludeItem } from "../route-types.js";
 import type { ResolvedRouteMap, RouteEntry, TrailingSlashMode } from "../types";
+import {
+  isIncludeProvider,
+  resolveIncludeModule,
+} from "../urls/include-provider.js";
 
 export interface LazyEvalDeps<TEnv = any> {
   routesEntries: RouteEntry<TEnv>[];
@@ -69,7 +73,7 @@ export function findLazyIncludes<TEnv = any>(
 export function evaluateLazyEntry<TEnv = any>(
   entry: RouteEntry<TEnv>,
   deps: LazyEvalDeps<TEnv>,
-): void {
+): void | Promise<void> {
   if (!entry.lazy || entry.lazyEvaluated || !entry.lazyPatterns) {
     return;
   }
@@ -93,9 +97,52 @@ export function evaluateLazyEntry<TEnv = any>(
     }
   }
 
-  entry.lazyEvaluated = true;
+  // Async provider (`() => import("./routes")`): the route module is evaluated
+  // off the startup path, on the first request reaching this prefix. Concurrent
+  // first-hits share one in-flight promise so the import + expansion run exactly
+  // once. The eager path below stays fully synchronous (no Promise), so the
+  // per-entry match loop pays no microtask for normal includes.
+  const lazyPatterns = entry.lazyPatterns;
+  if (isIncludeProvider(lazyPatterns)) {
+    const inflight = (entry as { _lazyInflight?: Promise<void> })._lazyInflight;
+    if (inflight) return inflight;
+    const work = (async () => {
+      const resolved = resolveIncludeModule(
+        await lazyPatterns(),
+        entry.staticPrefix,
+      );
+      // Cache the resolved patterns: any later re-entry expands synchronously.
+      entry.lazyPatterns = resolved as unknown as UrlPatterns<TEnv>;
+      runExpansion(entry, deps, resolved as UrlPatterns<TEnv>);
+    })();
+    (entry as { _lazyInflight?: Promise<void> })._lazyInflight = work;
+    const clear = () => {
+      (entry as { _lazyInflight?: Promise<void> })._lazyInflight = undefined;
+    };
+    // On failure, clear the flag (lazyEvaluated stays false) so a later request
+    // can retry the import rather than wedging the route permanently.
+    work.then(clear, clear);
+    return work;
+  }
+
+  runExpansion(entry, deps, lazyPatterns as UrlPatterns<TEnv>);
+}
 
-  const lazyPatterns = entry.lazyPatterns as UrlPatterns<TEnv>;
+/**
+ * Synchronously expand a lazy entry's (already-resolved) patterns into routes
+ * and splice any nested lazy includes as new entries. Runs once per entry.
+ */
+function runExpansion<TEnv = any>(
+  entry: RouteEntry<TEnv>,
+  deps: LazyEvalDeps<TEnv>,
+  lazyPatterns: UrlPatterns<TEnv>,
+): void {
+  // lazyEvaluated is set at the END, only after the handler ran and the routes
+  // (and any nested includes) were spliced. Setting it up-front would mark the
+  // entry done even if the handler throws mid-expansion: the async provider
+  // path clears _lazyInflight on rejection so a later request can retry, but a
+  // premature lazyEvaluated=true would make evaluateLazyEntry short-circuit
+  // (line ~77) forever, wedging the route at 404 until the isolate restarts.
   const lazyContext = entry.lazyContext;
 
   const manifest = new Map<string, EntryData>();
@@ -105,12 +152,9 @@ export function evaluateLazyEntry<TEnv = any>(
 
   let handlerResult: AllUseItems[] = [];
 
-  const lazyCounters: Record<string, number> = {};
-  if (lazyContext?.counters) {
-    for (const [key, value] of Object.entries(lazyContext.counters)) {
-      lazyCounters[key] = value;
-    }
-  }
+  const lazyCounters: Record<string, number> = lazyContext?.counters
+    ? { ...lazyContext.counters }
+    : {};
 
   RangoContext.run(
     {
@@ -170,7 +214,12 @@ export function evaluateLazyEntry<TEnv = any>(
       staticPrefix: extractStaticPrefix(fullPrefix),
       routes: {} as ResolvedRouteMap<any>,
       trailingSlash: entry.trailingSlash,
-      handler: (lazyInclude.patterns as UrlPatterns<TEnv>).handler,
+      // include entries don't invoke their own handler (real handlers come from
+      // the expanded routes); use the parent's placeholder. A provider has no
+      // `.handler` until resolved, so never read it here.
+      handler: isIncludeProvider(lazyInclude.patterns)
+        ? entry.handler
+        : (lazyInclude.patterns as UrlPatterns<TEnv>).handler,
       mountIndex: deps.nextMountIndex(),
       routerId: deps.routerId,
       lazy: true,
@@ -197,4 +246,9 @@ export function evaluateLazyEntry<TEnv = any>(
   }
 
   registerRouteMap(deps.mergedRouteMap);
+
+  // Expansion fully succeeded (handler ran, routes + nested includes spliced) —
+  // mark done now so a mid-expansion throw above leaves lazyEvaluated=false and
+  // the entry retriable.
+  entry.lazyEvaluated = true;
 }

package/src/router/manifest.ts

@@ -11,8 +11,17 @@ import MapRootLayout from "../server/root-layout";
 import { joinPrefix } from "./pattern-matching.js";
 import type { RouteEntry } from "../types";
 import type { UrlPatterns } from "../urls";
+import {
+  isIncludeProvider,
+  resolveIncludeModule,
+} from "../urls/include-provider.js";
 import { VERSION } from "@rangojs/router:version";
 
+// Tags an error thrown while dynamically importing an async include's module
+// (`() => import("./routes")`) so loadManifest's outer catch re-raises it as a
+// server error rather than masking it as a RouteNotFoundError (404).
+const MODULE_LOAD_FAILURE = Symbol.for("rango.moduleLoadFailure");
+
 // Module-level manifest cache: avoids re-executing DSL handler on every request.
 // Handler execution is deterministic (components, loaders, middleware are module-level
 // stable references), so the resulting EntryData tree can be safely cached and reused
@@ -165,6 +174,29 @@ export async function loadManifest(
         // not exist in the non-lazy (root handler) path and would produce
         // mismatched shortCodes.
         if (entry.lazy && entry.lazyPatterns) {
+          // Resolve an async include provider (`() => import("./routes")`) before
+          // running its handler. The match-time precomputed shortcut can skip
+          // evaluateLazyEntry's resolution, so render-time must resolve it here;
+          // cache the resolved patterns on the entry so later renders reuse them.
+          if (isIncludeProvider(entry.lazyPatterns)) {
+            try {
+              entry.lazyPatterns = resolveIncludeModule(
+                await entry.lazyPatterns(),
+                entry.staticPrefix,
+              ) as unknown as UrlPatterns<any>;
+            } catch (err) {
+              // A failed dynamic import of a REAL, matched route's module is a
+              // server error, not a missing route. Tag it so the outer catch
+              // surfaces it as a 5xx instead of masking it as a
+              // RouteNotFoundError — which renders the 404 page (monitoring
+              // misses the failure and a CDN could cache the 404).
+              if (err && typeof err === "object") {
+                (err as Record<PropertyKey, unknown>)[MODULE_LOAD_FAILURE] =
+                  true;
+              }
+              throw err;
+            }
+          }
           const lazyPatterns = entry.lazyPatterns as UrlPatterns<any>;
           const includePrefix = (entry as any)._lazyPrefix || "";
           // Slash-collapsing join so a trailing-slash parent prefix does not
@@ -192,12 +224,7 @@ export async function loadManifest(
 
         if (promiseResult !== null) {
           const load = await (promiseResult as Promise<any>);
-          if (
-            load &&
-            load !== null &&
-            typeof load === "object" &&
-            "default" in load
-          ) {
+          if (load && typeof load === "object" && "default" in load) {
             // Promise<{ default: () => Array }> - e.g., dynamic import
             if (typeof load.default !== "function") {
               throw new Error(
@@ -255,6 +282,16 @@ export async function loadManifest(
 
     return Store.manifest.get(routeKey)!;
   } catch (e) {
+    // A tagged async-include module-load failure is a server error for a REAL
+    // matched route — re-raise it unchanged (becomes a 5xx) instead of masking
+    // it as a RouteNotFoundError (which renders/caches a 404).
+    if (
+      e &&
+      typeof e === "object" &&
+      (e as Record<PropertyKey, unknown>)[MODULE_LOAD_FAILURE]
+    ) {
+      throw e;
+    }
     throw new RouteNotFoundError(
       `Failed to load route handlers for ${path}: ${(e as Error).message}`,
       {

package/src/router/match-api.ts

@@ -220,7 +220,7 @@ export async function createMatchContextForPartial<TEnv>(
     matched.pt = true;
   }
 
-  const nav = resolveNavigation(request, url, matched.routeKey, {
+  const nav = await resolveNavigation(request, url, matched.routeKey, {
     findMatch: deps.findMatch,
   });
   if (!nav) {
@@ -404,7 +404,7 @@ export async function matchError<TEnv>(
 
   debugLog("matchError", "matching error", { pathname });
 
-  const matched = deps.findMatch(pathname);
+  const matched = await deps.findMatch(pathname);
   if (!matched) {
     debugWarn("matchError", "no route matched", { pathname });
     return null;

package/src/router/navigation-snapshot.ts

@@ -25,15 +25,17 @@ export interface NavigationSnapshot {
 }
 
 export interface ResolveNavigationDeps {
-  findMatch: (pathname: string) => RouteMatchResult | null;
+  findMatch: (
+    pathname: string,
+  ) => RouteMatchResult | null | Promise<RouteMatchResult | null>;
 }
 
-export function resolveNavigation(
+export async function resolveNavigation(
   request: Request,
   url: URL,
   currentRouteKey: string,
   deps: ResolveNavigationDeps,
-): NavigationSnapshot | null {
+): Promise<NavigationSnapshot | null> {
   const clientSegmentIds =
     url.searchParams.get("_rsc_segments")?.split(",").filter(Boolean) || [];
   const stale = url.searchParams.get("_rsc_stale") === "true";
@@ -65,10 +67,10 @@ export function resolveNavigation(
     interceptContextUrl = prevUrl;
   }
 
-  const prevMatch = deps.findMatch(prevUrl.pathname);
+  const prevMatch = await deps.findMatch(prevUrl.pathname);
   const prevParams = prevMatch?.params || {};
   const interceptContextMatch = interceptSourceUrl
-    ? deps.findMatch(interceptContextUrl.pathname)
+    ? await deps.findMatch(interceptContextUrl.pathname)
     : prevMatch;
 
   const isSameRouteNavigation = !!(

package/src/router/prerender-match.ts

@@ -1,5 +1,6 @@
 import { type ReactNode } from "react";
 import { createHandleStore } from "../server/handle-store.js";
+import { resolveSegmentHandleValues } from "../handles/deferred-resolution.js";
 import { getRequestContext } from "../server/request-context.js";
 import {
   runWithRequestContext,
@@ -32,7 +33,9 @@ import type {
 import type { RouteMatchResult } from "./pattern-matching.js";
 
 export interface PrerenderMatchDeps<TEnv = any> {
-  findMatch: (pathname: string) => RouteMatchResult<TEnv> | null;
+  findMatch: (
+    pathname: string,
+  ) => RouteMatchResult<TEnv> | null | Promise<RouteMatchResult<TEnv> | null>;
   buildRouterContext: () => RouterContext<TEnv>;
   mergedRouteMap: Record<string, string>;
   resolveAllSegments: (
@@ -73,7 +76,7 @@ export async function matchForPrerender<TEnv = any>(
   passthrough?: true;
 } | null> {
   // 1. Find the matching route entry
-  const matched = deps.findMatch(pathname);
+  const matched = await deps.findMatch(pathname);
   if (!matched) return null;
 
   // Use params from trie match if available, fall back to provided params
@@ -293,7 +296,9 @@ export async function matchForPrerender<TEnv = any>(
       for (const seg of nonLoaderSegments) {
         const segHandles = handleStore.getDataForSegment(seg.id);
         if (Object.keys(segHandles).length > 0) {
-          handlesRecord[seg.id] = segHandles;
+          // Resolve deferred values before encoding so the baked artifact holds
+          // resolved data (prerender = build-time cache).
+          handlesRecord[seg.id] = await resolveSegmentHandleValues(segHandles);
         }
       }
       const handles = await encodeHandles(handlesRecord);
@@ -394,7 +399,8 @@ export async function matchForPrerender<TEnv = any>(
           for (const seg of interceptResolvedSegments) {
             const segHandles = handleStore.getDataForSegment(seg.id);
             if (Object.keys(segHandles).length > 0) {
-              interceptHandlesRecord[seg.id] = segHandles;
+              interceptHandlesRecord[seg.id] =
+                await resolveSegmentHandleValues(segHandles);
             }
           }
           // The intercept artifact serves main + intercept segments together, so
@@ -533,7 +539,7 @@ export async function renderStaticSegment<TEnv = any>(
     const segHandles = handleStore.getDataForSegment(handlerId);
     const handles =
       Object.keys(segHandles).length > 0
-        ? await encodeHandleValue(segHandles)
+        ? await encodeHandleValue(await resolveSegmentHandleValues(segHandles))
         : "";
 
     return { encoded: serialized.encoded, handles };

package/src/router/preview-match.ts

@@ -6,7 +6,9 @@ import type { MiddlewareFn } from "./middleware.js";
 import { resolveRoute } from "./route-snapshot.js";
 
 export interface PreviewMatchDeps<TEnv = any> {
-  findMatch: (pathname: string) => RouteMatchResult<TEnv> | null;
+  findMatch: (
+    pathname: string,
+  ) => RouteMatchResult<TEnv> | null | Promise<RouteMatchResult<TEnv> | null>;
 }
 
 /**

package/src/router/request-classification.ts

@@ -121,7 +121,9 @@ export type {
 };
 
 export interface ClassifyRequestDeps<TEnv = any> {
-  findMatch: (pathname: string) => RouteMatchResult<TEnv> | null;
+  findMatch: (
+    pathname: string,
+  ) => RouteMatchResult<TEnv> | null | Promise<RouteMatchResult<TEnv> | null>;
   routerVersion: string;
   routerId: string;
 }

package/src/router/route-snapshot.ts

@@ -56,7 +56,9 @@ export type ResolveRouteResult<TEnv = any> =
   | null;
 
 export interface ResolveRouteDeps<TEnv = any> {
-  findMatch: (pathname: string) => RouteMatchResult<TEnv> | null;
+  findMatch: (
+    pathname: string,
+  ) => RouteMatchResult<TEnv> | null | Promise<RouteMatchResult<TEnv> | null>;
   metricsStore?: MetricsStore;
   isSSR?: boolean;
   /**
@@ -105,7 +107,7 @@ export async function resolveRoute<TEnv = any>(
 
   const routeMatchStart =
     metricsStore && !skipRouteMatchMetric ? performance.now() : 0;
-  const matched = deps.findMatch(pathname);
+  const matched = await deps.findMatch(pathname);
   if (metricsStore && !skipRouteMatchMetric) {
     metricsStore.metrics.push({
       label: "route-matching",

package/src/router/router-context.ts

@@ -55,7 +55,9 @@ export interface InterceptResult {
  * Instead of passing 20+ parameters, middleware calls getRouterContext() to access them.
  */
 export interface RouterContext<TEnv = any> {
-  findMatch: (pathname: string) => RouteMatchResult | null;
+  findMatch: (
+    pathname: string,
+  ) => RouteMatchResult | null | Promise<RouteMatchResult | null>;
 
   loadManifest: (
     entry: any,

package/src/router/router-interfaces.ts

@@ -9,6 +9,7 @@ import type { NonceProvider } from "../rsc/types.js";
 import type { ExecutionContext } from "../server/request-context.js";
 import type { SerializedSegmentData } from "../cache/types.js";
 import type { MiddlewareEntry, MiddlewareFn } from "./middleware.js";
+import type { RouteMatchResult } from "./pattern-matching.js";
 import type { ExtractParams } from "../types/route-config.js";
 import { RSC_ROUTER_BRAND } from "./router-registry.js";
 import type { RangoOptions, RootLayoutProps } from "./router-options.js";
@@ -516,7 +517,14 @@ export interface RangoInternal<
    * Used by classifyRequest() for request classification without
    * entering the full match pipeline.
    */
-  findMatch(pathname: string, metricsStore?: any): any;
+  // Async since a lazy async include (`() => import()`) must resolve before its
+  // routes can match. Typed (not `any`) so a consumer doing
+  // `const m = router.findMatch(p); if (!m) ...; m.entry` gets a compile error
+  // (m is a Promise) instead of the silent always-truthy bug.
+  findMatch(
+    pathname: string,
+    metricsStore?: any,
+  ): Promise<RouteMatchResult<TEnv> | null>;
 
   /**
    * Debug utility to serialize the manifest for inspection

package/src/router.ts

@@ -620,8 +620,15 @@ export function createRouter<TEnv = any>(
     routerId,
   };
 
-  function evaluateLazyEntry(entry: RouteEntry<TEnv>): void {
-    _evaluateLazyEntry(entry, lazyEvalDeps);
+  // Must return the Promise from _evaluateLazyEntry: an async include provider
+  // (`() => import("./routes")`) resolves off the startup path, and createFindMatch
+  // awaits this to know when the import + expansion have completed. Dropping it
+  // (typing this `void`) makes the import fire-and-forget, so findMatch spins the
+  // lazy-eval retry loop to its cap and returns null on the first request to any
+  // async include whose prefix isn't already covered by a unique precomputed entry
+  // (nested includes, shared prefixes, regex fallback).
+  function evaluateLazyEntry(entry: RouteEntry<TEnv>): void | Promise<void> {
+    return _evaluateLazyEntry(entry, lazyEvalDeps);
   }
 
   // Create findMatch with single-entry cache, bound to router state

package/src/rsc/handler.ts

@@ -31,6 +31,7 @@ import {
   buildRouteMiddlewareEntries,
 } from "./helpers.js";
 import { guardOutgoingRedirect } from "./redirect-guard.js";
+import { resolvedHandleStream } from "../handles/deferred-resolution.js";
 import {
   isWebSocketUpgradeResponse,
   appendVaryAccept,
@@ -1131,7 +1132,8 @@ export function createRSCHandler<
               params: {},
               isPartial: false,
               rootLayout: router.rootLayout,
-              handles: handleStore.stream(),
+              // Full (404) render: resolve deferred handle values server-side.
+              handles: resolvedHandleStream(handleStore),
               version,
               prefetchCacheTTL: router.prefetchCacheTTL,
               prefetchCacheSize: router.prefetchCacheSize,

package/src/rsc/manifest-init.ts

@@ -32,7 +32,7 @@ export async function buildRouterTrieFromUrlpatterns(
 ): Promise<void> {
   const { generateManifestFull } =
     await import("../build/generate-manifest.js");
-  const generated = generateManifestFull(
+  const generated = await generateManifestFull(
     router.urlpatterns,
     undefined,
     router.basename ? { urlPrefix: router.basename } : undefined,

package/src/rsc/progressive-enhancement.ts

@@ -15,6 +15,7 @@ import type { MiddlewareFn } from "../router/middleware.js";
 import { executeMiddleware } from "../router/middleware.js";
 import { observePhase, PHASES } from "../router/instrument.js";
 import { gateTransitions } from "./transition-gate.js";
+import { resolvedHandleStream } from "../handles/deferred-resolution.js";
 import type { RscPayload, ReactFormState } from "./types.js";
 import {
   createResponseWithMergedHeaders,
@@ -315,7 +316,8 @@ export async function handleProgressiveEnhancement<TEnv>(
         params: match.params,
         isPartial: false,
         rootLayout: ctx.router.rootLayout,
-        handles: handleStore.stream(),
+        // PE full render: resolve deferred handle values server-side.
+        handles: resolvedHandleStream(handleStore),
         version: ctx.version,
         stateCookieName: ctx.router.resolvedStateCookieName,
         themeConfig: ctx.router.themeConfig,
@@ -462,7 +464,8 @@ async function renderPeErrorBoundary<TEnv>(
       isPartial: false,
       isError: true,
       rootLayout: ctx.router.rootLayout,
-      handles: handleStore.stream(),
+      // PE error-boundary full render: resolve deferred handle values server-side.
+      handles: resolvedHandleStream(handleStore),
       version: ctx.version,
       stateCookieName: ctx.router.resolvedStateCookieName,
       themeConfig: ctx.router.themeConfig,

package/src/rsc/rsc-rendering.ts

@@ -22,6 +22,7 @@ import {
 } from "./helpers.js";
 import type { HandlerContext } from "./handler-context.js";
 import { gateTransitions } from "./transition-gate.js";
+import { resolvedHandleStream } from "../handles/deferred-resolution.js";
 
 export function handleRscRendering<TEnv>(
   ctx: HandlerContext<TEnv>,
@@ -78,7 +79,10 @@ async function handleRscRenderingInner<TEnv>(
       params: m.params,
       isPartial: false,
       rootLayout: ctx.router.rootLayout,
-      handles: handleStore.stream(),
+      // Full render: resolve deferred handle values server-side so SSR markup and
+      // the first sync useHandle read see resolved values. Partial payloads below
+      // keep streaming (handleStore.stream()).
+      handles: resolvedHandleStream(handleStore),
       version: ctx.version,
       prefetchCacheTTL: ctx.router.prefetchCacheTTL,
       prefetchCacheSize: ctx.router.prefetchCacheSize,

package/src/ssr/index.tsx

@@ -195,6 +195,7 @@ function createSsrEventController(opts: {
     subscribeToHandles: () => () => {},
     setHandleData: () => {},
     getHandleState: () => handleState,
+    setRouteSegmentIds: () => {},
     setParams: (nextParams) => {
       params = nextParams;
     },

package/src/testing/collect-handle.ts

@@ -12,7 +12,9 @@
  * It relies on createHandle registering the collect even in a bare test (it
  * assigns a runtime fallback id when the Vite plugin did not inject one). If a
  * handle's module was never imported (so createHandle never ran), the collect is
- * unregistered and this falls back to a flat array with a warning.
+ * unregistered and this falls back to the default identity collect — with a
+ * warning, since a CUSTOM collect that failed to register silently returns the
+ * wrong shape.
  */
 
 import { getCollectFn, type Handle } from "../handle.js";
@@ -25,16 +27,20 @@ export function collectHandle<TData, TAccumulated>(
     | ((segments: TData[][]) => TAccumulated)
     | undefined;
 
+  // Drop empty arrays matching production behavior (segment count/indices).
+  const nonEmpty = segments.filter((seg) => seg.length > 0) as TData[][];
+
+  // No registered collect (the handle's module was not imported): fall back to the
+  // default identity collect — the per-segment arrays as-is, mirroring production
+  // collectHandleData. Warn, because a handle with a CUSTOM collect would silently
+  // get the wrong shape (the runtime can't tell it from an intended default).
   if (!collectFn) {
     console.warn(
-      `[rango] collectHandle: handle "${handle.$$id}" has no registered collect ` +
-        `function. Import the handle's module so createHandle() runs. Falling ` +
-        `back to a flat array.`,
+      `[rango] collectHandle: handle "${handle.$$id}" has no registered collect — ` +
+        `falling back to the identity (per-segment data as-is). Import the handle's ` +
+        `module so createHandle() runs if you expected a custom collect.`,
     );
-    return segments.flat() as unknown as TAccumulated;
+    return nonEmpty as unknown as TAccumulated;
   }
-
-  // Drop empty arrays matching production behavior (segment count/indices).
-  const nonEmpty = segments.filter((seg) => seg.length > 0) as TData[][];
   return collectFn(nonEmpty);
 }

package/src/testing/dispatch.ts

@@ -140,11 +140,11 @@ interface DispatchableRouter<TEnv> {
   routeMap: Record<string, unknown>;
   middleware: MiddlewareEntry<TEnv>[];
   onError?: OnErrorCallback<TEnv>;
-  findMatch(pathname: string): {
+  findMatch(pathname: string): Promise<{
     redirectTo?: string;
     routeKey?: string;
     params?: Record<string, string>;
-  } | null;
+  } | null>;
   previewMatch(
     request: Request,
     input?: { env?: TEnv },
@@ -351,7 +351,7 @@ export async function dispatch<TEnv = any>(
 
   // findMatch carries trailing-slash/redirect targets and null on no match.
   // previewMatch swallows redirects, so detect them here first.
-  const match = router.findMatch(url.pathname);
+  const match = await router.findMatch(url.pathname);
   const redirectTo = match?.redirectTo;
   const isUnmatched = !match;
 

package/src/testing/generated-routes.ts

@@ -29,6 +29,10 @@ import { isAutoGeneratedRouteName } from "../route-name.js";
  */
 interface RouterWithRouteMap {
   routeMap: Record<string, unknown>;
+  // findMatch is async (it may await an async include provider's import before
+  // the route's names are spliced into routeMap), so expandLazyIncludes awaits
+  // it. Typed `unknown` (not `unknown | Promise<unknown>`, which collapses to
+  // the same thing) — the awaited value is never read, only its side effect.
   findMatch?: (pathname: string) => unknown;
 }
 
@@ -42,16 +46,28 @@ function concretePath(pattern: string): string {
   );
 }
 
-function expandLazyIncludes(
+async function expandLazyIncludes(
   router: RouterWithRouteMap,
   patterns: Iterable<string>,
-): void {
+): Promise<void> {
   const findMatch = router.findMatch;
   if (typeof findMatch !== "function") return;
   for (const pattern of patterns) {
     try {
-      findMatch.call(router, concretePath(pattern));
-    } catch {}
+      // Await: an async include(`() => import()`) resolves its module + splices
+      // its routes into routeMap only after findMatch's Promise settles. Without
+      // the await, the routeMap read below races the import and reports the
+      // split-group routes as missing.
+      await findMatch.call(router, concretePath(pattern));
+    } catch (e) {
+      // A findMatch throw here is almost always a failing async include()
+      // provider (its `() => import()` rejected). Surface it — swallowed, it
+      // resurfaces downstream as a misleading "missing route" in the diff.
+      console.warn(
+        `[@rangojs/router] assertGeneratedRoutesMatch: could not expand include ` +
+          `for "${pattern}": ${(e as Error)?.message ?? String(e)}`,
+      );
+    }
   }
 }
 
@@ -91,13 +107,13 @@ function patternOf(value: unknown): string {
   return String(value);
 }
 
-export function diffGeneratedRoutes(
+export async function diffGeneratedRoutes(
   router: RouterWithRouteMap,
   generatedMap?: Record<string, unknown>,
-): GeneratedRoutesDiff {
+): Promise<GeneratedRoutesDiff> {
   const generated = generatedMap ?? getGlobalRouteMap();
 
-  expandLazyIncludes(
+  await expandLazyIncludes(
     router,
     Object.values(generated).map((v) => patternOf(v)),
   );
@@ -145,14 +161,14 @@ export function diffGeneratedRoutes(
  * import generated from "./router.named-routes.gen";
  * import { router } from "./router";
  *
- * assertGeneratedRoutesMatch(router, generated);
+ * await assertGeneratedRoutesMatch(router, generated);
  * ```
  */
-export function assertGeneratedRoutesMatch(
+export async function assertGeneratedRoutesMatch(
   router: RouterWithRouteMap,
   generatedMap?: Record<string, unknown>,
-): void {
-  const diff = diffGeneratedRoutes(router, generatedMap);
+): Promise<void> {
+  const diff = await diffGeneratedRoutes(router, generatedMap);
   if (diff.ok) return;
 
   const lines: string[] = [

package/src/testing/render-route.tsx

@@ -46,6 +46,7 @@ import {
   generateHistoryKey,
 } from "../browser/navigation-store.js";
 import { createEventController } from "../browser/event-controller.js";
+import { resolveDeferredHandleValues } from "../handles/deferred-resolution.js";
 import type { NavigationStore, NavigationBridge } from "../browser/types.js";
 import type { EventController } from "../browser/event-controller.js";
 import type { ResolvedSegment, RscMetadata } from "../browser/types.js";
@@ -481,8 +482,12 @@ export async function renderRoute(
 
   const eventController = createEventController({ initialLocation: url });
   eventController.setParams(initialMatch.params);
+  // Resolve-by-default: resolve any deferred (Promise) seeded handle values
+  // before applying, so the seeded handles reach collect/useHandle resolved —
+  // matching what the server/client do in a real app.
+  const resolvedSeed = await resolveDeferredHandleValues(handleSeed);
   eventController.setHandleData(
-    handleSeed,
+    resolvedSeed,
     initialSegments.map((s) => s.id),
   );