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

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/host-router/SKILL.md

@@ -33,6 +33,48 @@ export default {
 };
 ```
 
+## Deploying: Cloudflare vs node/vercel
+
+How a host router is _served_ depends on the preset, because the preset decides who owns the server entry.
+
+| Preset            | Who owns the entry          | What the host module exports                                                                                |
+| ----------------- | --------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `cloudflare`      | You (your `worker.rsc.tsx`) | `export default { fetch(request, env, ctx) { return router.match(request, { env, ctx }); } }`               |
+| `node` / `vercel` | rango (generated RSC entry) | `export default router;` (the `HostRouter` instance itself), or a named `export const hostRouter`/`router`. |
+
+On `node`/`vercel`, rango generates the served RSC entry, so it needs the `HostRouter` **instance** to call `hostRouter.match()` for you. Export the instance, not a `{ fetch }` object:
+
+```typescript
+// src/worker.rsc.tsx  (node / vercel)
+import { createHostRouter } from "@rangojs/router/host";
+
+export const hostRouter = createHostRouter();
+hostRouter.host(["admin.*"]).lazy(() => import("./apps/admin/handler.js"));
+hostRouter.host(["."]).lazy(() => import("./apps/site/handler.js"));
+
+// Export the instance — the generated entry serves it via hostRouter.match().
+export default hostRouter;
+```
+
+Each sub-app exports a handler exactly as on Cloudflare (no change):
+
+```typescript
+// src/apps/admin/handler.ts
+import { router } from "./router.js";
+export default (request: Request, input: any) => router.fetch(request, input);
+```
+
+Selecting the host entry — a host app has several `createRouter()` sub-apps, so single-router auto-discovery can't pick one. Either let rango auto-detect the lone `createHostRouter()` file, or point at it explicitly:
+
+```typescript
+// vite.config.ts
+rango({ preset: "vercel", hostRouter: "./src/worker.rsc.tsx" });
+```
+
+On Vercel this is a single function running `hostRouter.match()` for every request (mirrors the Cloudflare single-worker model); `{ env, ctx }` (`process.env` + `{ waitUntil }`) is threaded unchanged to each matched sub-app's handler and `cache(env, ctx)` factory. See the `vercel` skill.
+
+Unmatched hosts on node/vercel: because rango owns the generated entry (you have no worker `try/catch`), it catches `NoRouteMatchError` and returns **404** by default — so you do **not** need a catch-all host route. If you want different behavior (a branded 404, a redirect, a default app), register a catch-all mount as the **last** route, e.g. `host(["**"]).lazy(() => import("./apps/site/handler.js"))` — it matches any host, so the built-in 404 only fires when nothing matched at all. (Note `fallback()` is for cookie-override errors, not general unmatched hosts.)
+
 ## Inline handlers (`.map`) vs lazy mounts (`.lazy`)
 
 A host pattern maps to one of two things, and you pick the method by intent:
@@ -134,17 +176,17 @@ router.fallback().map((request) => {
 });
 ```
 
-For unmatched hosts without `hostOverride`, catch `NoRouteMatchError` in your worker fetch:
+For unmatched hosts without `hostOverride`, catch `NoRouteMatchError` in your worker fetch. Use the `isNoRouteMatchError()` guard rather than a bare `instanceof`: a workspace with a duplicated `@rangojs/router` copy can throw the error with a different class identity, and `instanceof` would then turn the 404 into an opaque 500.
 
 ```typescript
-import { NoRouteMatchError } from "@rangojs/router/host";
+import { isNoRouteMatchError } from "@rangojs/router/host";
 
 export default {
   async fetch(request: Request, env: Env, ctx: ExecutionContext) {
     try {
       return await router.match(request, { env, ctx });
     } catch (err) {
-      if (err instanceof NoRouteMatchError) {
+      if (isNoRouteMatchError(err)) {
         return new Response("Not Found", { status: 404 });
       }
       throw err;

package/skills/layout/SKILL.md

@@ -147,12 +147,21 @@ A layout as a child of `path()` wraps the route content and can read
 data set by the route handler via `ctx.get()`. The handler always
 executes before its children.
 
-This handler-first guarantee applies to a single full render pass
-(initial render, prerender, or full HTML re-render). During partial
-action revalidation, only the segments that revalidate are recomputed.
-If an orphan layout depends on data established by an outer handler or
-layout, that outer segment must also revalidate, or the orphan must
-guard/reload the data independently.
+This is the recommended way to pass handler data downward, and it is
+safe under partial action revalidation with zero configuration: orphan
+layouts (and their parallels) belong to the route entry, and on an
+action the whole entry re-runs together by default — route segment,
+loaders, and `belongsToRoute` children all seed revalidate-true, with
+handler-first ordering preserved. Producer and consumer cannot desync
+unless you narrow one side with a predicate that returns a hard `false`
+(then put the same contract on both — see "Revalidation Contracts").
+
+Data from an **outer** handler or layout entry is the opposite case:
+outer entries do not revalidate on actions by default (parent-chain
+skip). If an orphan layout depends on data established above its own
+route entry, that outer segment must share a revalidation contract, or
+the orphan must guard/reload the data independently. See `/rango` →
+"Passing data down the tree" for the full safest-first ladder.
 
 ```typescript
 import { Outlet, ParallelOutlet } from "@rangojs/router/client";
@@ -191,7 +200,10 @@ orphan layouts to read them.
 
 ## Layout Revalidation
 
-Layouts don't revalidate by default. Control with `revalidate()`:
+Standalone `layout()` entries don't revalidate by default — on an action,
+parent-chain segments are skipped unless a `revalidate()` opts them in.
+(Orphan layouts inside a `path()` are the opposite: they ride along with
+the route entry by default.) Control with `revalidate()`:
 
 ```typescript
 layout(<ShopLayout />, () => [
@@ -218,8 +230,13 @@ their `ctx.set()` state.
 
 ### Revalidation Contracts
 
-For shared upstream data, define named revalidation functions and reuse
-them on both producer and consumer segments:
+Contracts are the tool for cross-entry sharing — the bottom rung of the
+data-passing ladder (`/rango` → "Passing data down the tree"). Before
+writing one, check whether the producer can move down a rung: into the
+consumer's own entry as an orphan layout, into middleware, or into a
+loader. When the data genuinely must flow from an outer entry, define
+named revalidation functions and reuse them on both producer and
+consumer segments:
 
 ```typescript
 // revalidation-contracts.ts

package/skills/middleware/SKILL.md

@@ -60,8 +60,12 @@ data itself.
 ### Revalidation Contracts with Middleware-Backed Trees
 
 Middleware can establish request-level context (`ctx.set`) for segments that
-execute in the current render pass. It does not change partial revalidation
-boundaries between handler/layout/parallel segments.
+execute in the current render pass. Because route middleware wraps **every**
+render pass — normal renders, post-action revalidation, PE re-renders — its
+variables are never stale: middleware is the safest `ctx.set` rung on the
+data-passing ladder (`/rango` → "Passing data down the tree"). But it does
+not change partial revalidation boundaries between handler/layout/parallel
+segments.
 
 For shared segment data, use named revalidation contracts on both the producer
 and consumer segments, even when middleware is present in the chain.

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/observability/SKILL.md

@@ -112,7 +112,29 @@ const router = createRouter({
 });
 ```
 
-Both factories return a `RouterTracingConfig` for the same `tracing` slot;
+On **Vercel Functions** (Node runtime), use `createVercelTracing` — a thin
+wrapper over `createOTelTracing` that reads the global OTel tracer
+`@vercel/otel`'s `registerOTel()` installs, so you do not call `trace.getTracer`
+yourself. Custom spans are Node-only (unsupported on the Edge runtime):
+
+```typescript
+// instrumentation.ts — install the provider, then export the tracing config.
+// Importing this module is what runs registerOTel() — a Rango/Vite app does not
+// auto-load instrumentation.ts like Next.js, so a standalone registerOTel() that
+// nothing imports is a silent no-op.
+import { registerOTel } from "@vercel/otel";
+import { createVercelTracing } from "@rangojs/router/vercel";
+registerOTel({ serviceName: "my-app" });
+export const tracing = createVercelTracing(); // { enabled, spans, tracerName, tracer }
+
+// router.tsx — importing `tracing` runs instrumentation.ts
+import { createRouter } from "@rangojs/router";
+import { tracing } from "./instrumentation.js";
+
+const router = createRouter({ document: Document, urls: urlpatterns, tracing });
+```
+
+These factories return a `RouterTracingConfig` for the same `tracing` slot;
 `telemetry` stays independent (events only, no phase spans). Phase spans:
 `rango.request`, `rango.middleware`, `rango.action`, `rango.loader`,
 `rango.render`, `rango.ssr` — the same phases the `debugPerformance` timeline

package/skills/parallel/SKILL.md

@@ -344,9 +344,17 @@ parallel(
 )
 ```
 
-Revalidating only the parallel does not re-run outer handlers/layouts.
-If the slot reads `ctx.get()` data established above it, opt the outer
-segment into revalidation as well.
+Where the slot sits decides its action default. A parallel under a
+`path()` (or one of its orphan layouts) belongs to the route entry and
+revalidates together with it on every action — handler-set data stays
+consistent with no configuration. A parallel under a standalone
+`layout()` entry follows the parent-chain default instead: skipped on
+actions unless a `revalidate()` opts it in.
+
+In either position, revalidating only the parallel does not re-run outer
+handlers/layouts. If the slot reads `ctx.get()` data established above
+it, opt the outer segment into revalidation as well (see `/rango` →
+"Passing data down the tree").
 
 A `revalidate()` callback may return a hard `boolean`, a soft
 `{ defaultShouldRevalidate }` object, or nothing (`void` / `null` /

package/skills/rango/SKILL.md

@@ -59,22 +59,57 @@ appears, not up front.
 To decide where something can live: **does it define a URL? structure, stays in
 `urls()`. Does it modify a node? config, compose freely.**
 
+## Passing data down the tree
+
+Four ways to get per-request data to a segment below you, ordered safest-first.
+Reach for the next rung only when the one above doesn't fit — the higher rungs
+are immune to partial-revalidation staleness by construction.
+
+1. **A loader** (`loader()` + `useLoader()`). Loaders resolve fresh on every
+   pass — full renders, action revalidations, cache hits. Nothing to keep in
+   sync. If the data can be a loader, make it a loader.
+2. **Middleware `ctx.set()`**. Route middleware wraps every render pass,
+   including post-action revalidation and PE re-renders, so its variables are
+   never stale. Right for request-shaped context: auth, session, locale.
+3. **Handler `ctx.set()` to its own children** —
+   `path(handler, ..., () => [layout(...)])`. Orphan layouts and their
+   parallels belong to the route entry: on an action the whole entry re-runs
+   together by default (handler-first preserved), so the data stays consistent
+   with zero configuration. Right for data the page must compute anyway —
+   e.g. pagination, where the handler's search decides how many pages the
+   layout chrome renders. One rule: if you narrow the entry's revalidation
+   with a predicate that can return a hard `false`, put the same contract on
+   the entry's children too — a hard `false` on one side of a
+   producer/consumer pair desyncs it.
+4. **Cross-entry sharing** — an outer `layout()` entry feeding descendants.
+   Outer entries do NOT revalidate on actions by default (the revalidation
+   trace calls this `action:parent-chain-skip`), so this rung always requires
+   a shared revalidation contract: the same named `revalidate()` function on
+   the producer and every consumer. See `/layout` → "Revalidation Contracts".
+   Before writing one, check whether the producer can move down a rung.
+
+The failure mode this ladder prevents: a consumer re-runs, its producer
+doesn't, `ctx.get()` reads `undefined`, and fallback UI silently replaces good
+UI after an action. Rungs 1–3 make that unrepresentable; rung 4 makes it a
+stated, greppable contract.
+
 ## Pick a primitive
 
-| I need to…                            | Use                              | Skill                   |
-| ------------------------------------- | -------------------------------- | ----------------------- |
-| render data fresh every request       | `loader()` + `useLoader()`       | /loader                 |
-| cache a rendered subtree              | `cache()` on a segment           | /caching                |
-| cache one function/component's result | `"use cache"`                    | /use-cache              |
-| cache a loader's data                 | `loader(L, () => [cache()])`     | /loader, /caching       |
-| re-render a segment after an action   | `revalidate()`                   | /loader                 |
-| mutate                                | `"use server"` action            | /server-actions         |
-| debug a slow request                  | `debugPerformance` / telemetry   | /observability          |
-| share config across routes            | factory returning a helper array | /composability          |
-| compose a sub-app / module            | `include()`                      | /route                  |
-| modal / soft navigation               | `intercept()`                    | /intercept              |
-| pre-render a route at build time      | `Prerender(...)` wrapper         | /prerender              |
-| stream SSE / upgrade a WebSocket      | `path.stream()` / `path.any()`   | /streams-and-websockets |
+| I need to…                            | Use                                | Skill                   |
+| ------------------------------------- | ---------------------------------- | ----------------------- |
+| render data fresh every request       | `loader()` + `useLoader()`         | /loader                 |
+| cache a rendered subtree              | `cache()` on a segment             | /caching                |
+| cache one function/component's result | `"use cache"`                      | /use-cache              |
+| cache a loader's data                 | `loader(L, () => [cache()])`       | /loader, /caching       |
+| re-render a segment after an action   | `revalidate()`                     | /loader                 |
+| mutate                                | `"use server"` action              | /server-actions         |
+| debug a slow request                  | `debugPerformance` / telemetry     | /observability          |
+| share config across routes            | factory returning a helper array   | /composability          |
+| compose a sub-app / module            | `include()`                        | /route                  |
+| modal / soft navigation               | `intercept()`                      | /intercept              |
+| pre-render a route at build time      | `Prerender(...)` wrapper           | /prerender              |
+| feed live loaders from a cached shell | replayed handle + `ctx.rendered()` | /shell-manifest         |
+| stream SSE / upgrade a WebSocket      | `path.stream()` / `path.any()`     | /streams-and-websockets |
 
 ## Invariants
 
@@ -185,6 +220,12 @@ resolve `dist/` outside `./vite`, and it may lag `src/`.
 
 Grouped by concern — read when you need to…
 
+**Positioning & evaluation**:
+
+| Skill         | Description                                                  |
+| ------------- | ------------------------------------------------------------ |
+| `/comparison` | Compare Rango with Next.js, TanStack Start, and Waku fairly. |
+
 **Structure & routing** — shape URLs, layouts, navigation, and request processing:
 
 | Skill                     | Description                                                                |
@@ -206,15 +247,16 @@ Grouped by concern — read when you need to…
 
 **Data & caching** — fetch, mutate, and cache:
 
-| Skill             | Description                                                             |
-| ----------------- | ----------------------------------------------------------------------- |
-| `/loader`         | Data loaders with `createLoader()` and `revalidate()`                   |
-| `/server-actions` | Mutations with `"use server"`, useActionState, validation, revalidation |
-| `/caching`        | Segment caching with memory or KV stores                                |
-| `/use-cache`      | Function-level caching with `"use cache"` directive                     |
-| `/cache-guide`    | When to use `cache()` vs `"use cache"` — differences and decision guide |
-| `/document-cache` | Edge caching with Cache-Control headers                                 |
-| `/prerender`      | Pre-render route segments at build time (Passthrough live fallback)     |
+| Skill             | Description                                                                                |
+| ----------------- | ------------------------------------------------------------------------------------------ |
+| `/loader`         | Data loaders with `createLoader()` and `revalidate()`                                      |
+| `/server-actions` | Mutations with `"use server"`, useActionState, validation, revalidation                    |
+| `/caching`        | Segment caching with memory or KV stores                                                   |
+| `/use-cache`      | Function-level caching with `"use cache"` directive                                        |
+| `/cache-guide`    | When to use `cache()` vs `"use cache"` — differences and decision guide                    |
+| `/document-cache` | Edge caching with Cache-Control headers                                                    |
+| `/prerender`      | Pre-render route segments at build time (Passthrough live fallback)                        |
+| `/shell-manifest` | Replayed handles as cache metadata read by live loaders (frozen shell, batched live holes) |
 
 **Client & presentation** — build the client-side UX:
 
@@ -239,6 +281,12 @@ Grouped by concern — read when you need to…
 | `/bundle-analysis` | Audit your app's production bundle for server leaks and oversized chunks |
 | `/debug-manifest`  | Inspect route manifest structure                                         |
 
+**Deployment**:
+
+| Skill     | Description                                                                               |
+| --------- | ----------------------------------------------------------------------------------------- |
+| `/vercel` | Deploy to Vercel Functions (`preset: "vercel"`), Runtime Cache, and `createVercelTracing` |
+
 **Testing**:
 
 | Skill      | Description                                                                                                                     |
@@ -319,7 +367,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/route/SKILL.md

@@ -154,6 +154,13 @@ first. Use `ctx.set(key, value)` to share data with children, who read it
 via `ctx.get(key)`. Caching wraps all segments together, so either all run
 or none do.
 
+This pattern is also safe under partial action revalidation: on an action,
+the route entry re-runs as a unit by default — route segment, loaders, and
+`belongsToRoute` children (orphan layouts, entry parallels) all seed
+revalidate-true, with handler-first ordering preserved. Handler-set data
+stays consistent with no configuration. See `/rango` → "Passing data down
+the tree" for the safest-first ladder.
+
 ### Typed context variables with createVar
 
 Use `createVar<T>()` to create a typed token for `ctx.set()`/`ctx.get()`.
@@ -240,9 +247,18 @@ Cacheable vars (the default) can be read freely inside cache scopes.
 > decides hit/miss/ttl/swr independently and never reads `revalidate()`. See
 > `/cache-guide` → "Two axes" and `/rango` → "The shape of rango".
 
-Handler-first guarantees apply within a single full render pass. For partial
-action revalidation, define named revalidation contracts and reuse them on both
-the producer route and the consumer child segments.
+With no `revalidate()` configured, an entry needs no contract: on an action
+the route handler and its children re-run together by default, so handler
+data stays consistent on its own. Contracts matter in two cases:
+
+1. **You narrow the entry's revalidation** with a predicate that can return a
+   hard `false` (e.g. bare `ctx.isAction(X)`). A hard `false` on one side of a
+   producer/consumer pair desyncs it — the child re-runs by default and reads
+   `undefined`, or vice versa. Put the same named contract on the route and
+   its dependent children so they narrow together.
+2. **The producer is an outer entry** (a standalone `layout()` above this
+   route). Outer entries skip action revalidation by default, so the shared
+   contract is mandatory — see `/layout` → "Revalidation Contracts".
 
 ```typescript
 // revalidation-contracts.ts

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
@@ -493,6 +505,7 @@ const router = createRouter({
 ```typescript
 // On Cloudflare Workers, swap the tracing factory for native custom spans
 // (no @opentelemetry/api dependency); the telemetry slot is unchanged.
+// On Vercel (Node runtime) use createVercelTracing() from @rangojs/router/vercel.
 import { createCloudflareTracing } from "@rangojs/router/cloudflare";
 
 const router = createRouter({