@rangojs/router 0.0.0-experimental.f2d1a2f1 → 0.0.0-experimental.f4a8e8de

package/skills/rango/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: rango
-description: Overview of @rangojs/router and available skills
+description: Overview of @rangojs/router and available skills. Use when unsure which skill to reach for, starting a new task in a Rango app, or asking "what can this router do".
 argument-hint:
 ---
 
@@ -8,32 +8,314 @@ argument-hint:
 
 Django-inspired RSC router with composable URL patterns, type-safe href, and server components.
 
+This page is the mental model to read **before** the catalog. A flat list of
+skills gives nothing to slot details into, so a reader free-associates from local
+vocabulary — which is exactly how `revalidate()` gets misread as caching. Start
+with the shape, then pick a primitive.
+
+## The shape of rango (read first)
+
+- **Routes are expressed, not configured.** The `urls()` tree shows where every
+  route, layout, loader, and cache lives. No file-system convention, no hunting.
+- **Two freshness axes, orthogonal:**
+  - _stored-value freshness_ — `"use cache"`, `cache()`, loader `cache()`
+    (SWR is first-class where the store supports it; `"use cache"` ships a
+    default SWR window; see `/cache-guide`)
+  - _client-update selection_ — `revalidate()`
+- **Loaders are the live data layer** — fresh every request by default, even
+  inside a cached render. They run **in parallel** right after middleware and
+  **stream**, so data latency overlaps first paint instead of blocking it (a
+  cache hit streams UI instantly while loaders resolve fresh alongside). Opt into
+  caching explicitly. See `/loader` → "Parallel and streaming".
+- **One identity, one store** — loaders, handles, cached fns, and actions are all
+  `path#export`; all caches share one store. Entries expire by TTL/SWR, and are
+  tagged via `cache({ tags })` or runtime `cacheTag(...tags)`; built-in stores
+  index by tag and invalidate via `updateTag(...tags)` (awaitable, read-your-own-writes)
+  or `revalidateTag(...tags)` (background, non-blocking).
+- **Type-safe end to end** — route names, params, search schemas, loader return
+  types, context vars, and `href` / `reverse` are checked at compile time
+  (`/typesafety`).
+- **See where time goes** — turn on `debugPerformance` early (router option, or
+  `ctx.debugPerformance()` in middleware for per-request opt-in). It prints a
+  per-request waterfall + `Server-Timing` header; loaders should overlap the
+  render bar, not serialize after it. For production, wire `telemetry` to a
+  console, OpenTelemetry, or custom sink. See `/observability`.
+
+Most features are **just-in-time**: the core is `urls()`, `path()`, `layout()`,
+`include()`, and `reverse()`. Caching, parallel routes, intercepts, prerender,
+i18n, themes, and the rest are opt-in — reach for them when a requirement
+appears, not up front.
+
+## Composability: structure vs config
+
+- `path()` / `include()` are **structure** — they define URLs and must stay
+  visible in `urls()`. They cannot be hidden in a factory. `include()` composes
+  whole modules (separation of real concerns); `path()` places a leaf.
+- Everything else — `cache`, `loader`, `loading`, `middleware`, `revalidate`,
+  `parallel`, `intercept`, `errorBoundary`, … — is **config**. It attaches to a
+  node via its `use` callback, is importable, and extracts into factories that
+  return arrays (`withAuth()`, `withCaching()`), flattened automatically.
+
+To decide where something can live: **does it define a URL? structure, stays in
+`urls()`. Does it modify a node? config, compose freely.**
+
+## Passing data down the tree
+
+Four ways to get per-request data to a segment below you, ordered safest-first.
+Reach for the next rung only when the one above doesn't fit — the higher rungs
+are immune to partial-revalidation staleness by construction.
+
+1. **A loader** (`loader()` + `useLoader()`). Loaders resolve fresh on every
+   pass — full renders, action revalidations, cache hits. Nothing to keep in
+   sync. If the data can be a loader, make it a loader.
+2. **Middleware `ctx.set()`**. Route middleware wraps every render pass,
+   including post-action revalidation and PE re-renders, so its variables are
+   never stale. Right for request-shaped context: auth, session, locale.
+3. **Handler `ctx.set()` to its own children** —
+   `path(handler, ..., () => [layout(...)])`. Orphan layouts and their
+   parallels belong to the route entry: on an action the whole entry re-runs
+   together by default (handler-first preserved), so the data stays consistent
+   with zero configuration. Right for data the page must compute anyway —
+   e.g. pagination, where the handler's search decides how many pages the
+   layout chrome renders. One rule: if you narrow the entry's revalidation
+   with a predicate that can return a hard `false`, put the same contract on
+   the entry's children too — a hard `false` on one side of a
+   producer/consumer pair desyncs it.
+4. **Cross-entry sharing** — an outer `layout()` entry feeding descendants.
+   Outer entries do NOT revalidate on actions by default (the revalidation
+   trace calls this `action:parent-chain-skip`), so this rung always requires
+   a shared revalidation contract: the same named `revalidate()` function on
+   the producer and every consumer. See `/layout` → "Revalidation Contracts".
+   Before writing one, check whether the producer can move down a rung.
+
+The failure mode this ladder prevents: a consumer re-runs, its producer
+doesn't, `ctx.get()` reads `undefined`, and fallback UI silently replaces good
+UI after an action. Rungs 1–3 make that unrepresentable; rung 4 makes it a
+stated, greppable contract.
+
+## Pick a primitive
+
+| I need to…                              | Use                                | Skill                   |
+| --------------------------------------- | ---------------------------------- | ----------------------- |
+| render data fresh every request         | `loader()` + `useLoader()`         | /loader                 |
+| cache a rendered subtree                | `cache()` on a segment             | /caching                |
+| cache one function/component's result   | `"use cache"`                      | /use-cache              |
+| cache a loader's data                   | `loader(L, () => [cache()])`       | /loader, /caching       |
+| re-render a segment after an action     | `revalidate()`                     | /loader                 |
+| mutate                                  | `"use server"` action              | /server-actions         |
+| debug a slow request                    | `debugPerformance` / telemetry     | /observability          |
+| share config across routes              | factory returning a helper array   | /composability          |
+| compose a sub-app / module              | `include()`                        | /route                  |
+| modal / soft navigation                 | `intercept()`                      | /intercept              |
+| pre-render a route at build time        | `Prerender(...)` wrapper           | /prerender              |
+| feed live loaders from a cached shell   | replayed handle + `ctx.rendered()` | /shell-manifest         |
+| cache the HTML shell, keep loaders live | `ppr` path option                  | /ppr                    |
+| choose in-function vs CDN caching       | deployment cache boundary          | /deployment-caching     |
+| stream SSE / upgrade a WebSocket        | `path.stream()` / `path.any()`     | /streams-and-websockets |
+
+## Invariants
+
+- `path()`/`include()` are always visible in `urls()`; config helpers are extractable.
+- **Cache decides freshness; `revalidate()` decides client-update.** Orthogonal; compose.
+- Loaders resolve fresh every request (even inside `cache()`) and never run twice/request.
+- **The consumption-lane rule.** For every shared artifact (`cache()`,
+  `"use cache"`, the PPR shell): server-side handler consumption
+  (`await ctx.use(loader)`) yields a BAKED copy — identity reads
+  (`cookies()`/`headers()`) are permitted there and the capture-time value
+  freezes into the shared artifact (a documented footgun; see `/caching` →
+  "Cache purity & tainted objects"). Client-side consumption (`useLoader` in
+  a `"use client"` component) is the LIVE lane. DSL `loader()` segments
+  follow their lane machinery (live under renderable `loading()`, bake
+  otherwise). Pinned by semantic-matrix row PPR3.
+- Inside `"use cache"`: `cookies()`/`headers()` and `ctx` side-effects
+  (`set`/`header`/`setTheme`/`onResponse`/`setLocationState`) throw; `ctx.use(Handle)`
+  is captured on miss and replayed on hit. (The non-cacheable read guard is a
+  separate `cache()`-boundary check — see the correctness bullet below.)
+- One identity `path#export` (`functionId`/`$$id`/`actionId`); one store. Freshness
+  is TTL/SWR expiry plus tag-based invalidation: tag via `cache({ tags })` /
+  `cacheTag(...tags)`, then `updateTag(...tags)` (awaitable) or `revalidateTag(...tags)`
+  (background). Built-in stores index by tag.
+- `useLoader` / `useHandle` / `useFetchLoader` are client-only.
+- Caches are correctness-first: persistent store keys are version-segmented (no
+  cross-deploy drift), the forward/back cache is mutation-aware, and
+  `createVar({ cache: false })` throws on a **direct** read inside a `cache()`
+  boundary (a deliberately non-propagating guard). See `/cache-guide` →
+  "Correctness & invalidation".
+- Nested caches: the outer cache window bounds the inner — an inner shorter TTL
+  only applies when the enclosing cache recomputes; put a value in a loader if it
+  must be fresher. See `/cache-guide` → "Combining Both".
+
+## Don't confuse
+
+- `revalidate()` ≠ cache invalidation — partial-render selection vs value freshness.
+- host router `.lazy()` (lazy import of a handler/sub-app) vs `.map()` (inline Response).
+- `cache()` (segment, in the DSL) vs `"use cache"` (function/component directive).
+- `loader()` registration (server) vs `useLoader()` consumption (client).
+
+### Coming from another framework (false friends)
+
+Same words, different jobs — this is the most common source of the
+`revalidate()`-is-caching misread.
+
+| You may know                            | Maps to Rango axis | Watch out                                                                                                                                                                                                                                                                               |
+| --------------------------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Next.js `export const revalidate = N`   | **Axis 1** (cache) | Same word, opposite meaning. Next's `revalidate` is time-based cache expiry; Rango's `revalidate()` is **axis 2**. Use `cache({ ttl })` for the Next behavior.                                                                                                                          |
+| Next.js `revalidateTag` / `updateTag`   | **Axis 1** (cache) | Cache busting by tag. Tag via `cache({ tags })` / `cacheTag(...tags)`; invalidate with `updateTag(...tags)` (awaitable, read-your-own-writes) or `revalidateTag(...tags)` (background, non-blocking). Built-in stores index by tag. No `revalidatePath` (path-based busting); use tags. |
+| React Router / Remix `shouldRevalidate` | **Axis 2**         | This is the correct mental model for Rango's `revalidate()`.                                                                                                                                                                                                                            |
+| HTTP `Cache-Control` / ISR              | Deployment layer   | Complete-response deployment layer. A CDN hit bypasses Rango entirely; the store-backed middleware does not. See `/deployment-caching` and `/document-cache`.                                                                                                                           |
+| Next.js PPR (partial prerendering)      | HTML shell layer   | Same React primitive, different transport: Rango serves shells in-function after middleware. Ordinary `ppr` captures at runtime; `Prerender + ppr` captures at build. See `/ppr`, `/prerender`, and `/deployment-caching`.                                                              |
+| Remix/RR `loader`                       | live data          | Like Rango loaders, fresh per request — but Rango loaders run in parallel and stream (latency overlaps first paint), and can opt into caching on demand.                                                                                                                                |
+
+See `/cache-guide` for the axis-1 decision guide, `/loader` and `/route` for
+`revalidate()` (axis 2), and `/document-cache` for the edge layer.
+
+## Canonical shape
+
+```ts
+export const urlpatterns = urls(({ path, layout, loader, loading, cache, revalidate }) => [
+  layout(<ShopLayout />, () => [                 // structure: wraps children
+    loader(CartLoader, () => [                   // config: live data
+      // partial-render axis: re-run on cart actions, defer otherwise.
+      // ctx.isAction() matches by reference (rename-safe), not by string.
+      revalidate((ctx) => ctx.isAction(CartActions) || undefined),
+    ]),
+    path("/shop/:slug", ProductPage, { name: "product" }, () => [  // structure: leaf
+      loader(ProductLoader, () => [cache({ ttl: 60 })]),  // config: cache loader DATA
+      loading(<ProductSkeleton />),              // config
+      withRecs(),                                // composed factory (config array)
+    ]),
+  ]),
+]);
+```
+
+One tree, both axes visible: structure (`layout`/`path`) vs config (everything
+else), freshness (`cache`) vs client-update (`revalidate`). Actions are matched
+by reference with `ctx.isAction(Action)` (rename-safe, where `CartActions` is an
+`import * as CartActions from "./actions/cart"`); see `/typesafety` → "Stable
+identity".
+
+The predicate arg carries the action's full context, not just its identity. Match
+_which_ action with `ctx.isAction(addToCart)` (rename-safe); branch on _what it
+returned_ with `ctx.actionResult` — the value your `"use server"` function
+returned, for outcome-conditional revalidation. The arg also exposes `actionId`
+(raw `path#export`), `actionUrl`, `formData`, `method`, and `stale` (cross-tab
+`_rsc_stale` signal). All are `undefined` on plain navigation (no action).
+
+Two idioms, picked by what an _unrelated_ action should do. `ctx.isAction()`
+returns a raw boolean, so combine it with `|| undefined` to **defer** ("mine,
+else let the default decide": `ctx.isAction(CartActions) || undefined`) or leave
+it bare to **suppress** ("mine only": `ctx.isAction(CartActions)`). Prefer the
+defer form unless a sibling segment must own the unrelated-action decision.
+
+```ts
+// re-render only when checkout actually succeeded; defer otherwise
+revalidate((ctx) => (ctx.isAction(checkout) && ctx.actionResult?.ok) || undefined),
+```
+
+**The source is the source of truth.** Structure, types, and update policy are
+visible and local in the tree — read top-down, no hidden global model to hold in
+your head. A snippet earns its place only if, from the code alone, you can answer:
+_what URLs exist and who owns them?_ (composition), _can I trust this reference
+without leaving the call site?_ (type-safety), _what re-renders after this
+action?_ (partial rendering). If any answer needs another file, it isn't legible
+yet.
+
+**Reading Rango's own source.** Runtime exports resolve to `./src/*.ts`, so Vite
+bundles Rango straight from source; type conditions resolve to emitted
+`./dist/types/*.d.ts` so a consumer's standalone `tsc` does not check Rango's
+implementation. The `./vite` plugin and CLI also execute compiled files from
+`dist/`. Read `src/` to confirm runtime behavior and `dist/types/` to inspect
+the exact declarations consumers receive.
+
 ## Skills
 
-| Skill                   | Description                                                                |
-| ----------------------- | -------------------------------------------------------------------------- |
-| `/router-setup`         | Create and configure the RSC router                                        |
-| `/route`                | Define routes with `urls()` and `path()`                                   |
-| `/layout`               | Layouts that wrap child routes                                             |
-| `/loader`               | Data loaders with `createLoader()`                                         |
-| `/middleware`           | Request processing and authentication                                      |
-| `/intercept`            | Modal/slide-over patterns for soft navigation                              |
-| `/parallel`             | Multi-column layouts and sidebars                                          |
-| `/caching`              | Segment caching with memory or KV stores                                   |
-| `/use-cache`            | Function-level caching with `"use cache"` directive                        |
-| `/cache-guide`          | When to use `cache()` vs `"use cache"` — differences and decision guide    |
-| `/document-cache`       | Edge caching with Cache-Control headers                                    |
-| `/theme`                | Light/dark mode with FOUC prevention                                       |
-| `/links`                | URL generation: ctx.reverse, href, useHref, useMount, scopedReverse        |
-| `/hooks`                | Client-side React hooks                                                    |
-| `/typesafety`           | Type-safe routes, params, href, and environment                            |
-| `/host-router`          | Multi-app host routing with domain/subdomain patterns                      |
-| `/tailwind`             | Set up Tailwind CSS v4 with `?url` imports                                 |
-| `/response-routes`      | JSON/text/HTML/XML/stream endpoints with `path.json()`, `path.text()`      |
-| `/mime-routes`          | Content negotiation — same URL, different response types via Accept header |
-| `/fonts`                | Load web fonts with preload hints                                          |
-| `/migrate-nextjs`       | Migrate a Next.js App Router project to Rango                              |
-| `/migrate-react-router` | Migrate a React Router / Remix project to Rango                            |
+Grouped by concern — read when you need to…
+
+**Positioning & evaluation**:
+
+| Skill         | Description                                                  |
+| ------------- | ------------------------------------------------------------ |
+| `/comparison` | Compare Rango with Next.js, TanStack Start, and Waku fairly. |
+
+**Structure & routing** — shape URLs, layouts, navigation, and request processing:
+
+| Skill                     | Description                                                                |
+| ------------------------- | -------------------------------------------------------------------------- |
+| `/router-setup`           | Create and configure the RSC router                                        |
+| `/route`                  | Define routes with `urls()`, `path()`, and `include()`                     |
+| `/layout`                 | Layouts that wrap child routes                                             |
+| `/parallel`               | Multi-column layouts and sidebars                                          |
+| `/intercept`              | Modal/slide-over patterns for soft navigation                              |
+| `/middleware`             | Request processing and authentication                                      |
+| `/host-router`            | Multi-app host routing with domain/subdomain patterns                      |
+| `/links`                  | URL generation: ctx.reverse, href, useHref, useMount, scopedReverse        |
+| `/response-routes`        | JSON/text/HTML/XML/stream endpoints with `path.json()`, `path.text()`      |
+| `/api-client`             | Typed client for consuming your own response-route JSON APIs (recipe)      |
+| `/mime-routes`            | Content negotiation — same URL, different response types via Accept header |
+| `/streams-and-websockets` | SSE via `path.stream` and WebSocket upgrades via `path.any`                |
+| `/handler-use`            | Attach default loaders/middleware to a handler via `handler.use`           |
+| `/composability`          | Reusable route-helper factories (structure vs config)                      |
+
+**Data & caching** — fetch, mutate, and cache:
+
+| Skill                 | Description                                                                                                                                                       |
+| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `/loader`             | Data loaders with `createLoader()` and `revalidate()`                                                                                                             |
+| `/server-actions`     | Mutations with `"use server"`, useActionState, validation, revalidation                                                                                           |
+| `/caching`            | Segment caching with memory or KV stores                                                                                                                          |
+| `/use-cache`          | Function-level caching with `"use cache"` directive                                                                                                               |
+| `/cache-guide`        | When to use `cache()` vs `"use cache"` — differences and decision guide                                                                                           |
+| `/document-cache`     | Store-backed complete-response middleware using Cache-Control policy                                                                                              |
+| `/deployment-caching` | Choose between in-function caches, store-backed responses, and an external CDN cache                                                                              |
+| `/ppr`                | PPR shell caching: cached shell served instantly, live holes resumed — a hole is a `loading()` subtree OR a pending promise under `<Suspense>` (no loader needed) |
+| `/prerender`          | Pre-render route segments at build time (Passthrough live fallback)                                                                                               |
+| `/shell-manifest`     | Replayed handles as cache metadata read by live loaders (frozen shell, batched live holes)                                                                        |
+
+**Client & presentation** — build the client-side UX:
+
+| Skill               | Description                                                                                                                        |
+| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `/hooks`            | Client-side React hooks                                                                                                            |
+| `/theme`            | Light/dark mode with FOUC prevention                                                                                               |
+| `/i18n`             | Locale routing with `:locale?`, resolution chains, react-intl integration                                                          |
+| `/fonts`            | Load web fonts with preload hints                                                                                                  |
+| `/css`              | Import CSS in the Document `<head>` (`?url` + managed `precedence` links)                                                          |
+| `/scripts`          | Inject third-party scripts (GTM/analytics) into head/body via the `Script` handle; nonce auto-applied to document-rendered scripts |
+| `/tailwind`         | Set up Tailwind CSS v4 with `?url` imports                                                                                         |
+| `/view-transitions` | React View Transitions on layouts, routes, and parallel slots                                                                      |
+| `/defer-hydration`  | Full body HTML in the PPR shell + hydration off the critical path (gated Suspense boundary, content-as-fallback)                   |
+| `/breadcrumbs`      | Built-in Breadcrumbs handle for breadcrumb navigation                                                                              |
+| `/react-compiler`   | Enable React Compiler (opt-in) the vite-rsc way; client-only scope                                                                 |
+
+**Observability & production health**:
+
+| Skill              | Description                                                              |
+| ------------------ | ------------------------------------------------------------------------ |
+| `/observability`   | `debugPerformance`, `Server-Timing`, structured telemetry, tracing       |
+| `/bundle-analysis` | Audit your app's production bundle for server leaks and oversized chunks |
+| `/debug-manifest`  | Inspect route manifest structure                                         |
+
+**Deployment**:
+
+| Skill                 | Description                                                                                                      |
+| --------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `/cloudflare`         | Deploy to Cloudflare Workers with the Vite plugin, typed D1/KV bindings, migrations, secrets, and preview parity |
+| `/vercel`             | Deploy to Vercel Functions (`preset: "vercel"`), Runtime Cache, and `createVercelTracing`                        |
+| `/deployment-caching` | Compare deployment cache boundaries, middleware execution, PPR transport, and HTTP CDN caching                   |
+
+**Testing**:
+
+| Skill      | Description                                                                                                                     |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `/testing` | Unit (loaders/middleware/reverse/components), integration (dispatch/Flight), and e2e (dev+prod parity, progressive enhancement) |
+
+**Setup, types & migration**:
+
+| Skill                   | Description                                     |
+| ----------------------- | ----------------------------------------------- |
+| `/typesafety`           | Type-safe routes, params, href, and environment |
+| `/migrate-nextjs`       | Migrate a Next.js App Router project to Rango   |
+| `/migrate-react-router` | Migrate a React Router / Remix project to Rango |
 
 ## Quick Start
 
@@ -89,10 +371,23 @@ Each file is classified by its contents:
 Directories are scanned recursively for `.ts`/`.tsx` files, skipping `node_modules`,
 dotfiles, and existing `.gen.` files.
 
+> The two generated files are **not interchangeable surfaces**.
+> `router.named-routes.gen.ts` augments the global `GeneratedRouteMap` for
+> named-route typing (`Handler<"name">`, `ctx.reverse("name")`, prerender).
+> Per-module `*.gen.ts` exports a local `routes` map for `useReverse(routes)`
+> and explicit local handler typing (`Handler<".name", routes>`). Neither
+> carries response payloads — response/MIME payload inference comes from
+> `typeof router.routeMap` via `RegisteredRoutes`, not `*.named-routes.gen.ts`.
+> See `/typesafety` for the full surface breakdown.
+
 ### Recursive includes
 
 The generator follows `include()` calls across files, resolving imports to build
-the full route tree. Circular includes are detected and warned about.
+the full route tree. It resolves both the eager form `include("/x", patterns)`
+and the code-split async form `include("/x", () => import("./x"))` — for the
+latter it walks the imported module's `export default urls(...)`, including any
+nested `include()`s inside it — so a code-split route group is still fully typed
+(see `/composability`). Circular includes are detected and warned about.
 
 ### First-wins deduplication
 

package/skills/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`.