@rangojs/router 0.0.0-experimental.137 → 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

@@ -33,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: (
@@ -74,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

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/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/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/urls/include-helper.ts

@@ -9,6 +9,7 @@ import {
   validateUserRouteName,
 } from "../route-name.js";
 import type { UrlPatterns, IncludeOptions } from "./pattern-types.js";
+import type { IncludeProvider } from "./include-provider.js";
 import type { IncludeFn } from "./path-helper-types.js";
 
 function hasExplicitNameOption(options: IncludeOptions | undefined): boolean {
@@ -60,7 +61,11 @@ export function processItems(items: readonly AllUseItems[]): AllUseItems[] {
 export function createIncludeHelper<TEnv>(): IncludeFn<TEnv> {
   return (
     prefix: string,
-    patterns: UrlPatterns<TEnv>,
+    // A `urls()` value (eager) OR an async provider thunk
+    // (`() => import("./routes")`) whose evaluation is deferred to the first
+    // request matching `prefix`. The provider is stored unevaluated and
+    // resolved by the runtime lazy-include expansion / build-time discovery.
+    patterns: UrlPatterns<TEnv> | IncludeProvider<TEnv>,
     options?: IncludeOptions,
   ): IncludeItem => {
     const { ctx } = requireDslContext("include() must be called inside urls()");
@@ -81,10 +86,9 @@ export function createIncludeHelper<TEnv>(): IncludeFn<TEnv> {
         ? capturedUrlPrefix + prefix.slice(1)
         : capturedUrlPrefix + prefix
       : prefix;
-    const internalScope = !hasExplicitName
-      ? allocateInternalIncludeScopeId(ctx.counters)
-      : undefined;
-    const nextSegment = hasExplicitName ? explicitName : internalScope;
+    const nextSegment = hasExplicitName
+      ? explicitName
+      : allocateInternalIncludeScopeId(ctx.counters);
     const fullNamePrefix =
       nextSegment !== undefined && nextSegment !== ""
         ? capturedNamePrefix
@@ -117,9 +121,7 @@ export function createIncludeHelper<TEnv>(): IncludeFn<TEnv> {
     if (capturedParent?.shortCode) {
       const includeCounterKey = `${capturedParent.shortCode}${parentScope}_include`;
       ctx.counters[includeCounterKey] ??= 0;
-      const includeIdx = ctx.counters[includeCounterKey];
-      ctx.counters[includeCounterKey] = includeIdx + 1;
-      includeScope = `${parentScope}I${includeIdx}`;
+      includeScope = `${parentScope}I${ctx.counters[includeCounterKey]++}`;
     }
 
     // Snapshot parent's counters AFTER allocating the include scope so lazy

package/src/urls/include-provider.ts

@@ -0,0 +1,71 @@
+import type { UrlPatterns } from "./pattern-types.js";
+
+/**
+ * What an async `include()` provider may resolve to: a `urls()` value directly,
+ * or a module namespace whose `default` export is a `urls()` value (the shape
+ * produced by `() => import("./routes")` when the route module does
+ * `export default urls(...)`).
+ */
+export type IncludeModule<TEnv = any> =
+  | UrlPatterns<TEnv>
+  | { default: UrlPatterns<TEnv> };
+
+/**
+ * An async/lazy include provider: a thunk returning a `urls()` value (or a
+ * Promise of one). The thunk is stored unevaluated by `include()` and called
+ * once, on the first request that matches the prefix — so the route module and
+ * its (code-split) subtree are not evaluated at startup.
+ *
+ * Forward-compatible: `() => import("./routes")` today (async, separate chunk);
+ * `() => m.routes` with native `import defer` later (sync, deferred eval).
+ */
+export type IncludeProvider<TEnv = any> = () =>
+  | IncludeModule<TEnv>
+  | Promise<IncludeModule<TEnv>>;
+
+/** True when the include() argument is a provider thunk rather than a value. */
+export function isIncludeProvider(value: unknown): value is IncludeProvider {
+  // A `urls()` value is a (branded) object; a provider is a function.
+  return typeof value === "function";
+}
+
+/** A `urls()` value is an object exposing a synchronous `handler()`. */
+function isUrlPatterns(value: unknown): value is UrlPatterns {
+  return (
+    !!value && typeof (value as { handler?: unknown }).handler === "function"
+  );
+}
+
+/**
+ * Normalize an async provider's resolved value to a `UrlPatterns`. Accepts a
+ * `urls()` value directly or a module whose `default` export is one.
+ */
+export function resolveIncludeModule<TEnv = any>(
+  mod: IncludeModule<TEnv>,
+  id?: string,
+): UrlPatterns<TEnv> {
+  // Prefer an explicit `default` export (the `export default urls(...)`
+  // convention) BEFORE duck-typing the namespace. isUrlPatterns() keys on a
+  // `.handler` function, but a routes module can legitimately carry a NAMED
+  // `export function handler(...)` alongside its `export default urls(...)`;
+  // checking the namespace first would then misidentify the whole module as the
+  // urls() value and invoke the user's helper as the DSL handler (the group
+  // 404s with a misleading error). A bare `() => urls(...)` provider (no
+  // module) has no `default`, so it still resolves via the mod-as-value branch.
+  const def = (mod as { default?: unknown })?.default;
+  if (isUrlPatterns(def)) return def as UrlPatterns<TEnv>;
+  if (isUrlPatterns(mod)) return mod as UrlPatterns<TEnv>;
+  // The common failure is a module namespace whose `default` is missing or not a
+  // urls() value (e.g. only named exports); `typeof` alone says "object" and
+  // hides that, so name the keys present. "provider" (not "async provider") —
+  // synchronous providers are supported (see IncludeProvider).
+  const got =
+    mod && typeof mod === "object"
+      ? `a module with keys [${Object.keys(mod).join(", ") || "none"}] but no valid \`default\``
+      : typeof mod;
+  throw new Error(
+    `[@rangojs/router] include() provider${id ? ` for "${id}"` : ""} must ` +
+      `resolve to a urls() value — either returned directly or as the module's ` +
+      `\`default\` export (e.g. \`export default urls(...)\`). Got ${got}.`,
+  );
+}

package/src/urls/path-helper-types.ts

@@ -152,6 +152,30 @@ export type TextResponsePathFn<TEnv> = <
   use?: () => UseItems<ResponseRouteUseItem>,
 ) => TypedRouteItem<TName, TPattern, string, TSearch>;
 
+/**
+ * What an async include() provider resolves to. Route types (`TRoutes`) are
+ * inferred from the resolved `urls()` value so `href()` and named routes stay
+ * type-safe through a code-split module (`() => import("./routes")`).
+ */
+type IncludeResolved<
+  TEnv,
+  TRoutes extends Record<string, any>,
+  TResponses extends Record<string, unknown>,
+> =
+  | UrlPatterns<TEnv, TRoutes, TResponses>
+  | { default: UrlPatterns<TEnv, TRoutes, TResponses> };
+
+/** include() argument: an eager `urls()` value or an async provider thunk. */
+export type IncludeArg<
+  TEnv,
+  TRoutes extends Record<string, any>,
+  TResponses extends Record<string, unknown>,
+> =
+  | UrlPatterns<TEnv, TRoutes, TResponses>
+  | (() =>
+      | IncludeResolved<TEnv, TRoutes, TResponses>
+      | Promise<IncludeResolved<TEnv, TRoutes, TResponses>>);
+
 /**
  * Base include function signature.
  */
@@ -162,7 +186,7 @@ export type IncludeFn<TEnv> = <
   TResponses extends Record<string, unknown> = Record<string, unknown>,
 >(
   prefix: TUrlPrefix,
-  patterns: UrlPatterns<TEnv, TRoutes, TResponses>,
+  patterns: IncludeArg<TEnv, TRoutes, TResponses>,
   options?: IncludeOptions<TNamePrefix>,
 ) => TypedIncludeItem<TRoutes, TNamePrefix, TUrlPrefix, TResponses>;
 

package/src/vite/discovery/discover-routers.ts

@@ -186,7 +186,7 @@ export async function discoverRouters(
       continue;
     }
 
-    const manifest = generateManifestFull(
+    const manifest = await generateManifestFull(
       router.urlpatterns,
       routerMountIndex,
       {

package/src/vite/router-discovery.ts

@@ -544,6 +544,14 @@ export function createRouterDiscoveryPlugin(
           );
           console.warn(`[rango] Failed to create temp runner: ${err.message}`);
         }
+        // Reached only on failure (runner unavailable, or create/import threw
+        // AFTER the server was created). Close the just-created server so a
+        // failed discovery does not leak it until the next call or dev shutdown,
+        // and null the refs so the reuse path above starts clean. Mirrors the
+        // close pattern used when an existing server is discarded (above).
+        await prerenderTempServer?.close().catch(() => {});
+        prerenderTempServer = null;
+        prerenderNodeRegistry = null;
         return null;
       }