@rangojs/router 0.0.0-experimental.79 → 0.0.0-experimental.7c7e4327

package/skills/react-compiler/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: react-compiler
+description: Enable the React Compiler in a Rango app the @vitejs/plugin-rsc way — a separate @rolldown/plugin-babel running reactCompilerPreset(), ordered after react() and before the plugin that supplies @vitejs/plugin-rsc. Use when a consumer wants to turn React Compiler on, hits the dead plugin-react v6 `react({ babel })` path, or is unsure why server components aren't being compiled.
+argument-hint:
+---
+
+# React Compiler
+
+React Compiler is **opt-in** in Rango. The plugin pipeline is fully compatible —
+you just add one more plugin. The catch on a current Rango stack (Vite 8 +
+`@vitejs/plugin-react` v6) is that **v6 dropped its internal Babel for oxc**, so
+the way the React docs and most blog posts show it — `react({ babel: { plugins:
+[...] } })` — silently does nothing. The compiler has to be its own top-level
+plugin.
+
+## The shape (read first)
+
+- The compiler is a **Babel** plugin, run via
+  [`@rolldown/plugin-babel`](https://www.npmjs.com/package/@rolldown/plugin-babel)
+  with `reactCompilerPreset()` from `@vitejs/plugin-react`.
+- **Ordering is load-bearing:** put `babel(...)` **after `react()`** and
+  **before the plugin that supplies `@vitejs/plugin-rsc`**. In a default Rango
+  app that plugin is `rango()` itself; in a Cloudflare app it is
+  `@cloudflare/vite-plugin`.
+- **It is client-only.** `reactCompilerPreset()` gates itself to the client
+  environment. Server/RSC components are not compiled, and that is the upstream
+  example's behavior — not a Rango limitation. See
+  [What gets compiled](#what-gets-compiled-client-only).
+- **Rango's build-time prerender is unaffected.** You do not need to do anything
+  special. See [Prerender](#interaction-with-build-time-prerender).
+
+## Step 1: Install
+
+```bash
+pnpm add -D @rolldown/plugin-babel @babel/core babel-plugin-react-compiler
+# TypeScript users also want the Babel core types:
+pnpm add -D @types/babel__core
+```
+
+React 19 ships `react/compiler-runtime` in-tree, so there is **no** extra runtime
+to install and **no** `target` option to set. Only pass `target: '17' | '18'` to
+`reactCompilerPreset()` if you are on an older React.
+
+## Step 2: Wire it in
+
+### Default (non-Cloudflare) app
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import react, { reactCompilerPreset } from "@vitejs/plugin-react";
+import babel from "@rolldown/plugin-babel";
+import { rango } from "@rangojs/router/vite";
+
+export default defineConfig({
+  plugins: [
+    react(),
+    babel({ presets: [reactCompilerPreset()] }),
+    rango(), // supplies @vitejs/plugin-rsc
+  ],
+});
+```
+
+### Cloudflare app
+
+```ts
+// vite.config.ts
+import { cloudflare } from "@cloudflare/vite-plugin";
+import react, { reactCompilerPreset } from "@vitejs/plugin-react";
+import babel from "@rolldown/plugin-babel";
+import { defineConfig } from "vite";
+import { rango } from "@rangojs/router/vite";
+
+export default defineConfig({
+  plugins: [
+    react(),
+    babel({ presets: [reactCompilerPreset()] }),
+    rango({ preset: "cloudflare" }),
+    cloudflare({
+      /* ... */
+    }), // supplies @vitejs/plugin-rsc
+  ],
+});
+```
+
+## What gets compiled (client-only)
+
+`reactCompilerPreset()` carries
+`rolldown.applyToEnvironmentHook: (env) => env.config.consumer === "client"`, so
+even though the babel plugin is top-level, the transform runs **only in the
+`client` environment**:
+
+| Environment | `consumer` | Compiled? |
+| ----------- | ---------- | --------- |
+| client      | `client`   | Yes       |
+| ssr         | `server`   | No        |
+| rsc         | `server`   | No        |
+
+This matches the upstream `@vitejs/plugin-rsc` example. If you genuinely need to
+compile **server** components, you would have to invoke
+`babel-plugin-react-compiler` yourself without the preset's
+`applyToEnvironmentHook` — that is outside what the example does and is not
+covered here.
+
+## Options
+
+`reactCompilerPreset()` forwards to `babel-plugin-react-compiler`:
+
+| Option                          | Effect                                                                                 |
+| ------------------------------- | -------------------------------------------------------------------------------------- |
+| `compilationMode: 'annotation'` | Compile only components marked with the `"use memo"` directive, not every eligible one |
+| `target: '17' \| '18'`          | Emit `react-compiler-runtime` calls for React < 19. Omit on React 19+.                 |
+
+## Interaction with build-time prerender
+
+Nothing to configure. Rango's discovery/prerender step runs a throwaway temp Vite
+server (`createTempRscServer`) that forwards only your **resolution** plugins
+(`resolveId` / `load`). A pure transform plugin like `@rolldown/plugin-babel` is
+intentionally **not** forwarded — and that is correct: the temp runner only
+produces **data** (serialized Flight payloads + the route manifest), not shipped
+code, and React Compiler is a memoization-only transform that does not change
+rendered output. Your shipped client bundle still gets compiled, because the
+babel plugin lives in your app's top-level plugin array alongside `react()`.
+
+## Step 3: Verify the compiler actually ran
+
+A compiled module imports the cache allocator from `react/compiler-runtime` and
+calls `_c(n)`. Those two appear in **every** compiled module, so they are the
+reliable per-module signal in dev:
+
+```bash
+pnpm dev
+# fetch any client component module straight from Vite and look for the markers:
+curl -s "http://localhost:5173/src/components/SomeClientComponent.tsx" \
+  | grep -E "compiler-runtime|_c\("
+```
+
+For a production build, grep the built client bundle for the compiler's
+input-independent cache check, which has a **zero baseline** without the compiler:
+
+```bash
+pnpm build
+grep -r "Symbol.for(\"react.memo_cache_sentinel\")" dist/client/assets/ | head
+```
+
+Note the **comparison** form `$[i] === Symbol.for("react.memo_cache_sentinel")`
+is only emitted for components with input-independent JSX, so it is reliable over
+the **whole** client bundle, not necessarily in one chosen module. (React core
+also defines that symbol once with a single `=` assignment, so count comparisons,
+not the bare string.) Run the same grep over `dist/rsc` / `dist/ssr` and you
+should find **none** — that is the client-only contract.
+
+## Troubleshooting
+
+| Symptom                                                               | Cause / fix                                                                                                                                 |
+| --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| Nothing is compiled; no `compiler-runtime` import anywhere            | You used `react({ babel: { plugins: [...] } })`. plugin-react v6 has no internal Babel — add `@rolldown/plugin-babel` as its own plugin.    |
+| Client compiled, but server/RSC components are not                    | Expected. `reactCompilerPreset()` is client-only (see the table). Not a bug.                                                                |
+| `Cannot find module 'babel-plugin-react-compiler'` (or `@babel/core`) | Install the peer deps from Step 1; they are not bundled by `reactCompilerPreset()`.                                                         |
+| Build pulls in `react-compiler-runtime`                               | You set `target: '17'`/`'18'` on React 19. Drop `target` — React 19 ships `react/compiler-runtime` in-tree.                                 |
+| Output looks compiled but a component misbehaves                      | The component likely breaks the Rules of React. Fix the component, or scope the compiler with `compilationMode: 'annotation'` while you do. |
+
+## Reference
+
+A worked, tested wiring (dev + production e2e markers, incl. the client-only
+contract) lives in the `@rangojs/router` repo: `docs/react-compiler.md` and the
+`react-compiler.test.ts` files under `e2e/e2e-basic`, `tests/cloudflare-basic`,
+and `tests/vite-rsc-demo`.

package/skills/response-routes/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: response-routes
-description: Response routes (path.json, path.text, etc.) for non-RSC endpoints with typed responses
+description: Response routes (path.json, path.text, etc.) for non-RSC endpoints with typed responses. Use when building a JSON/text API endpoint alongside your pages, or asking how to return raw JSON instead of RSC from a route.
 argument-hint: [json|text|html|xml|md|image|stream]
 ---
 
@@ -68,16 +68,16 @@ export const urlpatterns = urls(({ path, layout, include }) => [
 
 ## Available Tags
 
-| Tag      | Usage           | Handler returns    | Auto-wrap                |
-| -------- | --------------- | ------------------ | ------------------------ |
-| `json`   | `path.json()`   | plain object/array | `{ data: T }` envelope   |
-| `text`   | `path.text()`   | string             | text/plain Response      |
-| `html`   | `path.html()`   | string             | text/html Response       |
-| `xml`    | `path.xml()`    | string             | application/xml Response |
-| `md`     | `path.md()`     | string             | text/markdown Response   |
-| `image`  | `path.image()`  | Response           | pass-through             |
-| `stream` | `path.stream()` | Response           | pass-through             |
-| `any`    | `path.any()`    | Response           | pass-through             |
+| Tag      | Usage           | Handler returns    | Auto-wrap                     |
+| -------- | --------------- | ------------------ | ----------------------------- |
+| `json`   | `path.json()`   | plain object/array | bare JSON value (no envelope) |
+| `text`   | `path.text()`   | string             | text/plain Response           |
+| `html`   | `path.html()`   | string             | text/html Response            |
+| `xml`    | `path.xml()`    | string             | application/xml Response      |
+| `md`     | `path.md()`     | string             | text/markdown Response        |
+| `image`  | `path.image()`  | Response           | pass-through                  |
+| `stream` | `path.stream()` | Response           | pass-through                  |
+| `any`    | `path.any()`    | Response           | pass-through                  |
 
 ## ResponseHandlerContext
 
@@ -139,22 +139,31 @@ path.json(
 );
 ```
 
-## JSON Envelope
+## JSON Wire Shape
 
-`path.json()` handlers return plain data. The framework auto-wraps it
-in a `ResponseEnvelope<T>` discriminated union:
+`path.json()` handlers return plain data. The framework serializes the handler's
+return value **verbatim** (no envelope) on success, and an RFC 9457 `problem+json`
+body on error. Discriminate with `res.ok` / the HTTP status — there is no in-body
+`data`/`error` union:
 
 ```typescript
-// Success: HTTP 200
-{ "data": { "status": "ok", "timestamp": 1700000000 } }
-
-// Error: HTTP 404 (or whatever status RouterError specifies)
-{ "error": { "message": "Product 999 not found", "code": "NOT_FOUND" } }
+// Success: HTTP 200, content-type application/json
+{ "status": "ok", "timestamp": 1700000000 }
+
+// Error: HTTP 404 (or whatever status RouterError specifies),
+//        content-type application/problem+json
+{
+  "title": "Not Found",
+  "status": 404,
+  "detail": "Product 999 not found",
+  "code": "NOT_FOUND"
+  // "stack": included in development only
+}
 ```
 
 ### Error Handling with RouterError
 
-Throw `RouterError` to return structured error envelopes:
+Throw `RouterError` to return a structured `problem+json` body:
 
 ```typescript
 import { RouterError } from "@rangojs/router";
@@ -199,25 +208,27 @@ path.json(
 
 ## Client-Side Type Safety
 
-### ResponseEnvelope and isResponseError
+### Discriminating success vs. error with res.ok
+
+Success bodies are the bare value; error bodies are RFC 9457 `ProblemDetails`.
+Branch on `res.ok` (or the HTTP status) — not an in-body union:
 
 ```typescript
 "use client";
-import type { ResponseEnvelope, ResponseError } from "@rangojs/router/client";
-import { isResponseError } from "@rangojs/router/client";
+import type { ProblemDetails } from "@rangojs/router";
 
 // Fetch a typed response
 const res = await fetch("/api/products/1");
-const result: ResponseEnvelope<Product> = await res.json();
 
-if (isResponseError(result)) {
-  // result.error: ResponseError  (message, code?, type?)
-  // result.data: undefined
-  console.error(result.error.message);
+if (!res.ok) {
+  // Error body: application/problem+json
+  const problem: ProblemDetails = await res.json();
+  // problem.detail: string, problem.code: string, problem.status: number
+  console.error(problem.code, problem.detail);
 } else {
-  // result.data: Product
-  // result.error: undefined
-  console.log(result.data.name);
+  // Success body: the bare value (no envelope)
+  const product: Product = await res.json();
+  console.log(product.name);
 }
 ```
 
@@ -230,32 +241,82 @@ import type { RouteResponse } from "@rangojs/router";
 
 // From the apiPatterns module (before include)
 type HealthData = RouteResponse<typeof apiPatterns, "health">;
-// = ResponseEnvelope<{ status: string; timestamp: number }>
+// = { status: string; timestamp: number }
 
 type ProductsData = RouteResponse<typeof apiPatterns, "products">;
-// = ResponseEnvelope<{ id: string; name: string; price: number }[]>
+// = { id: string; name: string; price: number }[]
 ```
 
-### PathResponse (global lookup by URL pattern)
+`RouteResponse` is the bare success payload (the JSON wire shape) — the same value
+a `fetch().then(r => r.json())` yields on a 2xx. Error bodies are `ProblemDetails`,
+keyed off `res.ok` at runtime, not part of this type.
+
+### Rango.PathResponse (global lookup by URL pattern or concrete path)
 
-Look up response type from the merged route map by URL pattern:
+`Rango.PathResponse` is ambient (no import) and reads from `RegisteredRoutes`,
+which carries response payload metadata. That surface is **not** auto-wired —
+without the augmentation below, `Rango.PathResponse` falls back to the generated
+path/search map, or to a permissive map when nothing is generated. Either way, it
+has no response payload metadata, so response routes resolve to `never`:
 
 ```typescript
-import type { PathResponse } from "@rangojs/router/client";
+// router.tsx
+export const router = createRouter({ document: Document }).routes(urlpatterns);
+
+declare global {
+  namespace Rango {
+    interface RegisteredRoutes extends typeof router.routeMap {}
+  }
+}
+```
 
+With that in place, look up the response type by URL pattern (ambient, no import):
+
+```typescript
 // After include("/api", apiPatterns) in main urls
-type Health = PathResponse<"/api/health">;
-// = ResponseEnvelope<{ status: string; timestamp: number }>
+type Health = Rango.PathResponse<"/api/health">;
+// = { status: string; timestamp: number }
+
+// RSC routes (no JSON payload) return never
+type Home = Rango.PathResponse<"/">;
+// = never
+```
+
+`Rango.PathResponse` also accepts a **concrete path**, so it types a `fetch`
+wrapper whose response is inferred from the path you pass:
+
+```typescript
+import { href } from "@rangojs/router/client";
 
-// RSC routes return ResponseEnvelope<never>
-type Home = PathResponse<"/">;
-// = ResponseEnvelope<never>
+async function get<T extends Rango.Path>(
+  path: T,
+): Promise<Rango.PathResponse<T>> {
+  return fetch(href(path)).then((r) => r.json());
+}
+
+const product = await get("/api/products/42"); // Product (bare value)
 ```
 
+Pattern keys (`/:id`) match exactly; a concrete path under a _nested_ dynamic
+route can match several patterns and union their responses.
+
+`Rango.PathResponse` reports the JSON **wire** shape, not the handler's raw
+return: `path.json()` serializes with `JSON.stringify`, so a handler returning
+`{ createdAt: Date }` resolves to the bare `{ createdAt: string }`. This
+runs through the ambient `Rango.JsonSerialize<T>` transform (`Date -> string`,
+honors `toJSON()`, drops functions/`undefined`, `bigint -> never`). The
+`RouteResponse` surface below applies the same `Rango.JsonSerialize` transform, so
+both response lookups report the identical wire shape.
+
+For local/scoped response typing without global augmentation, prefer
+`RouteResponse<typeof patterns, "routeName">` (see the section above) — it reads
+the response payload straight from the `urls()` patterns and needs no
+`RegisteredRoutes` wiring.
+
 ### ParamsFor with Response Routes
 
 ```typescript
-import type { ParamsFor } from "@rangojs/router/client";
+import type { ParamsFor } from "@rangojs/router";
 
 // Works for both RSC and response routes
 type ProductParams = ParamsFor<"api.productDetail">;
@@ -357,19 +418,35 @@ export const urlpatterns = urls(({ path, include }) => [
 ]);
 ```
 
+A heavy module like this is a good code-split candidate. Pass an async provider
+and the module — its handlers, response serializers, and any nested
+`include()`s — loads on the first request under the prefix instead of at startup:
+
+```typescript
+// blog/urls.tsx: `export default blogPatterns`
+include("/blog", () => import("./blog/urls"), { name: "blog" }),
+```
+
+Named routes and response types still resolve through the split: `TRoutes` and
+the `_responses` phantom are inferred from the resolved `urls()` value, so
+`Rango.PathResponse<"/blog/api/stats">` and `ctx.reverse` are unchanged. See
+`/composability`.
+
 ### Type safety after mounting
 
 ```typescript
 import type { RouteResponse } from "@rangojs/router";
-import type { PathResponse, ParamsFor } from "@rangojs/router/client";
+import type { ParamsFor } from "@rangojs/router";
 
-// Scoped (before mount) -- use the module directly
+// Scoped (before mount) -- use the module directly, no global wiring needed
 type Stats = RouteResponse<typeof blogApiPatterns, "stats">;
-// = ResponseEnvelope<{ views: number; visitors: number }>
+// = { views: number; visitors: number }
 
-// After mounting -- names get prefixed
-type BlogStats = PathResponse<"/blog/api/stats">;
-// = ResponseEnvelope<{ views: number; visitors: number }>
+// After mounting -- names get prefixed.
+// Rango.PathResponse needs `RegisteredRoutes extends typeof router.routeMap` (see above),
+// otherwise it resolves to never.
+type BlogStats = Rango.PathResponse<"/blog/api/stats">;
+// = { views: number; visitors: number }
 
 // Params work through nested includes
 type LikesParams = ParamsFor<"blog.api.likes">;
@@ -400,12 +477,24 @@ path(
 Multiple response types can share the same URL pattern. See `/mime-routes` for the
 full content negotiation API (Accept header matching, Vary: Accept, multi-variant routes).
 
+## Long-Lived Responses (SSE / WebSocket)
+
+For Server-Sent Events (`path.stream`) and WebSocket upgrades (`path.any`
+returning a 101 / `webSocket` Response), see `/streams-and-websockets`.
+Upgrade responses flow through without reconstruction; `Vary` and
+`Server-Timing` are skipped, and stub headers are applied in place on a
+best-effort basis.
+
 ## How It Works
 
 1. `path.json()` tags the route at the trie level with a MIME type
 2. `coreRequestHandler()` checks the tag before the RSC pipeline
 3. Tagged routes short-circuit: handler runs, Response is returned directly
-4. JSON routes auto-wrap return values in `{ data }` / `{ error }` envelope
+4. JSON routes serialize the return value verbatim (bare) on success; a thrown error becomes an RFC 9457 `problem+json` body (`application/problem+json`)
 5. Client-side navigation to response routes gets `X-RSC-Reload` header, triggering hard navigation
 6. Response types flow through `_responses` phantom type on `UrlPatterns`, propagated by `include()`
 7. When multiple routes share a URL pattern, the trie merges them for content negotiation (see `/mime-routes`)
+
+## Consuming response routes
+
+To call your own response-route JSON APIs from first-party TypeScript with a typed client (typed params, typed payloads inferred from the handler, no `.data`, typed `ProblemDetails` errors), see `/api-client` — a copy-paste recipe over `RouteResponse` + `ExtractParams` + a client-safe path builder. External/third-party consumers use the plain wire directly: bare JSON on success, `application/problem+json` on error.

package/skills/route/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: route
-description: Define routes with path() in @rangojs/router
+description: Define routes with path() in @rangojs/router. Use when creating a new page or route, or asking how to define a URL path and its handler.
 argument-hint: [pattern]
 ---
 
@@ -33,6 +33,69 @@ urls(({ path }) => [
 ]);
 ```
 
+### Optional URL params at runtime
+
+Absent optional params are **omitted from `ctx.params`** — `ctx.params.<name>`
+reads as `undefined`, matching the `RouteParams<"name">` type
+(`{ query?: string }`). Use `??` to default and `=== undefined` to check
+absence:
+
+```typescript
+path("/search/:query?", (ctx) => {
+  const query = ctx.params.query ?? ""; // works — undefined coalesces
+  if (ctx.params.query === undefined) return <EmptySearch />;
+  return <Results query={ctx.params.query} />;
+}, { name: "search" });
+```
+
+For the common pattern of an optional locale prefix
+(`include("/:locale?", routes)`) and the wider react-intl integration —
+locale detection, fallback chains, URL generation with absent locale —
+see `/i18n`.
+
+### Named catch-all params (`:name+` / `:name*`)
+
+A catch-all consumes the **rest of the path** and exposes it as a single
+decoded string at `ctx.params.<name>`, with the internal `/` separators kept.
+It must be the **last** segment of the pattern.
+
+- `:name+` — **one-or-more** segments (Next `[...name]`, React-Router splat).
+  `/docs/:slug+` matches `/docs/a` and `/docs/a/b/c`, but **not** the bare
+  `/docs`.
+- `:name*` — **zero-or-more** segments (Next `[[...name]]`). `/docs/:slug*`
+  additionally matches the bare `/docs`, binding `ctx.params.slug` to `""`.
+
+```typescript
+urls(({ path }) => [
+  // /shop/electronics/phones -> ctx.params.path === "electronics/phones"
+  path("/shop/:path+", ShopCatchAll, { name: "shopCatchAll" }),
+
+  // /docs         -> ctx.params.slug === ""
+  // /docs/intro   -> ctx.params.slug === "intro"
+  // /docs/a/b     -> ctx.params.slug === "a/b"
+  path("/docs/:slug*", (ctx) => {
+    const parts = ctx.params.slug === "" ? [] : ctx.params.slug.split("/");
+    return <Docs segments={parts} />;
+  }, { name: "docs" }),
+]);
+```
+
+`ctx.params.<name>` is always a `string` for a catch-all (never `undefined`) —
+`:name*` binds `""` for the empty case, so read it directly. `reverse()` /
+`ctx.reverse()` rebuild the URL with separators preserved:
+`reverse("docs", { slug: "a/b" })` -> `/docs/a/b`.
+
+The value is the URL-decoded remainder. `split("/")` recovers the segments in the
+common case, but note that a segment containing an encoded slash (`%2F`) decodes
+to a literal `/` and is therefore indistinguishable from a separator — the same
+trade-off the bare `*` splat has. If you need to distinguish those, match on the
+raw pathname instead.
+
+The bare unnamed wildcard `path("/files/*", …)` still works and is read at
+`ctx.params["*"]`; prefer a named catch-all when you want a typed param key.
+Combining a modifier with `?`, a literal suffix, or a constraint
+(`:slug*?`, `:slug*.html`, `:slug(a|b)+`) is rejected at build time.
+
 ## Route Handler Patterns
 
 ### Component Function
@@ -134,6 +197,13 @@ first. Use `ctx.set(key, value)` to share data with children, who read it
 via `ctx.get(key)`. Caching wraps all segments together, so either all run
 or none do.
 
+This pattern is also safe under partial action revalidation: on an action,
+the route entry re-runs as a unit by default — route segment, loaders, and
+`belongsToRoute` children (orphan layouts, entry parallels) all seed
+revalidate-true, with handler-first ordering preserved. Handler-set data
+stays consistent with no configuration. See `/rango` → "Passing data down
+the tree" for the safest-first ladder.
+
 ### Typed context variables with createVar
 
 Use `createVar<T>()` to create a typed token for `ctx.set()`/`ctx.get()`.
@@ -214,14 +284,33 @@ Cacheable vars (the default) can be read freely inside cache scopes.
 
 ### Revalidation Contracts for Handler Data
 
-Handler-first guarantees apply within a single full render pass. For partial
-action revalidation, define named revalidation contracts and reuse them on both
-the producer route and the consumer child segments.
+> **Scope: `revalidate()` is a partial-render concern, not a cache concern.**
+> It decides whether this segment re-runs and streams to the client on a
+> navigation or action — never whether a cached value is stale. The cache
+> decides hit/miss/ttl/swr independently and never reads `revalidate()`. See
+> `/cache-guide` → "Two axes" and `/rango` → "The shape of rango".
+
+With no `revalidate()` configured, an entry needs no contract: on an action
+the route handler and its children re-run together by default, so handler
+data stays consistent on its own. Contracts matter in two cases:
+
+1. **You narrow the entry's revalidation** with a predicate that can return a
+   hard `false` (e.g. bare `ctx.isAction(X)`). A hard `false` on one side of a
+   producer/consumer pair desyncs it — the child re-runs by default and reads
+   `undefined`, or vice versa. Put the same named contract on the route and
+   its dependent children so they narrow together.
+2. **The producer is an outer entry** (a standalone `layout()` above this
+   route). Outer entries skip action revalidation by default, so the shared
+   contract is mandatory — see `/layout` → "Revalidation Contracts".
 
 ```typescript
 // revalidation-contracts.ts
-export const revalidateCheckoutData = ({ actionId }) =>
-  actionId?.includes("src/actions/checkout.ts#") ?? false;
+import * as CheckoutActions from "./actions/checkout";
+
+// Defer (|| undefined), not ?? false: a hard `false` short-circuits the chain,
+// so when the same segment composes multiple contracts the later ones never run.
+export const revalidateCheckoutData = (ctx) =>
+  ctx.isAction(CheckoutActions) || undefined;
 
 path("/checkout", CheckoutPage, { name: "checkout" }, () => [
   revalidate(revalidateCheckoutData), // producer (route handler) reruns
@@ -250,9 +339,6 @@ path("/checkout", CheckoutPage, { name: "checkout" }, () => [
 ]);
 ```
 
-For scope/revalidation guarantees and non-guarantees, see:
-[docs/execution-model.md](../../docs/internal/execution-model.md)
-
 ## Redirects
 
 ### Basic redirect
@@ -269,6 +355,12 @@ path("/old-page", () => redirect("/new-page"), { name: "oldPage" });
 path("/moved", () => redirect("/new-location", 301), { name: "moved" });
 ```
 
+> **Redirecting from a route with `loading()`:** an `async` handler that returns
+> a `Response`/`redirect()` on a route that also declares `loading()` is streamed,
+> so the redirect is rendered into the RSC stream instead of becoming an HTTP
+> redirect. Issue the redirect from `middleware`, a loader, or a **synchronous**
+> handler return instead. (Dev logs a warning if this is hit.)
+
 ### Redirect with location state
 
 Carry typed state through redirects (e.g. flash messages):
@@ -313,6 +405,10 @@ state persists on back/forward. See `/hooks` for details.
 Attach location state to any server response (not just redirects):
 
 ```typescript
+import { createLocationState } from "@rangojs/router";
+
+const ServerInfo = createLocationState<{ data: string }>();
+
 path("/dashboard", (ctx) => {
   ctx.setLocationState(ServerInfo({ data: "welcome" }));
   return <Dashboard />;
@@ -383,6 +479,18 @@ urls(({ path, layout }) => [
 ])
 ```
 
+For composing whole route MODULES, reach for `include()` — and prefer the
+code-split form `include("/shop", () => import("./shop-patterns"))` for any
+group that is a natural unit: it keeps the group off the cold-start path, and
+measured first-hit cost scales with routes-per-chunk, so many small groups
+beat one giant one. Sizing rules and the numbers behind them:
+[skills/composability](../composability/SKILL.md) → "Sizing async include
+groups (measured)".
+
+## View Transitions
+
+A route can configure its own `transition()` — the wrap goes around the route's component itself (routes are leaves; they have no separate default outlet channel). If the route component renders a `<ParallelOutlet />` directly, that slot remains inside the route's VT subtree, so prefer mounting parallel slots in a layout when combining intercept modals with route-level transitions. See [skills/view-transitions](../view-transitions/SKILL.md) for examples and the wrap-location rules across layouts, routes, and slots.
+
 ## Handler-attached `.use`
 
 Page handlers can carry their own loader, middleware, error boundaries, parallels, and other defaults via a `.use` callback — so the page is self-contained and reusable across mount sites without re-wiring the same items.