@rangojs/router 0.16.0 → 0.18.0

package/skills/comparison/references/framework-comparison.md

@@ -44,10 +44,10 @@ and multi-region composition without replacing its routing or data model.
 
 | Dimension               | **Rango**                                                                                                  | Next.js (App Router)                                                           | TanStack Start                                                                     | Waku                                                                    |
 | ----------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
-| Routing model           | Code DSL (`urls()`/`include()`), named + `reverse()`                                                       | File-system convention                                                         | File or code, type-first                                                           | File-system (+ `createPages`)                                           |
+| Routing model           | Code DSL (`urls()`/`include()`), named + `ctx.reverse()`                                                   | File-system convention                                                         | File or code, type-first                                                           | File-system (+ `createPages`)                                           |
 | Foundation              | Vite + plugin-rsc                                                                                          | Turbopack (default in 16; Webpack opt-in)                                      | [Vite or Rsbuild](https://tanstack.com/start/latest/docs/framework/react/overview) | Vite + plugin-rsc                                                       |
 | RSC model               | RSC-first                                                                                                  | RSC-first                                                                      | SSR/client-first; RSC opt-in (experimental)                                        | RSC-first                                                               |
-| Type-safe routes/params | Generated names, params, search, `reverse()`, response MIME                                                | Stable typed links; route-local param types                                    | Best-in-class                                                                      | Typed path params                                                       |
+| Type-safe routes/params | Generated names, params, search, `ctx.reverse()`/`href()`, response MIME                                   | Stable typed links; route-local param types                                    | Best-in-class                                                                      | Typed path params                                                       |
 | Client render selection | Per-segment/loader `revalidate()` policy; typed action and result matching                                 | Automatic segment reuse; refresh/invalidation APIs                             | Match/loader reload policy                                                         | Route refetch/reload                                                    |
 | Slots and intercepts    | Code-defined named slots with their own loaders/policy; conditional alternate soft-navigation compositions | File-system `@slot` + intercept conventions                                    | Route masking, no parallel RSC slot graph                                          | No equivalent route-slot graph                                          |
 | Caching                 | One segment store = runtime + build-time + `"use cache"`, tags, SWR                                        | Cache Components plus distinct server/client cache lifecycles                  | Router loader cache + Query integration + HTTP/CDN policy                          | Minimal                                                                 |
@@ -81,16 +81,16 @@ const router = createRouter().routes(({ path }) => [
 As the application grows, each requirement adds one local primitive to that same
 tree:
 
-| When you need to…                          | Add…                              |
-| ------------------------------------------ | --------------------------------- |
-| make navigation refactor-safe              | a route `name` and `reverse()`    |
-| split the application into modules         | `urls()` and `include()`          |
-| keep request data live beneath cached UI   | `loader()`                        |
-| cache or prerender a shared shell          | `cache()` or `Prerender()`        |
-| choose what updates after an action        | `revalidate()`                    |
-| render independent regions                 | `parallel()` and named slots      |
-| open a route as a modal on soft navigation | `intercept()`                     |
-| inspect where request time went            | `debugPerformance` or `telemetry` |
+| When you need to…                          | Add…                               |
+| ------------------------------------------ | ---------------------------------- |
+| make navigation refactor-safe              | a route `name` and `ctx.reverse()` |
+| split the application into modules         | `urls()` and `include()`           |
+| keep request data live beneath cached UI   | `loader()`                         |
+| cache or prerender a shared shell          | `cache()` or `Prerender()`         |
+| choose what updates after an action        | `revalidate()`                     |
+| render independent regions                 | `parallel()` and named slots       |
+| open a route as a modal on soft navigation | `intercept()`                      |
+| inspect where request time went            | `debugPerformance` or `telemetry`  |
 
 Nothing in the first route requires learning the last row. More importantly, the
 last row does not force a migration to a second router, client data library, or
@@ -140,7 +140,11 @@ configure a node, so they can be imported or composed through small factories:
 ```tsx
 const withAccountPolicy = () => [
   middleware(requireUser),
-  revalidate((ctx) => ctx.isAction(AccountActions) || undefined),
+  // After an action, re-run only for account actions (a hard decision that ends
+  // the chain for later revalidators); on navigation, keep the default.
+  revalidate((ctx) =>
+    ctx.isAction() ? ctx.isAction(AccountActions) : undefined,
+  ),
 ];
 
 const accountPatterns = urls(({ path }) => [
@@ -208,7 +212,7 @@ you statically generate your top 1,000 products and serve the long tail
 dynamically, from one definition. Next.js approximates this with
 `generateStaticParams` + `dynamicParams`, but that is two separate knobs rather
 than one decision point inside your handler. See
-[prerender-api-design.md](../../../docs/prerender-api-design.md).
+[prerender-api-design.md](https://github.com/rangojs/rango/blob/main/packages/rangojs-router/docs/prerender-api-design.md).
 
 ### Progressive enhancement is a tested contract
 
@@ -297,8 +301,8 @@ The router gives you guarantees most file-based routers leave implicit:
   only; parallel siblings do not bleed into each other.
 - **Dev/prod matching parity** — one trie is used in both dev and production, so
   matching cannot drift between them. See
-  [matching-and-lazy-discovery.md](../../../docs/internal/matching-and-lazy-discovery.md)
-  and [execution-model.md](../../../docs/internal/execution-model.md).
+  [matching-and-lazy-discovery.md](https://github.com/rangojs/rango/blob/main/packages/rangojs-router/docs/internal/matching-and-lazy-discovery.md)
+  and [execution-model.md](https://github.com/rangojs/rango/blob/main/packages/rangojs-router/docs/internal/execution-model.md).
 
 ### Observability you do not wire yourself
 
@@ -311,7 +315,7 @@ Next.js also ships automatic OTel instrumentation; Rango's distinction is that t
 same router-owned phase registry drives its traces, local waterfall, and
 `Server-Timing` output. TanStack's strength is client/data devtools; Waku does not
 ship an equivalent request-phase model. See
-[telemetry.md](../../../docs/telemetry.md).
+[telemetry.md](https://github.com/rangojs/rango/blob/main/packages/rangojs-router/docs/telemetry.md).
 
 ### Deploy to Node, Cloudflare, and Vercel — and host many apps behind one entry
 
@@ -367,15 +371,19 @@ old-deployment request pinning.
 ### A shipped testing harness for server code
 
 The `@rangojs/router/testing/*` entry points give you `runLoader`,
-`runMiddleware`, `dispatch` (base `./testing`), `renderHandler` and real Flight
-rendering (`renderServerTree`, `findClientBoundaries`, `findElements`) from
-`./testing/flight`, `renderRoute` from `./testing/dom`, and a Playwright e2e
-harness with dev/prod parity helpers (`parityDescribe`, `expectParity`) from
-`./testing/e2e`. You can unit-test a loader, a middleware, or an RSC handler in
-isolation. Next.js and Waku ship no official primitives for testing server
-components/handlers; TanStack documents testing patterns (build your own harness
-from `createRouter`/`createMemoryHistory`) but ships no testing package, and
-nothing at the RSC-handler level. See [testing.md](../../../docs/testing.md).
+`runMiddleware`, `runInRequestContext` (server actions), `dispatch` (base
+`./testing`), `renderHandler` and real Flight rendering (`renderServerTree`,
+`findClientBoundaries`, `findElements`) plus a real PPR shell capture and HIT
+(`serveShellRequest`, `resetShellTestState`) from `./testing/flight`,
+`renderRoute` from `./testing/dom`, a vitest preset from `./testing/vitest`, and
+a Playwright e2e harness with dev/prod parity helpers (`parityDescribe`,
+`expectParity`) from `./testing/e2e`. You can unit-test a loader, a middleware,
+an action, or an RSC handler in isolation. Next.js and Waku ship no official
+primitives for testing server components/handlers; TanStack documents testing
+patterns (build your own harness from `createRouter`/`createMemoryHistory`) but
+ships no testing package, and nothing at the RSC-handler level. See the
+[testing skill](../../testing/SKILL.md) and
+[testing.md](https://github.com/rangojs/rango/blob/main/packages/rangojs-router/docs/testing.md).
 
 ### Bundle discipline
 
@@ -386,7 +394,7 @@ the build if React's development bundle leaks into production. Treat those as
 Rango baselines, not a normalized cross-framework benchmark: application shape,
 React version, compiler output, and deployment transforms make headline bundle
 comparisons unreliable. Waku deliberately targets a smaller surface. See
-[client-chunking.md](../../../docs/client-chunking.md).
+[client-chunking.md](https://github.com/rangojs/rango/blob/main/packages/rangojs-router/docs/client-chunking.md).
 
 ## Runtime mechanics in depth
 
@@ -495,7 +503,7 @@ layout(<ShopLayout />, () => [
 A click from the list renders `ProductQuickView` into `@modal` and preserves the
 list behind it. A direct visit or reload renders the canonical full page. Back
 closes the modal and restores the preserved background. The intercept can own its
-middleware, layout, loaders, loading/error policy, loader-level caching, and
+middleware, layout, loaders, loading state, and loader-level caching and
 `revalidate()` rules; the `when` config selector (the 4th argument to
 `intercept()`) can choose by navigation source.
 
@@ -521,17 +529,20 @@ There are two distinct things named "revalidate", and the split is deliberate:
    downstream revalidators in the same decision chain. This is surgical
    post-action control: "this widget re-renders only when `addToCart` ran; the
    rest of the tree stays put."
-   See [is-action-api-design.md](../../../docs/design/is-action-api-design.md).
+   See [is-action-api-design.md](https://github.com/rangojs/rango/blob/main/packages/rangojs-router/docs/design/is-action-api-design.md).
 2. **`revalidate: false` on `<Link>` / `navigate()`** — shallow navigation. When
    the pathname is unchanged (a search or hash change), it updates the URL and all
    location hooks but skips the server fetch and re-render entirely. For filters,
    tabs, and pagination. See
-   [shallow-navigation.md](../../../docs/design/shallow-navigation.md).
-
-Both are separate from `revalidateTag()`/`updateTag()`, which hard-purge tagged
-cache entries. `updateTag()` is awaitable for read-your-own-writes;
-`revalidateTag()` schedules the same invalidation in the background. Neither API
-selects a client segment to render. Next.js offers `router.refresh()` (and
+   [shallow-navigation.md](https://github.com/rangojs/rango/blob/main/packages/rangojs-router/docs/design/shallow-navigation.md).
+
+Both are separate from `revalidateTag()`/`updateTag()`, which evict tagged
+cache entries; the request that calls either reads its own writes.
+`updateTag()` also awaits the durable write; `revalidateTag()` schedules it in
+the background. The mutating user's next requests skip the stores' per-isolate
+PPR shell memos via a fresh-reads cookie, and other users converge within the
+memo window and the platform's own propagation. Neither API selects a client
+segment to render. Next.js offers `router.refresh()` (and
 `refresh()` from `next/cache`) plus path/tag cache invalidation, but no per-segment
 render predicate and no typed action discrimination — and its invalidations clear
 the whole client cache rather than selecting a segment. TanStack's `shouldReload`/`router.invalidate()` is the nearest
@@ -614,18 +625,22 @@ this resource-aware policy layer.
 
 `createLoader(fn)` / `loader()` define **live-by-default** data units: they are
 excluded from an enclosing segment cache and resolve on every request unless the
-loader itself explicitly opts into `cache()`. They may safely read `cookies()`,
-`headers()`, request context, and `env` because loader execution is outside the
-cached shell. Loaders run in parallel, stream independently under `loading()`
-boundaries, compose server-side via `ctx.use(OtherLoader)`, and carry
-route-level authority: they can throw `notFound()`/`redirect()`, WRITE handles
-(`ctx.use(Meta)({ title })` — data-derived page metadata pushed from the data's
-producer), read handle data after the render settles (`ctx.get(handle)` behind
-`await ctx.rendered()`), and opt into `loader(Def, { ssr: false })`
-so a document render awaits them before first flush (deterministic SSR'd data,
-meta, and 404 status). Reads happen through `useLoader` in a client component
-(including its SSR pass) or `useFetchLoader` for standalone client fetches. "Fetchable" loaders are callable
-endpoints with their own middleware and GET/POST/PUT/PATCH/DELETE bodies.
+loader itself explicitly opts into `cache()`. A loader without `ssr: false` may
+safely read `cookies()`, `headers()`, request context, and `env` because its
+execution is outside the cached shell; a loader with its own `cache()` must put
+those reads in its `key()`, or its miss fails and stores nothing. On a `ppr`
+route an `ssr: false` loader bakes into the shell, so an identity read there
+refuses the capture. Loaders run in parallel, stream independently under
+`loading()` boundaries, compose server-side via `ctx.use(OtherLoader)`, and
+carry route-level authority: they can throw `notFound()`/`redirect()`, WRITE
+handles (`ctx.use(Meta)({ title })` — data-derived page metadata pushed from the
+data's producer), read handle data after the render settles (`ctx.get(handle)`
+behind `await ctx.rendered()`), and opt into `loader(Def, { ssr: false })` so a
+document render awaits them before first flush (deterministic SSR'd data, meta,
+and 404 status). Reads happen through `useLoader` in a client component
+(including its SSR pass) or `useFetchLoader` for standalone client fetches.
+"Fetchable" loaders are callable endpoints with their own middleware and
+GET/POST/PUT/PATCH/DELETE bodies.
 
 One sharp edge is worth stating because the distinction matters: a cached handler
 can call `await ctx.use(Loader)`, but if it renders that result inline, it bakes the
@@ -675,7 +690,7 @@ a fully prerendered route. Caching loader data is a separate, explicit opt-in on
 that loader.
 
 The mechanism is concrete: a prerendered route serves its baked Flight shell from
-the store, then `resolveLoadersOnly()` resolves the loaders through their own
+the store, then the router resolves the loaders through their own
 freshness policy at request time and merges their segments into that replayed
 shell. With the default policy you get a cached/prerendered shell plus live data,
 automatically, with no per-route static-vs-dynamic decision. The loader is the
@@ -686,7 +701,8 @@ designated live data slot in a cache-first RSC tree.** Several properties follow
 that no loader-before-render has:
 
 - it is the **cache-safety escape hatch** — the only place request-coupled reads
-  are allowed inside a cache scope, because it is the part guaranteed to re-run;
+  are allowed inside a cache scope, because it is the part guaranteed to re-run
+  (a loader without `ssr: false` and without its own unkeyed `cache()`);
 - it is **standalone and composable**, not route-coupled — one `createLoader()`
   read by many segments, composed via `ctx.use`, or exposed as a fetchable endpoint;
 - it **streams as a hole, not a gate** — concurrent, Suspense-resolved under
@@ -767,16 +783,18 @@ safe rule remains simple: read request-specific context at the live point of use
 normally a loader, rather than deriving it outside and carrying it into a cached
 shell.
 
-This is where the taint and loader designs meet. Loaders are the sanctioned dynamic
-holes: they run outside the enclosing segment cache and may read the current
-request, while the shared shell remains protected. Next.js also isolates runtime
-APIs from ordinary `"use cache"`, and React's optional taint APIs protect values at
-the server-to-client serialization boundary. Those are useful but different
+This is where the taint and loader designs meet. Loaders are the sanctioned
+dynamic holes: they run outside the enclosing segment cache and may read the
+current request (except, on a `ppr` route, an `ssr: false` loader or a loader a
+handler awaits, which the capture runs and refuses on such a read), while the
+shared shell remains protected. Next.js also isolates runtime APIs from ordinary
+`"use cache"`, and React's optional taint APIs protect values at the
+server-to-client serialization boundary. Those are useful but different
 contracts; they do not provide Rango's route-aware tainted-argument keying,
 non-cacheable typed context variables, handle capture/replay, and loader escape
 path as one system. TanStack Start and Waku leave this boundary primarily to
 application architecture. See the [cache guide](../../cache-guide/SKILL.md) and
-[`"use cache"` design](../../../docs/use-cache-api-design.md).
+[`"use cache"` design](https://github.com/rangojs/rango/blob/main/packages/rangojs-router/docs/use-cache-api-design.md).
 
 ## Performance diagnostics (`debugPerformance`)
 
@@ -809,7 +827,7 @@ Next.js has no equivalent flip-a-boolean per-request phase waterfall: its automa
 OTel spans still need an exporter and trace viewer. TanStack's strength is
 client/data devtools, a different axis from server request-phase diagnostics. Waku
 does not ship an equivalent phase model. See
-[telemetry.md](../../../docs/telemetry.md).
+[telemetry.md](https://github.com/rangojs/rango/blob/main/packages/rangojs-router/docs/telemetry.md).
 
 ## Coming from a specific framework
 
@@ -819,7 +837,7 @@ layers for a code-defined, refactor-safe router and one caching model. You gain
 Cloudflare as a first-class target and phase spans for free. You give up the
 largest ecosystem and talent pool in the React world — the real cost.
 
-**From TanStack Start.** You get comparable type-safe routing (`reverse()`, typed
+**From TanStack Start.** You get comparable type-safe routing (`ctx.reverse()`/`href()`, typed
 params/search, even typed response MIME via `.json()`/`.text()`/`.image()`), plus a
 true RSC-first model (zero-bundle server components, Flight) that TanStack's
 client-first core added later and opt-in. You give up TanStack's best-in-class

package/skills/composability/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: composability
-description: Reusable composition patterns with globally importable route helpers in @rangojs/router. Use when sharing loaders, middleware, or handler logic across multiple route files, or avoiding copy-pasting the same route setup everywhere.
+description: Reusable composition patterns with globally importable route helpers and include() modules in @rangojs/router. Use when sharing loaders, middleware, or caching config across multiple route files, splitting routes into eager or code-split include() groups, or avoiding copy-pasting the same route setup everywhere.
 argument-hint: "pattern-name"
 ---
 
@@ -8,6 +8,11 @@ argument-hint: "pattern-name"
 
 Route helpers can be imported directly from `@rangojs/router` and used to build reusable composition factories. This enables sharing common route configurations across multiple routes and modules.
 
+Use this skill when the same config (auth middleware, caching, loading and error
+UI, revalidation) repeats across routes, when splitting a route tree into
+modules with `include()`, or when sizing code-split route groups. To attach
+defaults to one handler instead of a factory, see `/handler-use`.
+
 ## Globally Importable Helpers
 
 These helpers can be imported and called outside the `urls()` callback parameter:
@@ -24,10 +29,11 @@ import {
   intercept,
   errorBoundary,
   notFoundBoundary,
+  transition,
 } from "@rangojs/router";
 ```
 
-They work because they use AsyncLocalStorage internally and resolve context at call time, not import time.
+They work because they read the active `urls()` builder from AsyncLocalStorage at call time, not import time. Calling one outside a running `urls()` builder throws a `DslContextError`.
 
 ## Why path() and include() Are Not Global
 
@@ -49,26 +55,25 @@ The globally importable helpers (`cache`, `middleware`, `loading`, etc.) are con
 Define reusable factories that return arrays of use items:
 
 ```typescript
-import { cache, revalidate, loading, errorBoundary, middleware } from "@rangojs/router";
+// route-config.tsx
+import type { ReactNode } from "react";
+import { cache, loading, errorBoundary, middleware } from "@rangojs/router";
+import { authMiddleware, loggingMiddleware } from "./middleware";
 
 // Shared caching configuration
-const withCaching = () => [
-  cache({ ttl: 600_000 }),
-  // Defer on navigation (|| undefined) so each route keeps its own param/search
-  // revalidation default; only force a re-run when an action ran.
-  revalidate(({ actionId }) => (actionId ? true : undefined)),
+export const withCaching = () => [
+  cache({ ttl: 600 }), // seconds
 ];
 
 // Shared loading and error handling
-const withLoadingAndError = (skeleton: ReactNode) => [
+export const withLoadingAndError = (skeleton: ReactNode) => [
   loading(skeleton),
   errorBoundary(() => <div>Something went wrong</div>),
 ];
 
-// Shared auth middleware
-const withAuth = () => [
-  middleware(authMiddleware),
-  middleware(loggingMiddleware),
+// Shared middleware (the array form registers both in order)
+export const withAuth = () => [
+  middleware([authMiddleware, loggingMiddleware]),
 ];
 ```
 
@@ -97,7 +102,7 @@ const withAuth = () => [
 
 ## Using Factories in Routes
 
-Place factory calls inside `path()` or `layout()` use callbacks. The returned arrays are flattened automatically (up to 3 levels):
+Place factory calls inside any use callback (`path()`, `layout()`, `parallel()`, `intercept()`, `loader()`), as long as every item is valid there. The returned arrays are flattened automatically (up to 3 levels):
 
 ```typescript
 import { urls } from "@rangojs/router";
@@ -126,13 +131,10 @@ Factories can be defined in shared modules and reused across separate `urls()` d
 
 ```typescript
 // src/route-config.ts
-import { cache, revalidate, middleware } from "@rangojs/router";
+import { cache, middleware } from "@rangojs/router";
 import { authMiddleware } from "./middleware/auth";
 
-export const withPublicDefaults = () => [
-  cache({ ttl: 300 }),
-  revalidate(({ actionId }) => (actionId ? true : undefined)),
-];
+export const withPublicDefaults = () => [cache({ ttl: 300 })];
 
 export const withProtectedDefaults = () => [
   middleware(authMiddleware),
@@ -195,7 +197,10 @@ urls(({ include }) => [
 ]);
 ```
 
-The split module exposes its `urls()` value as the default export (convention):
+The provider must resolve to a `urls()` value — either as the module's `default`
+export (the usual form) or returned directly
+(`() => import("./shop-patterns").then((m) => m.shopPatterns)`). Anything else
+throws when the group is first loaded:
 
 ```typescript
 // src/shop-patterns.ts
@@ -219,7 +224,7 @@ splitting a thin group buys little). Both match identically at runtime — only
 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
+`href()`, `ctx.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.
@@ -227,8 +232,10 @@ the same way, so a code-split group is still fully typed.
 ### Sizing async include groups (measured)
 
 The first request into an async group pays that group's chunk import; every
-request after that is flat. Measured on a deployed Cloudflare worker with
-26k routes (2026-07, warm RTT floor ~23 ms):
+request after that is flat. One cold, single-run measurement right after
+deploying a 26k-route app to Cloudflare Workers (2026-07, warm RTT floor
+~23 ms, see `tests/cloudflare-stress-demo/BENCHMARK-2026-07-04-edge-26k.md`).
+Treat the numbers as orders of magnitude:
 
 | Group size                 | First-hit latency                    |
 | -------------------------- | ------------------------------------ |
@@ -261,11 +268,12 @@ erases first-hit cost for the isolate entirely.
 For typed factories, import the composition types:
 
 ```typescript
+import { cache, loading, middleware } from "@rangojs/router";
 import type { RouteUseItem, LayoutUseItem, UseItems } from "@rangojs/router";
 
 // Factory for path() use callbacks
 const withCaching = (): RouteUseItem[] => [
-  cache({ ttl: 600_000 }),
+  cache({ ttl: 600 }),
 ];
 
 // Factory for layout() use callbacks
@@ -281,12 +289,13 @@ const withEverything = (): UseItems<RouteUseItem> => [
 ```
 
 - `RouteUseItem[]` -- flat array for `path()` use callbacks
-- `LayoutUseItem[]` -- flat array for `layout()` use callbacks
-- `UseItems<T>` -- allows nested arrays from composing factories together
+- `LayoutUseItem[]` -- flat array for `layout()` use callbacks (every item type)
+- `UseItems<T>` -- allows one level of nested arrays from composing factories together
+- `HandlerUseItem` -- items a `handler.use` callback may return (see `/handler-use`)
 
 ## Rules
 
-- Helpers execute lazily -- factory functions are defined anywhere, but only called inside a `urls()` context (within `path()` or `layout()` use callbacks)
-- Calling helpers outside a `urls()` context throws an error
+- Helpers execute lazily -- factory functions are defined anywhere, but only called while a `urls()` builder runs (inside a use callback)
+- Calling helpers outside a `urls()` builder throws a `DslContextError`
 - Nested arrays from factories are flattened automatically via `.flat(3)`
-- `path()` and `include()` cannot be used in factories -- they define route structure and must remain visible in the `urls()` callback
+- `path()` and `include()` are not exported as standalone helpers -- they define route structure and must remain visible in the `urls()` callback

package/skills/css/SKILL.md

@@ -7,9 +7,10 @@ argument-hint:
 # CSS imports
 
 Document/app CSS in Rango lives in the Document `<head>`, loaded with Vite's
-`?url` import and a `precedence`-managed `<link rel="stylesheet">`. This page is
-the why and the one cross-app caveat; `/tailwind` is the concrete setup, `/theme`
-is dark mode, `/fonts` is fonts.
+`?url` import and a `precedence`-managed `<link rel="stylesheet">`. This page
+explains that pattern, when a side-effect `import "./x.css"` is fine, and how CSS
+behaves across host-router apps. `/tailwind` is the concrete Tailwind setup,
+`/theme` is dark mode, `/fonts` is fonts.
 
 ## The pattern
 
@@ -18,7 +19,7 @@ is dark mode, `/fonts` is fonts.
 "use client";
 
 import type { ReactNode } from "react";
-import { MetaTags } from "@rangojs/router/client";
+import { Html } from "@rangojs/router/client";
 import styles from "./index.css?url";
 
 export function Document({ children }: { children: ReactNode }) {
@@ -27,7 +28,7 @@ export function Document({ children }: { children: ReactNode }) {
       <head>
         <link rel="preload" href={styles} as="style" precedence="default" />
         <link rel="stylesheet" href={styles} precedence="default" />
-        <MetaTags />
+        <Html.Meta />
       </head>
       <body>{children}</body>
     </html>
@@ -50,14 +51,10 @@ A client-side navigation that crosses an app boundary is a **full document load*
 (the server returns `X-RSC-Reload` on an app switch — see `/host-router`), so the
 target app's entire document — its stylesheets, theme, meta — is re-established
 by the target app's own load. Each app owns its document; how one app renders a
-stylesheet has no effect on another.
-
-(This replaced an earlier soft cross-app swap. Under it, a stylesheet shared
-across apps by `href` — classically every app's `@import "tailwindcss"` compiling
-to one hashed asset — could be silently dropped by React's by-`href` resource
-dedup when the apps disagreed on `precedence` (one unmanaged, one managed). The
-full reload removes that footgun entirely, which is the main reason cross-app
-navigation is a hard boundary.)
+stylesheet has no effect on another. In particular, apps may disagree on
+`precedence` for a stylesheet they share by `href` (for example every app's
+`@import "tailwindcss"` compiling to one hashed asset) without React's by-`href`
+dedup dropping it.
 
 ## Side-effect imports vs `?url`
 

package/skills/debug-manifest/SKILL.md

@@ -1,30 +1,49 @@
 ---
 name: debug-manifest
-description: Debug and inspect route manifest structure. Use when routes aren't matching as expected, you need to see the generated route tree, or a path resolves to the wrong handler.
+description: Inspect the router's route manifest (route/layout tree, shortCodes, parent links, loader/middleware flags) and diff it between versions. Use when routes aren't matching as expected, you need to see the generated route tree, or a path resolves to the wrong handler.
 argument-hint:
 ---
 
 # Debug Manifest
 
-Inspect the route manifest to verify parent relationships, shortCodes, and route structure.
+Dump the route manifest the router builds from your `urls()` tree to verify
+parent relationships, shortCodes, and which segments carry loaders, middleware,
+error boundaries, parallel slots, or intercepts. This is a development aid; the
+diff helpers below are internal and may change between releases.
 
-## Programmatic Access
+## Programmatic access
 
-Call `router.debugManifest()` — an `async` method on the router instance:
+The router returned by `createRouter()` has an async `debugManifest()` method:
 
 ```typescript
 import { router } from "./router.js";
 
-// Only in development
+// Development only
 if (process.env.NODE_ENV !== "production") {
   const manifest = await router.debugManifest();
   console.log(JSON.stringify(manifest, null, 2));
 }
 ```
 
-## Manifest Structure
+Run it on the server side (for example from a dev-only route handler), since
+it evaluates your `urls()` tree. The result type is `SerializedManifest`
+(`import type { SerializedManifest } from "@rangojs/router"`).
 
-The programmatic `router.debugManifest()` call returns `{ routes, layouts, totalRoutes, totalLayouts }`:
+### `include()` groups are not expanded
+
+`include()` groups are lazy: the router evaluates one on the first request that
+matches its prefix. `debugManifest()` does not evaluate them. It lists the
+routes and layouts declared directly in each `.routes()` / `urls` mount, so the
+routes inside an included group are missing from `routes` and `totalRoutes`.
+For their names and patterns, read the generated `*.named-routes.gen.ts` file,
+which lists every route including those in `include()` groups.
+
+## Manifest structure
+
+`debugManifest()` returns `{ routes, layouts, totalRoutes, totalLayouts }`.
+Every entry has the same fields; `pattern` is present on routes only. Cache
+boundaries are listed under `layouts` with `type: "cache"`. Shape (values are
+illustrative):
 
 ```json
 {
@@ -47,7 +66,12 @@ The programmatic `router.debugManifest()` call returns `{ routes, layouts, total
       "id": "debug.M0.$root",
       "shortCode": "M0L0",
       "type": "layout",
-      "parentShortCode": null
+      "parentShortCode": null,
+      "hasLoader": false,
+      "hasMiddleware": false,
+      "hasErrorBoundary": false,
+      "parallelCount": 0,
+      "interceptCount": 0
     }
   },
   "totalRoutes": 45,
@@ -55,30 +79,39 @@ The programmatic `router.debugManifest()` call returns `{ routes, layouts, total
 }
 ```
 
-## ShortCode Format
+## ShortCode format
 
-| Prefix | Meaning                                  |
-| ------ | ---------------------------------------- |
-| **M**  | Mount index (multiple `.routes()` calls) |
-| **L**  | Layout                                   |
-| **C**  | Cache boundary                           |
-| **R**  | Route                                    |
-| **P**  | Parallel slot                            |
+A shortCode is the parent's shortCode plus one segment per level:
 
-Example: `M0L0L1C0R0` = Mount 0 → Root Layout → Nested Layout → Cache → Route
+| Prefix | Meaning                                                                 |
+| ------ | ----------------------------------------------------------------------- |
+| **M**  | Mount index (`.routes()` / `urls` registrations and `include()` mounts) |
+| **L**  | Layout (the router adds a root layout, `M<n>L0`)                        |
+| **C**  | Cache boundary                                                          |
+| **R**  | Route                                                                   |
+| **P**  | Parallel slot                                                           |
+| **I**  | `include()` scope token, so included routes never collide with siblings |
 
-## Debugging Checklist
+Example: `M0L0L1C0R0` = Mount 0 → Root Layout → Nested Layout → Cache → Route.
+At runtime, a route from an `include()` placed under the root layout gets a
+shortCode such as `M0L0I0R0`.
 
-1. **Routes have parents**: `parentShortCode` should NOT be `null` (except root layout)
-2. **Correct hierarchy**: ShortCode should reflect nesting (e.g., `M0L0R0` not `M0R0`)
-3. **Loaders attached**: Check `hasLoader: true` for routes with data requirements
-4. **Intercepts registered**: `interceptCount > 0` for modal/overlay patterns
+## Debugging checklist
 
-## Comparing Manifests
+1. **Correct hierarchy**: the shortCode reflects nesting (`M0L0L1R0` for a
+   route in a nested layout, not `M0L0R0`).
+2. **Parents**: only a mount's root layout (`M<n>L0`) has
+   `parentShortCode: null`.
+3. **Loaders attached**: `hasLoader: true` on routes/layouts that declare
+   `loader()`.
+4. **Intercepts registered**: `interceptCount > 0` where you declared
+   `intercept()` for modal/overlay patterns.
+5. **Slots**: `parallelCount` matches the number of `parallel()` slots.
+
+## Comparing manifests
 
 ```typescript
 import {
-  serializeManifest,
   compareManifests,
   formatManifestDiff,
 } from "@rangojs/router/__internal";
@@ -91,16 +124,26 @@ const diff = compareManifests(oldManifest, newManifest);
 console.log(formatManifestDiff(diff));
 ```
 
-## Common Issues
+`compareManifests` reports added, removed, and changed routes and layouts
+(field-level: `old` / `new` per changed field).
+
+## Common issues
 
-### Routes have `parentShortCode: null`
+### A route sits under the wrong layout
 
-Routes should have a layout parent. Check that `urls()` handler is being wrapped in root layout.
+Check that the `layout()` call wraps the route in its `use` callback
+(`layout(<Shell />, () => [path(...)])`). A `path()` listed next to a
+`layout()` is a sibling, not a child.
 
-### Missing layouts in hierarchy
+### Unexpected mount index
 
-Verify `layout()` calls wrap child routes correctly.
+Each `.routes()` call (and the `urls` option) registers a separate mount (M0,
+M1, ...), and each `include()` also takes a mount index. Routes registered by
+separate `.routes()` calls do not share layouts or middleware; compose modules
+with `include()` inside one `urls()` tree when they should (`/composability`).
 
-### Wrong mount index
+### Missing flags
 
-Multiple `.routes()` calls create separate mounts (M0, M1, etc.). Use `include()` to share context.
+`hasMiddleware` / `hasLoader` / `hasErrorBoundary` are per entry. Middleware or
+a loader declared on a parent layout shows on that layout, not on each child
+route.