@rangojs/router 0.24.4 → 0.25.0

package/skills/ppr/SKILL.md

@@ -151,12 +151,42 @@ cache miss (no shell).
 
 ### A request middleware rewrote
 
-A request middleware rewrote (`throw rewrite()`, `/middleware`) to a `ppr`
-route is served the target's shell under the target's key. The capture
-renders the target as a direct visit: `ctx.rewrittenFrom` reads `undefined`
-there and the payload carries the target's pathname, so the shell is the
-same for direct and rewritten visitors (a component that renders
-`usePathname()` shows the target's URL to a rewritten visitor on a HIT).
+A URL's shared shell is read and written only by requests on that URL. A
+request middleware rewrote (`throw rewrite()`, `/middleware`) to a `ppr` route
+neither reads the target's shell nor captures it: it renders live, at the
+visitor's location (`usePathname()`, `ctx.rewrittenFrom`), on every request.
+The target's shell is captured by a direct visit or a `router.prerender()` warm
+of the target's URL, so nothing a rewriting middleware set (a variable, the
+visitor's URL) ends up in the shell every direct visitor gets.
+
+The rewrite chooses a shell for the rewritten request with `.shell()`:
+
+```ts
+// A routing catch-all: each public URL gets a shell of its own.
+throw rewrite("item", { id }).shell("visitor");
+
+// A lock or promo page that renders nothing of the visitor's URL. A lock
+// also refuses mutations, which a rewrite otherwise moves to the target.
+throw rewrite("maintenance").shell("target").disallowMutations();
+```
+
+- `.shell("visitor")` keys the shell by the visitor's URL and the target
+  (`visitorShellCacheKey(router, "/summer", "/item/1")` in a test; the target
+  route's `cache.searchParams` filter and its own partition apply). The
+  capture renders the visitor's location and `ctx.rewrittenFrom`, and a
+  variable set before the throw may be baked in, since the key covers the URL
+  it came from. Navigation replay uses the same key. A build shell of the
+  target is never served to it. Store growth is one shell per public URL;
+  `updateTag()` reaches every one of them through the shell's tags.
+- `.shell("target")` reads and captures the target's shared shell from the
+  rewritten request. The shell then shows the target's URL to a rewritten
+  visitor on a HIT (`usePathname()` hydrates against the address bar, so a
+  component that renders it mismatches), and a variable set before the throw
+  is baked into the shell direct visitors get. Use it only for a page that
+  renders neither.
+
+A rewritten navigation without `.shell()` reports
+`x-rango-ppr-replay: BYPASS; reason=rewritten`.
 
 ### Request-partitioned shells
 
@@ -1299,7 +1329,10 @@ shell-cache only public/shared pages, keep per-user content in live-lane
 loaders (no `ssr: false`) or nested promises in bake-lane loader data — NOT in
 handler output or plain bake-lane container data — mark the variable
 `{ cache: false }` so a stray shell read refuses the capture, or key per
-variant at the CDN tier.
+variant at the CDN tier. A variable a middleware sets before `throw rewrite()`
+never reaches the target's shared shell: a rewritten request captures none
+unless its rewrite opts in with `.shell("target")` (see "A request middleware
+rewrote"); with `.shell("visitor")` it lands only in that URL's own shell.
 
 ## What always renders without a shell
 
@@ -1307,7 +1340,9 @@ Non-GET, non-partial RSC/action/loader fetches, partial requests without an
 eligible captured segment snapshot, per-request CSP nonce, `streamMode:
 "allReady"`, redirects, 404s, error renders, routes without `ppr`, a document
 request the route's own `cache()` scope refuses (`cache(false)`, or a
-`condition()` returning false for it), and any store without the shell family.
+`condition()` returning false for it), a request middleware rewrote whose
+rewrite chose no shell (`rewrite(...).shell()`), and any store without the
+shell family.
 A stored shell is invalidated when
 `React.version` changes (postponed state is build-coupled) or when the router's
 document version changes, so a deploy that changes the router self-heals via

package/skills/prerender/SKILL.md

@@ -1020,8 +1020,7 @@ in dev. A removed page is the exception: its marker answers 404 in dev too.
   that only a refresh produced.
 - **Connected clients can lag.** A refresh has no response to reach open tabs:
   a client that prefetched the page keeps its copy for `prefetchCacheTTL`
-  (default 300s) and the browser HTTP cache (`prefetchCacheControl`). Lower
-  them if the window matters.
+  (default 300s, in memory only). Lower it if the window matters.
 - **Entries are per deploy.** Keys carry the router's data version, so a deploy
   that changes server code starts from the build entries again; a client-only
   deploy keeps refreshed pages.

package/skills/rango/SKILL.md

@@ -111,6 +111,7 @@ stated, greppable contract.
 | debug a slow request                    | `debugPerformance` / telemetry     | /observability          |
 | share config across routes              | factory returning a helper array   | /composability          |
 | compose a sub-app / module              | `include()`                        | /route                  |
+| lay out a whole app                     | section modules, guards, groups    | /app-structure          |
 | modal / soft navigation                 | `intercept()`                      | /intercept              |
 | route group of client components        | `clientUrls()` in `"use client"`   | /client-urls            |
 | set meta/breadcrumbs from loader data   | `ctx.use(Handle)` in the loader    | /loader                 |
@@ -306,8 +307,10 @@ Grouped by concern — read when you need to…
 | Skill                     | Description                                                                |
 | ------------------------- | -------------------------------------------------------------------------- |
 | `/router-setup`           | Create and configure the RSC router                                        |
+| `/app-structure`          | Whole-app recipes: large app with admin, multi-app, content site, shop     |
 | `/route`                  | Define routes with `urls()`, `path()`, and `include()`                     |
 | `/client-urls`            | Client-component route groups with `clientUrls()` — no handlers            |
+| `/ux-architecture`        | Recipes for fast, stable navigation with `urls()` and `clientUrls()`       |
 | `/layout`                 | Layouts that wrap child routes                                             |
 | `/parallel`               | Multi-column layouts and sidebars                                          |
 | `/intercept`              | Modal/slide-over patterns for soft navigation                              |

package/skills/response-routes/SKILL.md

@@ -617,7 +617,10 @@ path.json(
 
 A dot-local name (`ctx.reverse(".comments")`) is a type error here. The
 runtime reverse has no scope to resolve it against, so untyped (JS) code that
-calls it throws `Unknown route` and the route answers 500.
+calls it throws `Unknown route` and the route answers 500. Leaving out a
+required param (`ctx.reverse("blog.api.comments")`) throws
+`Missing param "slug" for route "blog.api.comments"`, with or without a params
+object; it never returns the `/:slug` pattern as a URL.
 
 ## Content Negotiation
 

package/skills/scripts/SKILL.md

@@ -133,6 +133,17 @@ re-pushed inline script. The GTM demo does exactly this: a root-layout `Script`
 bootstrap fires the first page_view on document load, and a `"use client"`
 `<GtmPageViews>` component fires a page_view on every subsequent soft navigation.
 
+**Key that component on a handle value that carries the page's path, not on the
+URL.** Handle values arrive on their own channel, by design: on a page React
+holds in a transition (`transition()`, a same-route search change, a prefetched
+click) the URL changes before the destination's `content_group` and title land,
+so an effect keyed on `usePathname()` sends the previous page's tagging. Push
+the navigation's `pathname + search` into your `Gtm` handle (collected as `page.path`) from a root
+`parallel()` slot with `revalidate(true)`, read the tagging with `useHandle(Gtm)`,
+and send the page_view when `page.path` differs from the last path sent (seed it
+with the landing path, which the bootstrap already sent). The pattern, its
+trade-offs and the code are in [hooks](../hooks/handle-and-actions.md#when-handle-values-change-by-design).
+
 ## The inline-self-inject rule (GTM/GA4/Segment)
 
 If an inline bootstrap must run **before** an external loader, do NOT push the
@@ -202,6 +213,6 @@ warns once per key. See `/ppr` → "What always renders without a shell".
 - **Partytown / web-worker offloading** — push the worker config with
   `type: "text/partytown"` and wire Partytown's own nonce config manually.
 
-A full GTM + GA4-style integration (page_view on first render + soft nav, nonce,
+A full GTM + GA4-style integration (page_view on first render + soft nav keyed on a path-carrying handle value, nonce,
 ecommerce events) lives in the router repository's `tests/vite-rsc-demo` app
 (not shipped in this package).

package/skills/server-actions/SKILL.md

@@ -446,8 +446,8 @@ import * as CartActions from "./actions/cart";
 
 urls(({ path, loader, revalidate }) => [
   path("/", HomePage, { name: "home" }, () => [
-    // Loader data re-runs by default after any action. Opt out with revalidate(() => false).
-    loader(StaticHomepageLoader, () => [revalidate(() => false)]),
+    // Loader data re-runs by default after any action. Opt out with revalidate(false).
+    loader(StaticHomepageLoader, () => [revalidate(false)]),
   ]),
 
   // Re-render the cart page handler AND re-resolve its loader only after cart
@@ -603,6 +603,12 @@ Redirects from actions render the **target** route tree's matched segments
 source page's — the target is what the user sees next. See `/hooks
 useLocationState` for reading flash state on the target page.
 
+Build the target by name rather than a literal path:
+`throw redirect(getRequestContext().reverse("account.settings"))`. It fills
+mount params (`:accountId`, `:locale`) from the page URL the action was called
+on, so the module that owns the action does not need to know its mount
+(`/links`).
+
 ### Same-origin by default (open-redirect protection)
 
 `redirect()` is same-origin by default on every path — JS, no-JS PE, and
@@ -624,6 +630,28 @@ model). Omit it and off-host targets stay blocked. `external` only waives the
 `javascript:` or `data:` URL is still neutralized, so a forged or mistaken
 `external` target can never become a scriptable navigation.
 
+## Actions on a Rewritten Page
+
+An action cannot `throw rewrite()`; use `redirect()`. But a page that
+middleware reached through `throw rewrite()` can call actions. The action
+(JS or a no-JS form post) is posted to the visitor's URL, so the same
+middleware sees it:
+
+- A rewrite in **route middleware** runs after the action, around the
+  re-render, which route middleware sees as the page's GET, so a rewrite
+  written for GETs only fires too. The action runs once, then the re-render
+  runs as the target: its global and route middleware, its handlers and
+  loaders. The page on screen is revalidated in place, as at the target's
+  own URL.
+- A rewrite in **global middleware** runs before the action and moves the
+  mutation to the target first: the target's global middleware, then the
+  action, once, then the target's route middleware and render, as a direct
+  post to the target. A page a routing rewrite showed (a multi-tenant host,
+  an A/B split) keeps its forms working, in JS and no-JS. A lock refuses
+  mutations instead: `throw rewrite("maintenance").disallowMutations()` is an
+  error before the action runs, or return a `Response` for mutations. See
+  `/middleware` ("Mutations: where the middleware sits decides").
+
 ## Error Handling
 
 ### Validation errors — return them as state
@@ -688,24 +716,36 @@ For a recoverable "already gone" case, return a result the form can show
 ### A loader that fails on the revalidation render
 
 A loader that throws while it reruns after the action does not undo the
-action, which has already run and returned. What follows depends on the route:
-
-- **No `loading()` on the route (and any `clientUrls()` route):** the action
-  call rejects with the loader's error, nothing of that revalidation commits,
-  and the page keeps its data and its React state. A `<form action>`,
-  `useActionState` or `useTransition` call hands that rejection to the nearest
-  React error boundary above the form.
-- **A `urls()` route with `loading()`:** the call resolves with the action's
-  result, the page renders, and the loader's read throws to the nearest React
-  error boundary.
-- **An `errorBoundary()` above the route:** its fallback replaces the route.
-
-For a failure the user can retry, return it from the loader as data
-(`{ ok: false, reason }`) and render it where the data goes. A failure returned
-as data is a value like any other, so a `cache()` on the loader (or a `ppr`
-bake, or a prerender) stores and serves it; a thrown error is never stored.
-See `/client-urls` → "A loader that fails on its rerun" for the table and an
-example.
+action, which has already run and returned. It behaves as on a navigation (a
+plain or fully prefetched click, Back/Forward), on every route, called
+directly or from `<form action>`, `useActionState` or `useTransition`:
+
+- The call resolves with the action's result.
+- The loader throws in place, at its `useLoader` read, and the nearest
+  boundary to the read catches it: your own React error boundary around the
+  read, else the route's `errorBoundary()`, else the router's root one.
+  Everything outside that boundary keeps its React state; loaders that reran
+  without error commit their new data.
+- The error goes to `onError` on the server (phase `"loader"`) and to
+  `useAction(action).revalidationError` in the browser (`error` stays `null`,
+  `result` is set).
+- A later rerun that succeeds clears an `errorBoundary()` fallback. Your own
+  boundary resets by its own rule: key it on data that reruns with the loader
+  and is read outside the boundary.
+
+`notFound()` and `redirect()` from the loader keep their path: a `redirect()`
+replaces the route's content and navigates, and the layouts keep their
+instance. Every refetch the router runs for an action follows the same rule
+(after several actions at once, after a navigation during it), and the action
+that ran it reports the loader's error as its `revalidationError`. Not
+covered yet: an `intercept()`'s loaders, and a parallel slot's loaders under
+its own `loading()`. For a failure the user should see in place of the
+data without an error boundary, return it from the loader as data
+(`{ ok: false, reason }`) and render it where the data goes. A failure
+returned as data is a value like any other, so a `cache()` on the loader (or
+a `ppr` bake, or a prerender) stores and serves it; a thrown error is never
+stored. See `/client-urls` → "A loader that fails on its rerun" for the
+details and examples.
 
 ### Authorization in actions
 

package/skills/testing/SKILL.md

@@ -155,6 +155,7 @@ beside their function):
 |                                           | `setBuildVersions`                                                                                                                                           | [`serve-shell-request.md`](./serve-shell-request.md) |
 |                                           | `assertCacheStatus`, `assertCacheDecision`, `parseCacheHeader`, `createCacheSink`, `filterCacheDecisions`                                                    | [`cache-prerender.md`](./cache-prerender.md)         |
 |                                           | `assertShellStatus`, `parseShellStatus`, `shellCacheKey`, `SHELL_STATUS_HEADER`, `assertPprReplayStatus`, `parsePprReplayStatus`, `PPR_REPLAY_STATUS_HEADER` | [`cache-prerender.md`](./cache-prerender.md)         |
+|                                           | `visitorShellCacheKey`                                                                                                                                       | [`serve-shell-request.md`](./serve-shell-request.md) |
 |                                           | `assertGeneratedRoutesMatch`, `diffGeneratedRoutes`                                                                                                          | [`reverse-and-types.md`](./reverse-and-types.md)     |
 | `@rangojs/router/testing/dom`             | `renderRoute`                                                                                                                                                | [`client-components.md`](./client-components.md)     |
 | `@rangojs/router/testing/flight`          | `renderToFlightString`, `normalizeFlight`, `assertFlightRuntimeAvailable`                                                                                    | [`flight.md`](./flight.md)                           |

package/skills/testing/client-components.md

@@ -38,7 +38,7 @@
 | `useReverse`                   | Reverse a name->pattern map to a URL; merges `useParams()` and the `mount`/`basename` prefix. |
 | `useHref`                      | Resolve an href against the mount/basename.                                                   |
 | `useMount`                     | The `include()` mount prefix (`options.mount`), else `"/"`.                                   |
-| `useNavigation`                | Navigation controller state — stays `idle` (see caveat).                                      |
+| `useNavigation`                | Navigation controller state: `loading` from a `navigate()` call to its commit, else `idle`.   |
 | `useRouter`                    | The router handle, including `.basename`.                                                     |
 | `usePathname`                  | Current committed pathname.                                                                   |
 | `useSearchParams`              | Search params from the `request` URL.                                                         |
@@ -376,14 +376,17 @@ it("dims the held price while the next product streams", async () => {
 });
 ```
 
-| Pending state                                                                                  | Under `renderRoute`                                                                                                                                            |
-| ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `useLoader().isLoading` on the reader a `transition` navigate() holds, pending seed            | Modeled: `true` on the OLD data until the promise settles, then `false` with the new data in the same commit.                                                  |
-| `transition` navigate(), settled seed (a plain value)                                          | `false`; the data swaps in the commit.                                                                                                                         |
-| navigate() without `transition`, pending seed                                                  | Urgent commit (production's cold-navigation lane): the read suspends to the nearest `<Suspense>` fallback (with none, React keeps the previous tree). No flag. |
-| `transition: { when }` returning false, or `navigate(url, { transition: false })`              | Same as without `transition`: urgent, with production's decision (`kind: "push"`; `refresh()` is `"revalidate"`). `transition: false` calls no predicate.      |
-| Production's other hold lanes (same-structure search/filter nav, fully-prefetched, optimistic) | NOT modeled — without `transition` navigate() stays urgent. Assert those at e2e.                                                                               |
-| `useNavigation().state`, `useLinkStatus().pending`, `useAction().state`                        | Stay `idle` — navigate() never starts the navigation lifecycle. e2e.                                                                                           |
+| Pending state                                                                                  | Under `renderRoute`                                                                                                                                                                                    |
+| ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `useLoader().isLoading` on the reader a `transition` navigate() holds, pending seed            | Modeled: `true` on the OLD data until the promise settles, then `false` with the new data in the same commit.                                                                                          |
+| `transition` navigate(), settled seed (a plain value)                                          | `false`; the data swaps in the commit.                                                                                                                                                                 |
+| navigate() without `transition`, pending seed                                                  | Urgent commit (production's cold-navigation lane): the read suspends to the nearest `<Suspense>` fallback (with none, React keeps the previous tree). No flag.                                         |
+| `transition: { when }` returning false, or `navigate(url, { transition: false })`              | Same as without `transition`: urgent, with production's decision (`kind: "push"`; `refresh()` is `"revalidate"`). `transition: false` calls no predicate.                                              |
+| Production's other hold lanes (same-structure search/filter nav, fully-prefetched, optimistic) | NOT modeled — without `transition` navigate() stays urgent. Assert those at e2e.                                                                                                                       |
+| `useNavigation().state`, `useLinkStatus().pending`                                             | Modeled: navigate() starts the navigation as a click does. `loading` from the call, `idle` in the commit, held with it; `pending` true for the destination's link until the commit is handed to React. |
+| `useAction().state`                                                                            | Stays `idle`: navigate() runs no action. e2e.                                                                                                                                                          |
+| `useHandle()` on a held navigation, `navigate(url, { handles, loaders })`                      | Modeled: `handles` arrive on the response's handle stream, so readers keep the page being left's values while React holds the page and take the new ones with its commit.                              |
+| A back/forward restored from the history cache (its view transition, `pop`)                    | NOT modeled: the tree has one location and navigate() caches no entries, so a `popstate` restores nothing. Assert it at e2e.                                                                           |
 
 - Per-navigation seeds merge over the render-time `loaders`/`loaderData` for THAT navigation only; a later `navigate()` without `loaders` falls back to the render-time data.
 - Pass settled data as a plain value, not `Promise.resolve(value)`: React has not observed a plain promise yet, so it counts as pending and renders one `stale` frame. (A Flight chunk that has already settled carries its status and is skipped, which a plain value mirrors.)
@@ -392,7 +395,7 @@ it("dims the held price while the next product streams", async () => {
 ## Caveats
 
 - Client tree ONLY. Does NOT catch server/client boundary reference-identity remount bugs, real Flight serialization errors, loader execution, middleware, or handler ordering — those are `renderServerTree` / `renderHandler` / e2e territory. Loader data is SEEDED, never run. `hydrate: true` adds an HTML pass of this same client tree ([Hydration](#hydration)), not a render of your routes on a server.
-- `router.navigate()` bypasses the navigation lifecycle, so the controller never leaves `idle`. `useNavigation()` / `useLinkStatus()` / `useAction()` non-idle states (loading/streaming/pending, action result/error) are NOT reachable — test those at e2e. The one modeled pending state is held-navigation `useLoader().isLoading` ([Held navigation](#held-navigation)).
+- `router.navigate()` drives the navigation lifecycle: `useNavigation()` reads `loading` from the call and `idle` in the commit, held with it for a `transition` spec ([Held navigation](#held-navigation)). `useAction()` non-idle states (action loading/streaming, result/error) are NOT reachable — no action runs; test those at e2e.
 - `outletPending` seeds only the production-shaped outlet context. It is useful
   for the two settled render states of a layout that reads `useOutlet()`, but it
   does not prove the hydrated `clientUrls()` transition that toggles the value;

package/skills/testing/loader.md

@@ -8,29 +8,30 @@
 
 ### Options — `RunLoaderOptions<TEnv>`
 
-| Field           | Type                                                            | Meaning                                                                                                                                                                                                                    |
-| --------------- | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `params`        | `Record<string, string>`                                        | Route params; surfaced as `ctx.params` and `ctx.routeParams`.                                                                                                                                                              |
-| `search`        | `Record<string, string>`                                        | Search params; merged into the request URL so `ctx.searchParams` reflects them.                                                                                                                                            |
-| `searchData`    | `Record<string, unknown>`                                       | The TYPED `ctx.search` object a route's search schema would produce. Distinct from `search` (which sets the raw `ctx.searchParams`).                                                                                       |
-| `basename`      | `string`                                                        | Router basename surfaced on the context; drives `redirect()` prefixing.                                                                                                                                                    |
-| `theme`         | `ThemeConfig \| true`                                           | Theme config in the `createRouter({ theme })` shape (e.g. `true` or `{ themes: [...] }`). Without it `ctx.theme`/`ctx.setTheme` are inert.                                                                                 |
-| `env`           | `TEnv`                                                          | Environment bindings surfaced as `ctx.env`.                                                                                                                                                                                |
-| `request`       | `Request \| string`                                             | Override the backing Request. Defaults to a localhost GET.                                                                                                                                                                 |
-| `vars`          | `VarsInit`                                                      | Variables a prior middleware would have set (object `{ key: value }`, or `[key, value]` tuples where the key may be a `createVar()` handle).                                                                               |
-| `routeMap`      | `Record<string, string>`                                        | Route name -> pattern map enabling `ctx.reverse()`.                                                                                                                                                                        |
-| `routeName`     | `string`                                                        | Matched route name for scoped `.name` reverse resolution.                                                                                                                                                                  |
-| `method`        | `string`                                                        | HTTP method surfaced as `ctx.method`. Defaults to `"GET"`.                                                                                                                                                                 |
-| `body`          | `unknown`                                                       | Request body surfaced as `ctx.body`.                                                                                                                                                                                       |
-| `formData`      | `FormData`                                                      | Form data surfaced as `ctx.formData` (exposed verbatim; no multipart parsing).                                                                                                                                             |
-| `loaders`       | `ReadonlyArray<readonly [LoaderDefinition<any, any>, unknown]>` | Seed `ctx.use(OtherLoader)` by REFERENCE as `[[OtherLoader, data]]` tuples (same shape as `renderHandler`/`renderRoute`). Checked before `use`.                                                                            |
-| `use`           | `UseResolver`                                                   | Dynamic resolver for `ctx.use(OtherLoader)` composition. `loaders` wins when both match.                                                                                                                                   |
-| `cacheStore`    | `SegmentCacheStore`                                             | Cache store backing `use cache` functions. Without one, a cached function bypasses and runs uncached (its taint/profile guards never fire).                                                                                |
-| `cacheProfiles` | `Record<string, CacheProfile>`                                  | Cache profiles, the `createRouter({ cacheProfiles })` shape.                                                                                                                                                               |
-| `cache`         | `PartialCacheOptions`                                           | Run the loader through the `cache()` a route binds it with (`loader(Loader, () => [cache({...})])` takes the same options), against `cache.store`, else `cacheStore`. See the caveat below.                                |
-| `stateCookie`   | `StateCookieSeed` (`{ prefix?, routerId?, version? }`)          | Customize the rango state cookie a loader calling `invalidateClientCache()` rotates (the name is always seeded — default `rango-state_router_0`).                                                                          |
-| `rendered`      | `boolean \| (() => void \| Promise<void>)`                      | Mock the `ctx.rendered()` render barrier so a loader that `await ctx.rendered()`s can be unit-tested. By default `ctx.rendered()` throws. `true` resolves immediately; a function controls timing/side effects.            |
-| `handles`       | `ReadonlyArray<readonly [Handle<any, any>, unknown]>`           | Seed the values `ctx.get(SomeHandle)` returns — the ACCUMULATED handle data read after `await ctx.rendered()`. Matched by handle reference. (Loader handle WRITES need no seed — see `runLoaderResult(...).handlePushes`.) |
+| Field           | Type                                                            | Meaning                                                                                                                                                                                                                                            |
+| --------------- | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `params`        | `Record<string, string>`                                        | Route params; surfaced as `ctx.params` and `ctx.routeParams`.                                                                                                                                                                                      |
+| `search`        | `Record<string, string>`                                        | Search params; merged into the request URL so `ctx.searchParams` reflects them.                                                                                                                                                                    |
+| `searchData`    | `Record<string, unknown>`                                       | The TYPED `ctx.search` object a route's search schema would produce. Distinct from `search` (which sets the raw `ctx.searchParams`).                                                                                                               |
+| `basename`      | `string`                                                        | Router basename surfaced on the context; drives `redirect()` prefixing.                                                                                                                                                                            |
+| `theme`         | `ThemeConfig \| true`                                           | Theme config in the `createRouter({ theme })` shape (e.g. `true` or `{ themes: [...] }`). Without it `ctx.theme`/`ctx.setTheme` are inert.                                                                                                         |
+| `env`           | `TEnv`                                                          | Environment bindings surfaced as `ctx.env`.                                                                                                                                                                                                        |
+| `request`       | `Request \| string`                                             | Override the backing Request. Defaults to a localhost GET.                                                                                                                                                                                         |
+| `vars`          | `VarsInit`                                                      | Variables a prior middleware would have set (object `{ key: value }`, or `[key, value]` tuples where the key may be a `createVar()` handle).                                                                                                       |
+| `routeMap`      | `Record<string, string>`                                        | Route name -> pattern map enabling `ctx.reverse()`.                                                                                                                                                                                                |
+| `routeName`     | `string`                                                        | Matched route name for scoped `.name` reverse resolution.                                                                                                                                                                                          |
+| `declaredIn`    | `string`                                                        | Include name prefix of the module whose `layout()` / `parallel()` / `cache()` declares the loader (`"account"`, `""` for the root module). `.name` then resolves in that module, as such a loader does in production, instead of from `routeName`. |
+| `method`        | `string`                                                        | HTTP method surfaced as `ctx.method`. Defaults to `"GET"`.                                                                                                                                                                                         |
+| `body`          | `unknown`                                                       | Request body surfaced as `ctx.body`.                                                                                                                                                                                                               |
+| `formData`      | `FormData`                                                      | Form data surfaced as `ctx.formData` (exposed verbatim; no multipart parsing).                                                                                                                                                                     |
+| `loaders`       | `ReadonlyArray<readonly [LoaderDefinition<any, any>, unknown]>` | Seed `ctx.use(OtherLoader)` by REFERENCE as `[[OtherLoader, data]]` tuples (same shape as `renderHandler`/`renderRoute`). Checked before `use`.                                                                                                    |
+| `use`           | `UseResolver`                                                   | Dynamic resolver for `ctx.use(OtherLoader)` composition. `loaders` wins when both match.                                                                                                                                                           |
+| `cacheStore`    | `SegmentCacheStore`                                             | Cache store backing `use cache` functions. Without one, a cached function bypasses and runs uncached (its taint/profile guards never fire).                                                                                                        |
+| `cacheProfiles` | `Record<string, CacheProfile>`                                  | Cache profiles, the `createRouter({ cacheProfiles })` shape.                                                                                                                                                                                       |
+| `cache`         | `PartialCacheOptions`                                           | Run the loader through the `cache()` a route binds it with (`loader(Loader, () => [cache({...})])` takes the same options), against `cache.store`, else `cacheStore`. See the caveat below.                                                        |
+| `stateCookie`   | `StateCookieSeed` (`{ prefix?, routerId?, version? }`)          | Customize the rango state cookie a loader calling `invalidateClientCache()` rotates (the name is always seeded — default `rango-state_router_0`).                                                                                                  |
+| `rendered`      | `boolean \| (() => void \| Promise<void>)`                      | Mock the `ctx.rendered()` render barrier so a loader that `await ctx.rendered()`s can be unit-tested. By default `ctx.rendered()` throws. `true` resolves immediately; a function controls timing/side effects.                                    |
+| `handles`       | `ReadonlyArray<readonly [Handle<any, any>, unknown]>`           | Seed the values `ctx.get(SomeHandle)` returns — the ACCUMULATED handle data read after `await ctx.rendered()`. Matched by handle reference. (Loader handle WRITES need no seed — see `runLoaderResult(...).handlePushes`.)                         |
 
 ### Context — `TestLoaderContext<TEnv>` (what your loader receives)
 
@@ -116,7 +117,7 @@ it("asserts a loader's set-cookie + redirect (runLoaderResult)", async () => {
 
 ## Caveats
 
-- `ctx.reverse(...)` throws unless you pass `routeMap` (and `routeName` for scoped `.name` resolution). It does NOT fall back to the global route map.
+- `ctx.reverse(...)` throws unless you pass `routeMap` (and `routeName` for scoped `.name` resolution, or `declaredIn` for a layout's or parallel's loader). It does NOT fall back to the global route map.
 - `ctx.rendered()` throws by default (the render barrier only exists in a full match); pass `{ rendered: true }` to mock it for post-barrier logic, and `{ handles: [[SomeHandle, data]] }` to seed the `ctx.get(SomeHandle)` read.
 - A loader has no `isAction()`: whether it re-runs after an action is decided by `revalidate()` on its registration, not inside the loader body. Assert post-action re-runs at e2e.
 - Seeded `loaders` (by-reference tuples) are NOT executed — `ctx.use(OtherLoader)` returns the seeded value. The dynamic `use` resolver, by contrast, IS executed (it is a function called to compute the value). Either way the REAL loader body is not run; real loader execution and side-effects are e2e-only. `loaders` is checked before the `use` resolver.

package/skills/testing/middleware.md

@@ -44,17 +44,17 @@ The `ctx` your middleware reads. Notable fields:
 
 ### Returns — `RunMiddlewareResult<TEnv>`
 
-| Field             | Type                      | Meaning                                                                                                                                                                                                                                                                     |
-| ----------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `response`        | `Response`                | The final Response: the downstream response, or a middleware short-circuit.                                                                                                                                                                                                 |
-| `ctx`             | `RequestContext<TEnv>`    | The underlying RequestContext (NOT a per-middleware `MiddlewareContext`). Use `ctx.get(...)` for anything the envelope above doesn't surface.                                                                                                                               |
-| `nextCalled`      | `number`                  | Times the terminal handler ran: `0` on short-circuit, `1` on pass-through.                                                                                                                                                                                                  |
-| `rewrite`         | `RunMiddlewareRewrite?`   | The target of a `throw rewrite(...)`: `{ pathname, search, routeName? }`, resolved as production resolves it (a path basename-prefixed, a name through `routeMap`). `undefined` when nothing rewrote. On a rewrite, `response` carries what the chain set before the throw. |
-| `dynamic`         | `boolean`                 | Whether the chain called `ctx.dynamic()` (the PPR shell opt-out).                                                                                                                                                                                                           |
-| `cookies`         | `Record<string, string>`  | Effective cookie view: request cookies merged with chain sets/deletes (last-write-wins), as `{ name: value }`.                                                                                                                                                              |
-| `headers`         | `Record<string, string>`  | Final response headers as `{ name: value }`, lowercased, EXCLUDING `set-cookie` (use `cookies`).                                                                                                                                                                            |
-| `locationState`   | `Record<string, unknown>` | Flat `{ key: value }` state set via `setLocationState()` / `redirect({ state })` (empty when none).                                                                                                                                                                         |
-| `stateCookieName` | `string`                  | The resolved rango state cookie name seeded for the run (default `rango-state_router_0`). Assert a middleware's `invalidateClientCache()` rotation against it without recomputing — parity with `runInRequestContext` / `runLoaderResult` / `renderHandler`.                |
+| Field             | Type                      | Meaning                                                                                                                                                                                                                                                                                                                                                                           |
+| ----------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `response`        | `Response`                | The final Response: the downstream response, or a middleware short-circuit.                                                                                                                                                                                                                                                                                                       |
+| `ctx`             | `RequestContext<TEnv>`    | The underlying RequestContext (NOT a per-middleware `MiddlewareContext`). Use `ctx.get(...)` for anything the envelope above doesn't surface.                                                                                                                                                                                                                                     |
+| `nextCalled`      | `number`                  | Times the terminal handler ran: `0` on short-circuit, `1` on pass-through.                                                                                                                                                                                                                                                                                                        |
+| `rewrite`         | `RunMiddlewareRewrite?`   | The target of a `throw rewrite(...)`: `{ pathname, search, routeName?, mutationsDisallowed? }` (`mutationsDisallowed: true` only for `.disallowMutations()`, absent otherwise), resolved as production resolves it (a path basename-prefixed, a name through `routeMap`). `undefined` when nothing rewrote. On a rewrite, `response` carries what the chain set before the throw. |
+| `dynamic`         | `boolean`                 | Whether the chain called `ctx.dynamic()` (the PPR shell opt-out).                                                                                                                                                                                                                                                                                                                 |
+| `cookies`         | `Record<string, string>`  | Effective cookie view: request cookies merged with chain sets/deletes (last-write-wins), as `{ name: value }`.                                                                                                                                                                                                                                                                    |
+| `headers`         | `Record<string, string>`  | Final response headers as `{ name: value }`, lowercased, EXCLUDING `set-cookie` (use `cookies`).                                                                                                                                                                                                                                                                                  |
+| `locationState`   | `Record<string, unknown>` | Flat `{ key: value }` state set via `setLocationState()` / `redirect({ state })` (empty when none).                                                                                                                                                                                                                                                                               |
+| `stateCookieName` | `string`                  | The resolved rango state cookie name seeded for the run (default `rango-state_router_0`). Assert a middleware's `invalidateClientCache()` rotation against it without recomputing — parity with `runInRequestContext` / `runLoaderResult` / `renderHandler`.                                                                                                                      |
 
 ## Recipe
 

package/skills/testing/response-routes.md

@@ -4,6 +4,8 @@
 
 `dispatch` runs the router's REAL matching (reusing `previewMatch`) and the real global + route-level middleware chain, with no RSC render — so redirects, 404s, response routes, content negotiation, and middleware short-circuits behave exactly as in production. You SEED the request and `env`; everything else (matching, middleware, header/cookie merge) is real machinery.
 
+Matching goes through the route trie, as every request in `vite dev` and production does.
+
 ## API
 
 ### Options — `DispatchOptions<TEnv>`
@@ -78,7 +80,7 @@ describe("api routes via dispatch", () => {
 
 `dispatch` also covers, with production code paths:
 
-- trailing-slash/redirect targets (`findMatch`) — a redirected path returns a 308 with the `Location` (query preserved);
+- trailing-slash redirects from the trie — a route with `trailingSlash: "never"` or `"always"` answers the other form with a 308 and the `Location` (query preserved). A route with no `trailingSlash` serves its URL with and without a trailing slash, with no redirect, as production does;
 - the open-redirect guard on browser-followed redirects (a cross-origin `Location` is rewritten to the basename root unless `redirect(url, { external: true })`);
 - content-negotiated routes (`Vary: Accept` appended);
 - cached response routes (`cache({ ... })` around a `path.json` etc.): hit, SWR, and tag writes. The cache write is scheduled via `waitUntil` (a microtask in tests), so flush microtasks between the seeding `dispatch` and the one that asserts the hit;
@@ -90,6 +92,7 @@ describe("api routes via dispatch", () => {
 - A COMPONENT route's guard stack cannot run here. Assert it at e2e, or extract the middleware fn and unit-test it with `runMiddleware` (see `./middleware.md`).
 - JSON serialization is bare, applied in `response-route-handler.ts`: a `path.json` handler that returns a value is serialized verbatim (`JSON.stringify(value)`, status 200, `application/json`) — no envelope. Returning or throwing a `Response` (e.g. `Response.json(x)`) uses the same control-flow path. Any other thrown error takes the error's status (`RouterError.status`, else 500, or a non-200 status already set upstream in the request pipeline). On a `path.json` route the body is an RFC 9457 problem+json object `{ title, status, detail, code }` (`application/problem+json;charset=utf-8`), where `code` is the `RouterError.code`, else `"INTERNAL"`, and the `type` member is omitted. On text/html/xml/md routes the body is `text/plain`: the `RouterError` message, the error message in dev, or `"Internal Server Error"` in production. Assert the shape matching what your handler returns.
 - Setup: needs the preset (alias + virtual stubs) or a Vite-RSC env (see `./setup.md`); a bare router import throws on Vite virtuals.
+- Building the trie runs route discovery: every `include()`d `urls()` handler runs once more, and every async include provider (`() => import(...)`) is called. Count provider calls or handler runs after the first `dispatch` on that router, not from router construction. A provider that rejects fails the `dispatch`, as it fails `vite dev` and the build.
 - A router using `Prerender()`/`createLoader()`/`Static()` now constructs in a bare test (each assigns a runtime fallback `$$id`). Importing the whole router _file_ may still need the plugin (its page modules pull app deps / `virtual:` modules) — build from a focused include (your API routes) for whole-router dispatch.
 - A `throw rewrite(target)` from global or route middleware re-dispatches as the router does: global middleware matched on the target's path, the target's route middleware and handler, the same request context, `x-rango-rewrite` on the response, 508 on a loop. The visitor's URL is matched before middleware runs, so it must be a response route (or a redirect or 404) too; a rewrite target that is a component route throws the same error as a direct request.
 - A `_rsc_partial` request to a response route runs global middleware first (an auth gate can still 401/redirect), then returns `X-RSC-Reload` — route-level middleware is skipped, exactly like production.