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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.0.0-experimental.136",
+  "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/breadcrumbs/SKILL.md

@@ -90,7 +90,9 @@ a deep async component, not the handler — call `.defer()` on the push function
 slot synchronously and returns a **resolver that is push-equal** — you call it
 later, anywhere in the render, with the same argument you'd have passed to the
 push (a value, a `Promise`, or a thunk). The only added behavior is a timeout, so a
-forgotten resolve can't hold the Flight stream (and the HTTP response) open forever.
+forgotten resolve can't hang the render (and the HTTP response): resolve-by-default
+awaits the reserved slot before any consumer reads it, and the timeout guarantees it
+settles to `else` instead of blocking forever.
 
 Reserve the slot in the handler, then resolve it from a nested async component
 that closes over the resolver — no extra wiring (the resolver is a plain closure,
@@ -131,15 +133,17 @@ hung request. `timeoutMs: 0` or `Infinity` disable the timeout intentionally; an
 other non-finite or negative value falls back to the default rather than silently
 disabling the safety net.
 
-**Consumer note:** because `.defer()` reserves the slot for the WHOLE item, a
-client reading the handle (`useHandle(Breadcrumbs)`) sees that entry as a
-`Promise` until it resolves. Type such reads with the exported
-`DeferredHandleEntry<BreadcrumbItem>` (from `@rangojs/router/client`); a
-deferred-aware consumer should `use()` thenable entries inside `<Suspense>`, while
-a simple one can skip them (`typeof entry.then === "function"`). Use `.defer()`
-only when even `label`/`href` are unknown at handler time — if you know them and
-only the `content` is async, push a concrete item with a `Promise` `content` field
-instead (no `.defer()` needed).
+**Consumer note (resolve-by-default):** a deferred crumb is RESOLVED before any
+consumer sees it — `useHandle(Breadcrumbs)` returns the resolved item, never a
+`Promise`, so you read it like any sync crumb (no `use()`, no thenable narrowing).
+On a full/SSR load the value is resolved server-side; on a soft navigation the
+breadcrumbs HOLD the previous resolved value until the deferred value lands, then
+swap in — no blank, no pending entry. If the slot times out to `else: null`/
+undefined, the entry is simply dropped. Use `.defer()` only when even
+`label`/`href` are unknown at handler time — if you know them and only the
+`content` is async, push a concrete item with a `Promise` `content` field instead
+(the `content` field is a nested promise you resolve with `use()` in your
+component; no `.defer()` needed).
 
 ## Consuming Breadcrumbs (Client)
 
@@ -274,15 +278,28 @@ Create your own handle with `createHandle()`:
 ```typescript
 import { createHandle } from "@rangojs/router";
 
-// Default: flatten into array
+// Custom collect: last value wins.
 export const PageTitle = createHandle<string, string>(
   (segments) => segments.flat().at(-1) ?? "Default Title",
 );
 
-// No collect function: default flattens into T[]
+// No collect: the DEFAULT is the identity (lossless) — `collect` receives the
+// per-segment data (TData[][], one array per segment that pushed, in segment
+// order) and passes it through as-is. `useHandle(Warnings)` is `string[][]`, so a
+// consumer can tell which/how-many segments contributed.
 export const Warnings = createHandle<string>();
+
+// Want a single flat list instead? Opt in:
+export const FlatWarnings = createHandle<string, string[]>((segments) =>
+  segments.flat(),
+);
 ```
 
+A handle whose module is never imported (so `createHandle()` never ran to register
+its collect) falls back to this same identity default and **warns in dev** — a
+handle with a custom collect that failed to register would otherwise return the
+wrong shape silently, and the runtime can't tell it from one that wanted the default.
+
 The Vite `exposeInternalIds` plugin auto-injects a stable `$$id` based on
 file path and export name. No manual naming required for project-local code.
 

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/handles.md

@@ -13,7 +13,7 @@ A handle's `collect`/accumulator (the `createHandle(collect)` argument that maps
 | `handle`   | `Handle<TData, TAccumulated>`         | The handle whose registered collect to run.                                                                                                                                                                                                          |
 | `segments` | `ReadonlyArray<ReadonlyArray<TData>>` | Per-segment pushed values, one inner array per route segment, in **parent -> child** order. Empty inner arrays are filtered before the collect runs (matching production `collectHandleData` — a segment that pushed nothing is not passed through). |
 
-**Returns** `TAccumulated` — exactly what the handle's collect produces (a default-flatten array, or a custom accumulator's value). If the handle's module was never imported (collect unregistered), it warns and falls back to `segments.flat()`.
+**Returns** `TAccumulated` — exactly what the handle's collect produces (the default identity collect's per-segment `TData[][]`, or a custom accumulator's value). If the handle's module was never imported (collect unregistered), it falls back to that same identity default and **warns** — a handle with a custom collect that failed to register would otherwise return the wrong shape silently.
 
 ### runLoader option — `handles` — `src/testing/run-loader.ts`
 
@@ -40,7 +40,9 @@ import { describe, it, expect } from "vitest";
 import { collectHandle } from "@rangojs/router/testing";
 import { createHandle } from "@rangojs/router";
 
-const Breadcrumbs = createHandle<{ label: string; href: string }>(); // default flatten
+// Opt into a flat list; the default collect groups per segment (TData[][]).
+type Crumb = { label: string; href: string };
+const Breadcrumbs = createHandle<Crumb, Crumb[]>((segments) => segments.flat());
 
 it("flattens per-segment crumbs in parent->child order", () => {
   const home = { label: "Home", href: "/" };

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/browser/event-controller.ts

@@ -249,6 +249,14 @@ export interface EventController {
     resolvedIds?: string[],
   ): void;
   getHandleState(): HandleState;
+  /**
+   * Update ONLY `routeSegmentIds` (what `useSegments` reads) from `matched`,
+   * leaving `data` and `segmentOrder` (what `useHandle` collects over) untouched.
+   * Used while a deferred handle is resolving: the route has changed (so
+   * `useSegments` must reflect the new segment ids) but `useHandle` still holds
+   * its previous value until the deferred snapshot is applied.
+   */
+  setRouteSegmentIds(matched: string[]): void;
 
   // Params operations
   setParams(params: Record<string, string>): void;
@@ -860,6 +868,18 @@ export function createEventController(
     };
   }
 
+  function setRouteSegmentIds(matched: string[]): void {
+    const next = filterRouteSegmentIds(matched);
+    if (
+      next.length === routeSegmentIds.length &&
+      next.every((id, i) => id === routeSegmentIds[i])
+    ) {
+      return;
+    }
+    routeSegmentIds = next;
+    notifyHandles();
+  }
+
   // ========================================================================
   // Subscriptions
   // ========================================================================
@@ -928,6 +948,7 @@ export function createEventController(
     // Handles
     setHandleData,
     getHandleState,
+    setRouteSegmentIds,
 
     // Params
     setParams,