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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.0.0-experimental.137",
+  "version": "0.0.0-experimental.138",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",
@@ -162,6 +162,17 @@
     "access": "public",
     "tag": "experimental"
   },
+  "scripts": {
+    "build": "pnpm exec esbuild src/vite/index.ts --bundle --format=esm --outfile=dist/vite/index.js --platform=node --packages=external && mkdir -p dist/vite/plugins && cp src/vite/plugins/cloudflare-protocol-loader-hook.mjs dist/vite/plugins/cloudflare-protocol-loader-hook.mjs && pnpm exec esbuild src/testing/vitest.ts --bundle --format=esm --outfile=dist/testing/vitest.js --platform=node --packages=external && pnpm exec esbuild src/bin/rango.ts --bundle --format=esm --outfile=dist/bin/rango.js --platform=node --packages=external --banner:js='#!/usr/bin/env node' && chmod +x dist/bin/rango.js",
+    "prepublishOnly": "pnpm build",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.strict-check.json --noEmit && tsc -p tsconfig.augment-check.json --noEmit",
+    "test": "playwright test",
+    "test:ui": "playwright test --ui",
+    "test:hmr-local": "playwright test --project=dev-warmup --project=hmr-routes --project=hmr-basename --project=hmr-prerender --no-deps --workers=1",
+    "test:unit": "vitest run",
+    "test:unit:watch": "vitest",
+    "test:unit:rsc": "vitest run --config vitest.rsc.config.ts"
+  },
   "dependencies": {
     "@types/debug": "^4.1.12",
     "@vitejs/plugin-rsc": "^0.5.27",
@@ -173,19 +184,19 @@
   },
   "devDependencies": {
     "@playwright/test": "^1.49.1",
+    "@shared/e2e": "workspace:*",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/react": "^16.3.2",
     "@types/node": "^24.10.1",
-    "@types/react": "^19.2.7",
-    "@types/react-dom": "^19.2.3",
+    "@types/react": "catalog:",
+    "@types/react-dom": "catalog:",
     "esbuild": "^0.28.1",
     "happy-dom": "^20.10.1",
     "jiti": "^2.6.1",
-    "react": "^19.2.6",
-    "react-dom": "^19.2.6",
+    "react": "catalog:",
+    "react-dom": "catalog:",
     "typescript": "^5.3.0",
-    "vitest": "^4.1.9",
-    "@shared/e2e": "0.0.1"
+    "vitest": "^4.1.9"
   },
   "peerDependencies": {
     "@cloudflare/vite-plugin": "^1.42.1",
@@ -216,15 +227,5 @@
   },
   "engines": {
     "node": "^20.19.0 || >=22.12.0"
-  },
-  "scripts": {
-    "build": "pnpm exec esbuild src/vite/index.ts --bundle --format=esm --outfile=dist/vite/index.js --platform=node --packages=external && mkdir -p dist/vite/plugins && cp src/vite/plugins/cloudflare-protocol-loader-hook.mjs dist/vite/plugins/cloudflare-protocol-loader-hook.mjs && pnpm exec esbuild src/testing/vitest.ts --bundle --format=esm --outfile=dist/testing/vitest.js --platform=node --packages=external && pnpm exec esbuild src/bin/rango.ts --bundle --format=esm --outfile=dist/bin/rango.js --platform=node --packages=external --banner:js='#!/usr/bin/env node' && chmod +x dist/bin/rango.js",
-    "typecheck": "tsc --noEmit && tsc -p tsconfig.strict-check.json --noEmit && tsc -p tsconfig.augment-check.json --noEmit",
-    "test": "playwright test",
-    "test:ui": "playwright test --ui",
-    "test:hmr-local": "playwright test --project=dev-warmup --project=hmr-routes --project=hmr-basename --project=hmr-prerender --no-deps --workers=1",
-    "test:unit": "vitest run",
-    "test:unit:watch": "vitest",
-    "test:unit:rsc": "vitest run --config vitest.rsc.config.ts"
   }
-}
+}

package/skills/composability/SKILL.md

@@ -160,6 +160,56 @@ export const adminPatterns = urls(({ path }) => [
 ]);
 ```
 
+## Code-splitting a route group with async include()
+
+`include()` takes a route module two ways. Eager — the module is already in the
+graph:
+
+```typescript
+import { shopPatterns } from "./shop-patterns";
+
+urls(({ include }) => [include("/shop", shopPatterns, { name: "shop" })]);
+```
+
+Async — the module is code-split behind a `() => import()` thunk. It becomes its
+own chunk that is NOT evaluated at startup; the router imports it on the first
+request that reaches the prefix, then caches it:
+
+```typescript
+urls(({ include }) => [
+  include("/shop", () => import("./shop-patterns"), { name: "shop" }),
+]);
+```
+
+The split module exposes its `urls()` value as the default export (convention):
+
+```typescript
+// src/shop-patterns.ts
+import { urls } from "@rangojs/router";
+
+export const shopPatterns = urls(({ path, include }) => [
+  path("/", ShopHome, { name: "home" }),
+  include("/product", productPatterns, { name: "product" }), // nesting is fine
+]);
+
+export default shopPatterns; // async include() resolves this
+```
+
+**Prefer the async form** for any route group that is a natural,
+independently-loadable unit (a localized section, an admin area, an API surface
+with heavy handlers) — it trims the eagerly-parsed entry bundle and keeps that
+subgraph off the cold-start path. The **eager form is still fully valid** (not
+deprecated): keep it for small groups, or ones that share most of their module
+graph with the entry (the bundler keeps shared modules common regardless, so
+splitting a thin group buys little). Both match identically at runtime — only the
+module's runtime evaluation timing differs.
+
+What you do NOT lose by splitting: build-time discovery `await`s the provider, so
+`href()`, `reverse()`, generated route types, and prerender still see every route
+in the group — including nested `include()`s inside the split module. Only the
+module's runtime evaluation defers. `rango generate` resolves the `() => import()`
+the same way, so a code-split group is still fully typed.
+
 ## Composition Types
 
 For typed factories, import the composition types:

package/skills/migrate-nextjs/SKILL.md

@@ -153,6 +153,18 @@ export const marketingPatterns = urls(({ path }) => [
 include("/", marketingPatterns, { name: "marketing" }),
 ```
 
+Next.js code-splits each route segment automatically. Rango's eager `include()`
+bundles the group into the entry chunk; to get Next-style per-section splitting,
+pass an async provider so the group loads on the first request under its prefix:
+
+```typescript
+// urls/admin.tsx: `export default adminPatterns` — loads on first /admin request
+include("/admin", () => import("./urls/admin"), { name: "admin" }),
+```
+
+Route types, `href()`, and prerender still see every route in the split group.
+See `/composability`.
+
 ### Parallel routes
 
 In Next.js, `@sidebar` and `@main` are both named slots. In Rango, the main content

package/skills/rango/SKILL.md

@@ -319,7 +319,11 @@ dotfiles, and existing `.gen.` files.
 ### Recursive includes
 
 The generator follows `include()` calls across files, resolving imports to build
-the full route tree. Circular includes are detected and warned about.
+the full route tree. It resolves both the eager form `include("/x", patterns)`
+and the code-split async form `include("/x", () => import("./x"))` — for the
+latter it walks the imported module's `export default urls(...)`, including any
+nested `include()`s inside it — so a code-split route group is still fully typed
+(see `/composability`). Circular includes are detected and warned about.
 
 ### First-wins deduplication
 

package/skills/response-routes/SKILL.md

@@ -418,6 +418,20 @@ export const urlpatterns = urls(({ path, include }) => [
 ]);
 ```
 
+A heavy module like this is a good code-split candidate. Pass an async provider
+and the module — its handlers, response serializers, and any nested
+`include()`s — loads on the first request under the prefix instead of at startup:
+
+```typescript
+// blog/urls.tsx: `export default blogPatterns`
+include("/blog", () => import("./blog/urls"), { name: "blog" }),
+```
+
+Named routes and response types still resolve through the split: `TRoutes` and
+the `_responses` phantom are inferred from the resolved `urls()` value, so
+`Rango.PathResponse<"/blog/api/stats">` and `ctx.reverse` are unchanged. See
+`/composability`.
+
 ### Type safety after mounting
 
 ```typescript

package/skills/router-setup/SKILL.md

@@ -398,6 +398,18 @@ export const urlpatterns = urls(({ path, include }) => [
 ]);
 ```
 
+`include()` also accepts an async provider to code-split that group into its own
+chunk, imported on the first request reaching the prefix instead of at startup:
+
+```typescript
+// urls/shop.tsx: `export default shopPatterns`
+include("/shop", () => import("./urls/shop"), { name: "shop" }),
+```
+
+Build-time discovery still `await`s the provider, so route types, `href()`, and
+prerender see every route in the split group. Reach for it when a group is a
+large, independently-loadable unit — see `/composability`.
+
 ## Environment Types
 
 ```typescript

package/skills/testing/reverse-and-types.md

@@ -2,7 +2,7 @@
 
 **Layer:** unit (node) + typecheck · **Import:** `@rangojs/router/client` (useReverse), `@rangojs/router/testing` (assertGeneratedRoutesMatch) · **DSL it tests:** `reverse`/`href`/`useReverse` (see `/typesafety`, `/links`)
 
-The reverse/href/params/env types are a real contract: a wrong route name, a missing param, or an unknown env binding should be a COMPILE error, not a runtime surprise. The type-test recipes have no runtime API — `tsc --noEmit` IS the assertion. `assertGeneratedRoutesMatch` is the one runtime helper here: it runs the router's real matching to expand lazy includes, then diffs the live `routeMap` against the generated named-routes map you seed.
+The reverse/href/params/env types are a real contract: a wrong route name, a missing param, or an unknown env binding should be a COMPILE error, not a runtime surprise. The type-test recipes have no runtime API — `tsc --noEmit` IS the assertion. `assertGeneratedRoutesMatch` is the one runtime helper here: it runs the router's real matching to expand lazy includes, then diffs the live `routeMap` against the generated named-routes map you seed. It (and `diffGeneratedRoutes`) are **async — `await` them** — because expanding an async `include(prefix, () => import("./routes"))` group means importing that module first.
 
 ## API
 
@@ -13,7 +13,7 @@ The reverse/href/params/env types are a real contract: a wrong route name, a mis
 | `router`       | `{ routeMap; findMatch? }`           | Your router (real impl). `routeMap` is the live name→pattern map; `findMatch` (when present) is called to force-expand lazy `include()`d routes.           |
 | `generatedMap` | `Record<string, unknown>` (optional) | The imported `*.named-routes.gen.ts` map (name→pattern, or `{ path }` objects). Omit to diff against the global route map (`getGlobalRouteMap()`) instead. |
 
-### Context — `GeneratedRoutesDiff` (what `diffGeneratedRoutes` returns)
+### Context — `GeneratedRoutesDiff` (what `diffGeneratedRoutes` resolves to)
 
 | Field      | Type                           | Meaning                                                                                                                                     |
 | ---------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -24,7 +24,7 @@ The reverse/href/params/env types are a real contract: a wrong route name, a mis
 
 ### Returns — `assertGeneratedRoutesMatch`
 
-`void` on match. On drift, throws an `Error` listing every missing, extra, and mismatched route plus a "regenerate the `*.named-routes.gen.ts` file" hint. (`diffGeneratedRoutes` returns the `GeneratedRoutesDiff` above without throwing.)
+`Promise<void>` — **await it**. Resolves on match; on drift the promise REJECTS with an `Error` listing every missing, extra, and mismatched route plus a "regenerate the `*.named-routes.gen.ts` file" hint. (`diffGeneratedRoutes` resolves to the `GeneratedRoutesDiff` above and never rejects.) Both are async so an async `include(() => import())` group is imported and spliced into `routeMap` before the diff — call them without `await` and every route in that group reads as a false `missing`.
 
 ## Recipe
 
@@ -57,14 +57,15 @@ expectTypeOf<
 
 ```ts
 // 3. assertGeneratedRoutesMatch — a one-liner whole-app drift test. Real
-//    matching expands lazy include()d routes before the diff.
+//    matching expands lazy include()d routes before the diff. It is async
+//    (it awaits findMatch to import async include groups), so await it.
 import { it } from "vitest";
 import { assertGeneratedRoutesMatch } from "@rangojs/router/testing";
 import { router } from "../src/router";
 import generated from "../src/router.named-routes.gen";
 
-it("generated named-routes map is in sync with the router", () => {
-  assertGeneratedRoutesMatch(router, generated);
+it("generated named-routes map is in sync with the router", async () => {
+  await assertGeneratedRoutesMatch(router, generated);
 });
 ```
 
@@ -74,7 +75,7 @@ For a large type-only suite, collect recipe-1/2 assertions in `*.test-d.ts` file
 
 - Type tests run at TYPECHECK time (`tsc --noEmit`), NOT in the vitest runner. They are their own layer — wire them into CI as a real step (`pnpm run typecheck`). A type test nobody runs is just a comment.
 - `@ts-expect-error` ERRORS if the line below it ever starts compiling, so a regressed guard fails the typecheck. A runtime test cannot assert "this should not type-check".
-- `assertGeneratedRoutesMatch` force-expands lazy `include()`d routes (calls `findMatch` on a concrete path derived from each generated pattern) before diffing — otherwise every included route reads as a false `missing`. This makes the whole-app drift check work in a plain unit test. Routers without `findMatch` (a bare `{ routeMap }`) are left as-is.
+- `assertGeneratedRoutesMatch` force-expands lazy `include()`d routes (awaits `findMatch` on a concrete path derived from each generated pattern) before diffing — otherwise every included route reads as a false `missing`. It is **async** so it can await the module import behind an async `include(() => import())` group; `await` the call (or the async group's routes read as `missing`). This makes the whole-app drift check work in a plain unit test. Routers without `findMatch` (a bare `{ routeMap }`) are left as-is.
 - MULTI-APP route-map isolation. `href()`/`reverse()` typing is GLOBAL — each app's generated file augments the one `Rango.GeneratedRouteMap` interface. A `renderRoute` suite that imports a client component from app B (which calls `href("/b-route")`) won't typecheck if the same tsconfig program also carries app A's augmentation: A's route union rejects B's name. `renderRoute` is app-agnostic at RUNTIME; the collision is purely the global `href` typing. Keep a `renderRoute` suite single-app, or give each app its OWN tsconfig program (see `/typesafety`); a quick sidestep is to probe `useMount`/`useHref` inline instead of importing the cross-app component.
 
 ## See also

package/src/build/generate-manifest.ts

@@ -17,6 +17,11 @@ import type { TrailingSlashMode } from "../types.js";
 import { createRouteHelpers } from "../route-definition.js";
 import MapRootLayout from "../server/root-layout.js";
 import { collectFallbackClientRefs } from "./collect-fallback-refs.js";
+import {
+  isIncludeProvider,
+  resolveIncludeModule,
+  type IncludeProvider,
+} from "../urls/include-provider.js";
 
 /**
  * Node in the prefix tree
@@ -61,13 +66,32 @@ export interface GeneratedManifest {
 // Merge tracked nested includes into `target`. Multiple includes can share a
 // fullPrefix (e.g. include("/", a), include("/", b)) — concat their routes and
 // Object.assign children rather than overwrite.
-function mergeIncludeNodes(
+async function mergeIncludeNodes(
   target: Record<string, PrefixTreeNode>,
   includes: TrackedInclude[],
-  buildChild: (include: TrackedInclude) => PrefixTreeNode,
-): void {
+  buildChild: (include: TrackedInclude) => Promise<PrefixTreeNode>,
+): Promise<void> {
   for (const include of includes) {
-    const node = buildChild(include);
+    let node: PrefixTreeNode;
+    try {
+      node = await buildChild(include);
+    } catch (err) {
+      // Discovery (build-time, and the dev trie-rebuild) populates the
+      // manifest / trie / generated types for the WHOLE app. A failing async
+      // include provider here — a broken import, a module that throws at eval —
+      // must HARD-FAIL, not be swallowed: swallowing produces a green build with
+      // the entire route group silently absent from the manifest/trie/types, so
+      // CI passes, the deploy ships, and every one of that group's URLs then
+      // 404s/500s in production. On main an eager include that threw failed the
+      // build loudly; the async form must keep that contract. Rethrow with the
+      // offending prefix so the failure is actionable. (Sibling isolation
+      // belongs at PER-REQUEST runtime — see find-match.ts — not at discovery.)
+      throw new Error(
+        `[@rangojs/router] Failed to resolve include at prefix "${include.fullPrefix}" ` +
+          `during route discovery: ${(err as Error)?.message ?? String(err)}`,
+        { cause: err },
+      );
+    }
     const existing = target[include.fullPrefix];
     if (existing) {
       existing.routes.push(...node.routes);
@@ -78,10 +102,10 @@ function mergeIncludeNodes(
   }
 }
 
-function buildPrefixTreeNode(
+async function buildPrefixTreeNode(
   urlPrefix: string,
   namePrefix: string | undefined,
-  patterns: UrlPatterns<any>,
+  patternsOrProvider: UrlPatterns<any> | IncludeProvider<any>,
   routeManifest: Record<string, string>,
   routeAncestry: Record<string, string[]>, // internal: feeds trie building, not exported
   mountIndex: number,
@@ -92,7 +116,14 @@ function buildPrefixTreeNode(
   passthroughRoutes?: string[],
   responseTypeRoutes?: Record<string, string>,
   routeSearchSchemas?: Record<string, Record<string, string>>,
-): PrefixTreeNode {
+): Promise<PrefixTreeNode> {
+  // Resolve an async include provider (`() => import("./routes")`) so its routes
+  // are walked into the build-time manifest/types/href. Runtime matching still
+  // defers the import via lazy-includes; this only runs during build/dev
+  // discovery, which is async.
+  const patterns: UrlPatterns<any> = isIncludeProvider(patternsOrProvider)
+    ? resolveIncludeModule(await patternsOrProvider(), urlPrefix)
+    : patternsOrProvider;
   if (visited.has(patterns)) {
     console.warn(
       `[@rangojs/router] Circular include detected at prefix "${urlPrefix}". Skipping.`,
@@ -106,118 +137,117 @@ function buildPrefixTreeNode(
     };
   }
   visited.add(patterns);
-  // Create context for running patterns with include tracking
-  const manifest = new Map<string, EntryData>();
-  const patternsMap = new Map<string, string>();
-  const patternsByPrefix = new Map<string, Map<string, string>>();
-  const trailingSlashMap = new Map<string, TrailingSlashMode>();
-  const searchSchemasMap = new Map<string, Record<string, string>>();
-  const trackedIncludes: TrackedInclude[] = [];
+  try {
+    // Create context for running patterns with include tracking
+    const manifest = new Map<string, EntryData>();
+    const patternsMap = new Map<string, string>();
+    const patternsByPrefix = new Map<string, Map<string, string>>();
+    const trailingSlashMap = new Map<string, TrailingSlashMode>();
+    const searchSchemasMap = new Map<string, Record<string, string>>();
+    const trackedIncludes: TrackedInclude[] = [];
 
-  RangoContext.run(
-    {
-      manifest,
-      patterns: patternsMap,
-      patternsByPrefix,
-      trailingSlash: trailingSlashMap,
-      searchSchemas: searchSchemasMap,
-      namespace: "build",
-      parent: null,
-      counters: {},
-      mountIndex,
-      trackedIncludes, // Enable nested include tracking
-    },
-    () => {
-      const helpers = createRouteHelpers();
-      // Wrap in root layout for correct parent hierarchy (matches runtime)
-      helpers.layout(MapRootLayout, () => {
-        if (urlPrefix || namePrefix) {
-          return runWithPrefixes(urlPrefix, namePrefix, () => {
-            return patterns.handler() as AllUseItems[];
-          });
-        }
-        return patterns.handler() as AllUseItems[];
-      });
-    },
-  );
+    RangoContext.run(
+      {
+        manifest,
+        patterns: patternsMap,
+        patternsByPrefix,
+        trailingSlash: trailingSlashMap,
+        searchSchemas: searchSchemasMap,
+        namespace: "build",
+        parent: null,
+        counters: {},
+        mountIndex,
+        trackedIncludes, // Enable nested include tracking
+      },
+      () => {
+        const helpers = createRouteHelpers();
+        // Wrap in root layout for correct parent hierarchy (matches runtime)
+        helpers.layout(MapRootLayout, () => {
+          if (urlPrefix || namePrefix) {
+            return runWithPrefixes(urlPrefix, namePrefix, () => {
+              return patterns.handler() as AllUseItems[];
+            });
+          }
+          return patterns.handler() as AllUseItems[];
+        });
+      },
+    );
 
-  // Collect route names defined in this include (routes have prefixes applied)
-  const routes: string[] = [];
-  for (const [name, pattern] of patternsMap.entries()) {
-    routes.push(name);
-    routeManifest[name] = pattern;
-  }
+    // Collect route names defined in this include (routes have prefixes applied)
+    const routes = [...patternsMap.keys()];
+    Object.assign(routeManifest, Object.fromEntries(patternsMap));
 
-  // Collect trailing slash config
-  if (routeTrailingSlash) {
-    for (const [name, mode] of trailingSlashMap.entries()) {
-      routeTrailingSlash[name] = mode;
+    // Collect trailing slash config
+    if (routeTrailingSlash) {
+      for (const [name, mode] of trailingSlashMap.entries()) {
+        routeTrailingSlash[name] = mode;
+      }
     }
-  }
-  if (routeSearchSchemas) {
-    for (const [name, schema] of searchSchemasMap.entries()) {
-      routeSearchSchemas[name] = schema;
+    if (routeSearchSchemas) {
+      for (const [name, schema] of searchSchemasMap.entries()) {
+        routeSearchSchemas[name] = schema;
+      }
     }
-  }
 
-  // Capture ancestry from manifest entries' parent chains
-  captureAncestry(manifest, routeAncestry);
+    // Capture ancestry from manifest entries' parent chains
+    captureAncestry(manifest, routeAncestry);
 
-  // Collect prerender route names and handler definitions from manifest entries
-  if (prerenderRoutes) {
-    for (const [name, entry] of manifest) {
-      if (entry.type === "route" && entry.isPrerender) {
-        prerenderRoutes.push(name);
-        if (prerenderDefs && entry.prerenderDef) {
-          prerenderDefs[name] = entry.prerenderDef;
-        }
-        if (passthroughRoutes && entry.isPassthrough === true) {
-          passthroughRoutes.push(name);
+    // Collect prerender route names and handler definitions from manifest entries
+    if (prerenderRoutes) {
+      for (const [name, entry] of manifest) {
+        if (entry.type === "route" && entry.isPrerender) {
+          prerenderRoutes.push(name);
+          if (prerenderDefs && entry.prerenderDef) {
+            prerenderDefs[name] = entry.prerenderDef;
+          }
+          if (passthroughRoutes && entry.isPassthrough === true) {
+            passthroughRoutes.push(name);
+          }
         }
       }
     }
-  }
 
-  // Collect response type routes from manifest entries
-  if (responseTypeRoutes) {
-    for (const [name, entry] of manifest) {
-      if (entry.type === "route" && entry.responseType) {
-        responseTypeRoutes[name] = entry.responseType;
+    // Collect response type routes from manifest entries
+    if (responseTypeRoutes) {
+      for (const [name, entry] of manifest) {
+        if (entry.type === "route" && entry.responseType) {
+          responseTypeRoutes[name] = entry.responseType;
+        }
       }
     }
-  }
-
-  const children: Record<string, PrefixTreeNode> = {};
-  mergeIncludeNodes(children, trackedIncludes, (include) =>
-    buildPrefixTreeNode(
-      include.fullPrefix,
-      include.namePrefix,
-      include.patterns as UrlPatterns<any>,
-      routeManifest,
-      routeAncestry,
-      mountIndex,
-      visited,
-      routeTrailingSlash,
-      prerenderRoutes,
-      prerenderDefs,
-      passthroughRoutes,
-      responseTypeRoutes,
-      routeSearchSchemas,
-    ),
-  );
 
-  // Remove from visited so sibling branches can reuse the same patterns
-  // without false circular-include detection. Only ancestors in the current
-  // recursion path should trigger the cycle guard.
-  visited.delete(patterns);
+    const children: Record<string, PrefixTreeNode> = {};
+    await mergeIncludeNodes(children, trackedIncludes, (include) =>
+      buildPrefixTreeNode(
+        include.fullPrefix,
+        include.namePrefix,
+        include.patterns as UrlPatterns<any> | IncludeProvider<any>,
+        routeManifest,
+        routeAncestry,
+        mountIndex,
+        visited,
+        routeTrailingSlash,
+        prerenderRoutes,
+        prerenderDefs,
+        passthroughRoutes,
+        responseTypeRoutes,
+        routeSearchSchemas,
+      ),
+    );
 
-  return {
-    staticPrefix: extractStaticPrefix(urlPrefix),
-    fullPrefix: urlPrefix,
-    namePrefix: namePrefix || undefined,
-    children,
-    routes,
-  };
+    return {
+      staticPrefix: extractStaticPrefix(urlPrefix),
+      fullPrefix: urlPrefix,
+      namePrefix: namePrefix || undefined,
+      children,
+      routes,
+    };
+  } finally {
+    // Remove from visited so sibling branches can reuse the same patterns without
+    // false circular-include detection — and so a throwing handler (caught by the
+    // parent mergeIncludeNodes) does not leak this entry into the shared set.
+    visited.delete(patterns);
+  }
 }
 
 /**
@@ -261,7 +291,8 @@ export interface FullManifest extends GeneratedManifest {
  * import { generateManifest } from "@rangojs/router/build";
  * import { urlpatterns } from "./urls";
  *
- * const manifest = generateManifest(urlpatterns);
+ * // Async: awaits async include() providers (`() => import("./routes")`).
+ * const manifest = await generateManifest(urlpatterns);
  * // Write to file for runtime use
  * fs.writeFileSync(
  *   "src/generated/route-manifest.json",
@@ -269,15 +300,12 @@ export interface FullManifest extends GeneratedManifest {
  * );
  * ```
  */
-export function generateManifest<TEnv>(
+export async function generateManifest<TEnv>(
   urlpatterns: UrlPatterns<TEnv, any>,
   mountIndex: number = 0,
-): GeneratedManifest {
-  const {
-    _routeAncestry: _,
-    _prerenderDefs: __,
-    ...publicManifest
-  } = generateManifestFull(urlpatterns, mountIndex);
+): Promise<GeneratedManifest> {
+  const { _routeAncestry, _prerenderDefs, ...publicManifest } =
+    await generateManifestFull(urlpatterns, mountIndex);
   return publicManifest;
 }
 
@@ -288,7 +316,7 @@ export function generateManifest<TEnv>(
  * @rangojs/router/build), manifest-init (direct import), and trie
  * building. Not intended for external use.
  */
-export function generateManifestFull<TEnv>(
+export async function generateManifestFull<TEnv>(
   urlpatterns: UrlPatterns<TEnv, any>,
   mountIndex: number = 0,
   options?: {
@@ -302,7 +330,7 @@ export function generateManifestFull<TEnv>(
      */
     collectClientFallbackRef?: (refKey: string) => void;
   },
-): FullManifest {
+): Promise<FullManifest> {
   const routeManifest: Record<string, string> = {};
   const routeAncestry: Record<string, string[]> = {};
   const prefixTree: Record<string, PrefixTreeNode> = {};
@@ -356,17 +384,13 @@ export function generateManifestFull<TEnv>(
   }
 
   // Collect root-level routes and trailing slash config
-  const routeTrailingSlash: Record<string, string> = {};
-  for (const [name, pattern] of patternsMap.entries()) {
-    routeManifest[name] = pattern;
-  }
-  for (const [name, mode] of trailingSlashMap.entries()) {
-    routeTrailingSlash[name] = mode;
-  }
-  const routeSearchSchemas: Record<string, Record<string, string>> = {};
-  for (const [name, schema] of searchSchemasMap.entries()) {
-    routeSearchSchemas[name] = schema;
-  }
+  Object.assign(routeManifest, Object.fromEntries(patternsMap));
+  const routeTrailingSlash: Record<string, string> =
+    Object.fromEntries(trailingSlashMap);
+  const routeSearchSchemas: Record<
+    string,
+    Record<string, string>
+  > = Object.fromEntries(searchSchemasMap);
 
   // Capture ancestry from manifest entries' parent chains
   captureAncestry(manifest, routeAncestry);
@@ -393,11 +417,11 @@ export function generateManifestFull<TEnv>(
 
   // Shared visited set for cycle detection across all root-level includes.
   const visited = new Set<unknown>();
-  mergeIncludeNodes(prefixTree, trackedIncludes, (include) =>
+  await mergeIncludeNodes(prefixTree, trackedIncludes, (include) =>
     buildPrefixTreeNode(
       include.fullPrefix,
       include.namePrefix,
-      include.patterns as UrlPatterns<any>,
+      include.patterns as UrlPatterns<any> | IncludeProvider<any>,
       routeManifest,
       routeAncestry,
       mountIndex,
@@ -441,14 +465,14 @@ export function generateManifestFull<TEnv>(
  *
  * @example
  * ```typescript
- * const code = generateManifestCode(urlpatterns);
+ * const code = await generateManifestCode(urlpatterns);
  * fs.writeFileSync("src/generated/route-manifest.ts", code);
  * ```
  */
-export function generateManifestCode<TEnv>(
+export async function generateManifestCode<TEnv>(
   urlpatterns: UrlPatterns<TEnv, any>,
-): string {
-  const manifest = generateManifest(urlpatterns);
+): Promise<string> {
+  const manifest = await generateManifest(urlpatterns);
 
   return `/**
  * Auto-generated route manifest