@rangojs/router 0.0.0-experimental.112 → 0.0.0-experimental.114

package/skills/document-cache/SKILL.md

@@ -10,73 +10,82 @@ Caches complete HTTP responses (HTML/RSC) at the edge based on Cache-Control hea
 
 ## Setup
 
-Configure document cache in router:
+Document caching is a middleware. Add `createDocumentCacheMiddleware()` to the
+router with `.use()`. The cache store it reads from is the app-level store you
+configure on `createRouter({ cache })` (available on the request context as
+`requestCtx._cacheStore`), not a store passed to the middleware.
 
 ```typescript
 import { createRouter } from "@rangojs/router";
-import { CFCacheStore } from "@rangojs/router/cache";
+import {
+  createDocumentCacheMiddleware,
+  CFCacheStore,
+} from "@rangojs/router/cache";
 import { urlpatterns } from "./urls";
 
 const router = createRouter<AppBindings>({
   document: Document,
   urls: urlpatterns,
-  documentCache: (_env, ctx) => ({
-    store: new CFCacheStore({ ctx: ctx! }),
+  // App-level cache store. The document cache middleware uses this store's
+  // getResponse/putResponse methods.
+  cache: (_env, ctx) => new CFCacheStore({ ctx: ctx! }),
+});
+
+router.use(
+  createDocumentCacheMiddleware({
     skipPaths: ["/api", "/admin"],
     debug: process.env.NODE_ENV === "development",
   }),
-});
+);
 
 export default router;
 ```
 
-## Route Opt-In with cache()
+## Route Opt-In with Cache-Control
 
-Routes opt-in to document caching using the `cache()` DSL with `documentCache` option:
+Routes opt-in to document caching by setting a `Cache-Control` response header
+with `s-maxage`. The middleware caches responses whose `Cache-Control` includes
+`s-maxage`; `stale-while-revalidate` enables background revalidation (SWR).
 
 ```typescript
-import { urls } from "@rangojs/router";
-
-export const urlpatterns = urls(({ path, cache }) => [
-  // Cache full page for 5 min, serve stale for 1 hour
-  cache({ documentCache: { sMaxAge: 300, swr: 3600 } }, () => [
-    path("/blog", BlogIndex, { name: "blog" }),
-  ]),
-
-  // Long cache for individual posts
-  cache({ documentCache: { sMaxAge: 3600, swr: 86400 } }, () => [
-    path("/blog/:slug", BlogPost, { name: "blogPost" }),
-  ]),
-
-  // No cache for dashboard (no documentCache option)
-  path("/dashboard", Dashboard, { name: "dashboard" }),
-]);
+// Cache full page for 5 min, serve stale for 1 hour
+function BlogIndexHandler(ctx) {
+  ctx.headers.set("Cache-Control", "s-maxage=300, stale-while-revalidate=3600");
+  return <BlogIndex />;
+}
+
+// Long cache for individual posts
+function BlogPostHandler(ctx) {
+  ctx.headers.set("Cache-Control", "s-maxage=3600, stale-while-revalidate=86400");
+  return <BlogPost />;
+}
+
+// Dashboard sets no Cache-Control header, so it is never document-cached.
 ```
 
 ## Document Cache Options
 
-```typescript
-createRouter({
-  // ...
-  documentCache: (_env, ctx) => ({
-    // Cache store (required)
-    store: new CFCacheStore({ ctx: ctx! }),
+`createDocumentCacheMiddleware(options?)` accepts:
 
-    // Skip specific paths
-    skipPaths: ["/api", "/admin"],
+```typescript
+createDocumentCacheMiddleware({
+  // Skip specific paths (matched by pathname prefix)
+  skipPaths: ["/api", "/admin"],
 
-    // Custom cache key
-    keyGenerator: (url) => url.pathname,
+  // Custom cache key generator
+  keyGenerator: (url) => url.pathname,
 
-    // Conditional caching
-    isEnabled: (ctx) => !ctx.request.headers.has("x-preview"),
+  // Conditional caching, evaluated per request
+  isEnabled: (ctx) => !ctx.request.headers.has("x-preview"),
 
-    // Debug logging
-    debug: true,
-  }),
+  // Debug logging (HIT, MISS, STALE, REVALIDATED)
+  debug: true,
 });
 ```
 
+The cache store is not a middleware option — it comes from the app-level
+`createRouter({ cache })` store.
+
 ## How It Works
 
 ```
@@ -89,7 +98,7 @@ Request → Check Cache
     ↓             ↓
   Fresh?      Run handler
     │             │
-   Yes → Return   Has documentCache?
+   Yes → Return   Has s-maxage?
     │             │
    No (stale)    Yes → Cache + Return
     │             │
@@ -120,13 +129,14 @@ Segment hash ensures different cached responses for navigations from different s
 
 - Full HTML responses (document requests)
 - RSC payloads (client navigation)
-- Only 200 OK responses with documentCache enabled
+- Only 200 OK responses whose `Cache-Control` includes `s-maxage`
 
 ## What's NOT Cached
 
 - Server actions (`_rsc_action`)
 - Loader requests (`_rsc_loader`)
-- Routes without `documentCache` option
+- Non-GET requests
+- Responses without an `s-maxage` `Cache-Control` directive
 - Non-200 responses
 
 ## Complete Example
@@ -134,40 +144,53 @@ Segment hash ensures different cached responses for navigations from different s
 ```typescript
 // router.tsx
 import { createRouter } from "@rangojs/router";
-import { CFCacheStore } from "@rangojs/router/cache";
+import { createDocumentCacheMiddleware, CFCacheStore } from "@rangojs/router/cache";
 import { urlpatterns } from "./urls";
 
 const router = createRouter<AppBindings>({
   document: Document,
   urls: urlpatterns,
-  documentCache: (_env, ctx) => ({
-    store: new CFCacheStore({ ctx: ctx! }),
+  cache: (_env, ctx) => new CFCacheStore({ ctx: ctx! }),
+});
+
+router.use(
+  createDocumentCacheMiddleware({
     skipPaths: ["/api"],
     debug: process.env.NODE_ENV === "development",
   }),
-});
+);
 
 export default router;
 
 // urls.tsx
 import { urls } from "@rangojs/router";
 
-export const urlpatterns = urls(({ path, layout, cache, loader }) => [
-  // Blog with document caching
-  cache({ documentCache: { sMaxAge: 300, swr: 3600 } }, () => [
-    layout(<BlogLayout />, () => [
-      path("/blog", BlogIndex, { name: "blog" }),
-      path("/blog/:slug", BlogPost, { name: "blogPost" }, () => [
-        loader(BlogPostLoader),
-      ]),
+export const urlpatterns = urls(({ path, layout, loader }) => [
+  // Blog pages opt into document caching via Cache-Control headers set in
+  // their handlers (see BlogIndex / BlogPost below).
+  layout(<BlogLayout />, () => [
+    path("/blog", BlogIndex, { name: "blog" }),
+    path("/blog/:slug", BlogPost, { name: "blogPost" }, () => [
+      loader(BlogPostLoader),
     ]),
   ]),
 
-  // Dashboard - no document cache (dynamic content)
+  // Dashboard sets no Cache-Control header, so it is never document-cached.
   layout(<DashboardLayout />, () => [
     path("/dashboard", Dashboard, { name: "dashboard" }),
   ]),
 ]);
+
+// Blog handlers set s-maxage to opt into the document cache.
+function BlogIndex(ctx) {
+  ctx.headers.set("Cache-Control", "s-maxage=300, stale-while-revalidate=3600");
+  return <BlogIndexPage />;
+}
+
+function BlogPost(ctx) {
+  ctx.headers.set("Cache-Control", "s-maxage=300, stale-while-revalidate=3600");
+  return <BlogPostPage />;
+}
 ```
 
 ## Document Cache vs Segment Cache
@@ -175,7 +198,7 @@ export const urlpatterns = urls(({ path, layout, cache, loader }) => [
 | Feature      | Document Cache             | Segment Cache         |
 | ------------ | -------------------------- | --------------------- |
 | Granularity  | Full response              | Individual segments   |
-| Opt-in       | `documentCache` in cache() | `cache({ ttl, swr })` |
+| Opt-in       | `Cache-Control` `s-maxage` | `cache({ ttl, swr })` |
 | Use case     | Static pages               | Dynamic compositions  |
 | Key includes | URL + segment hash         | Route params          |
 

package/skills/hooks/SKILL.md

@@ -268,7 +268,11 @@ reads (keyed or not) reset on navigation from fresh route data, as before.
 **Refreshing multiple loaders together (`refreshGroup` + `useRefreshLoaders`)**:
 
 `key` groups readers of one loader. To refresh **different** loaders together,
-tag them with the same `refreshGroup` and trigger them with `useRefreshLoaders`:
+tag them with a shared `refreshGroup` name and trigger them with
+`useRefreshLoaders()`. The hook takes no argument; you pass the group(s) to the
+function it returns, so one `useRefreshLoaders()` can refresh different groups
+depending on context. A read may carry **several** tags — pass an array — and is
+refreshed when **any** of its groups is refreshed:
 
 ```tsx
 function Profile() {
@@ -279,33 +283,47 @@ function Profile() {
   return <span>{data.name}</span>;
 }
 function Orders() {
+  // Tagged into two groups: refreshed by "account" (the whole set) or the
+  // finer "orders" tag.
   const { data } = useLoader(OrdersLoader, {
     key: userId,
-    refreshGroup: "account",
+    refreshGroup: ["account", "orders"],
   });
   return <span>{data.count} orders</span>;
 }
-function RefreshButton() {
-  const refreshAccount = useRefreshLoaders("account");
-  return <button onClick={() => refreshAccount()}>Refresh</button>;
+function RefreshButtons() {
+  const refresh = useRefreshLoaders();
+  return (
+    <>
+      <button onClick={() => refresh("account")}>Refresh account</button>
+      <button onClick={() => refresh("orders")}>Refresh orders only</button>
+      <button onClick={() => refresh(["account", "orders"])}>
+        Refresh both
+      </button>
+    </>
+  );
 }
 ```
 
-`refreshAccount()` re-runs every currently-mounted member with a **plain GET**
-against the current route URL — no params, no body, no mutation methods, because
-a group spans loaders with different shapes. It returns a promise that resolves
+`refresh(groups)` accepts one name or an array and re-runs every currently-mounted
+member tagged with **any** of them, with a **plain GET** against the current route
+URL — no params, no body, no mutation methods, because a group spans loaders with
+different shapes. A member that sits in two of the requested groups is fetched
+once (members are unioned and deduped by read). It returns a promise that resolves
 when all members settle and **rejects with an `AggregateError`** if any fail;
 group refresh never render-throws, so handle failures at the await site
-(`await refreshAccount().catch(...)`). Each failing member also exposes its error
-via its own read's `error`.
-
-Sharing within a group is opt-in via `key`: members that share a `key` share one
-value (and one fetch); a grouped reader **without** a `key` gets its own private
-bucket, so a group refresh updates only that read and never leaks into unrelated
-unkeyed reads of the same loader. A bucket may belong to several groups at once
-(different reads can tag the same keyed bucket with different group names).
-Keep parameterized loaders on the single-loader `key` — a plain-GET group refresh
-sends no params.
+(`await refresh("account").catch(...)`). Each failing member also exposes its
+error via its own read's `error`.
+
+Multiple tags give you granular vs. whole-set refresh from one place: a coarse
+tag (`"account"`) covers everything, while a finer tag (`"orders"`) targets a
+subset. Sharing within a group is opt-in via `key`: members that share a `key`
+share one value (and one fetch); a grouped reader **without** a `key` gets its own
+private bucket, so a group refresh updates only that read and never leaks into
+unrelated unkeyed reads of the same loader. A bucket may belong to several groups
+at once (one read tagged with multiple names, or different reads tagging the same
+keyed bucket with different names). Keep parameterized loaders on the single-loader
+`key` — a plain-GET group refresh sends no params.
 
 **Load options**:
 
@@ -850,7 +868,7 @@ function MountInfo() {
 
 ### useReverse(routes)
 
-Mount-aware local reverse for client components. Import the generated `routes` map from a `urls()` module's `.gen.ts` and call `reverse(".name", params?)`. Auto-fills params from `useParams()`; explicit params override.
+Mount-aware local reverse for client components. Import the generated `routes` map from a `urls()` module's `.gen.ts` and call `reverse("name", params?)` — the leading dot is optional. Auto-fills params from `useParams()`; explicit params override.
 
 > Per-module `*.gen.ts` files are **CLI opt-in and not Vite-watched** — run `rango generate <urls-file>` (or wire it into `predev`) and re-run it whenever the module's routes change. See `/links` for the full generated-file setup and exposure-boundary rules.
 
@@ -863,8 +881,8 @@ function BlogNav() {
   const reverse = useReverse(blogRoutes);
   return (
     <nav>
-      <Link to={reverse(".index")}>Blog</Link>
-      <Link to={reverse(".post", { postId: "hello" })}>Post</Link>
+      <Link to={reverse("index")}>Blog</Link>
+      <Link to={reverse("post", { postId: "hello" })}>Post</Link>
     </nav>
   );
 }
@@ -888,7 +906,7 @@ See `/links` for the full URL generation guide. `ctx.reverse()` is server-only;
 | `useLinkStatus()`     | Link pending state                | { pending }                                                        |
 | `useLoader()`         | Loader data (strict)              | data, isLoading, error                                             |
 | `useFetchLoader()`    | Loader with on-demand fetch       | data, load, isLoading                                              |
-| `useRefreshLoaders()` | Refresh a cross-loader group      | `(group) => () => Promise<void>`                                   |
+| `useRefreshLoaders()` | Refresh cross-loader group(s)     | `() => (groups: string \| string[]) => Promise<void>`              |
 | `useHandle()`         | Accumulated handle data           | T (handle type)                                                    |
 | `useAction()`         | Server action state               | state, error, result                                               |
 | `useLocationState()`  | History state (persists or flash) | T \| undefined                                                     |

package/skills/links/SKILL.md

@@ -13,7 +13,7 @@ argument-hint: [ctx.reverse|href|useHref|useMount|useReverse|scopedReverse]
 **On the client, two patterns:**
 
 1. **Receive URLs as props / loader data / action return.** The default. The server has the full route manifest and handler context — generate URLs there and hand strings to client components.
-2. **`useReverse(routes)`.** Import a generated `routes` map from a `urls()` module's `.gen.ts` and call `reverse(".name", params?)`. Mount-aware via `useMount()`, auto-fills params from `useParams()`, fully typed from the imported map. Use this when a client component needs to generate URLs into a known module without round-tripping through the server.
+2. **`useReverse(routes)`.** Import a generated `routes` map from a `urls()` module's `.gen.ts` and call `reverse("name", params?)` (the leading dot is optional). Mount-aware via `useMount()`, auto-fills params from `useParams()`, fully typed from the imported map. Use this when a client component needs to generate URLs into a known module without round-tripping through the server.
 
 `ctx.reverse()` itself is **server-only** — it depends on the full route manifest and handler context. Client components never import or call it.
 
@@ -273,7 +273,7 @@ function MountInfo() {
 
 Hook that returns a typed local reverse function for a `routes` map imported from a generated `.gen.ts` next to a `urls()` module. The route map is the **exposure boundary** — `useReverse` only knows about names in that map, never the full app manifest.
 
-> Import the per-module `routes` (e.g. `urls/blog.gen.ts`), **not** `router.named-routes.gen.ts`. The named-routes file is the whole app manifest and is server-only data — importing it into a client component pulls every route name into the client bundle.
+> **Which map?** `useReverse` accepts any routes map. Prefer the per-module `routes` (e.g. `urls/blog.gen.ts`): it gives **mount-aware** local `.name` reverse (auto-prefixes the `include()` mount) and only that module's names enter the client bundle. You _can_ instead pass `router.named-routes.gen.ts` (`NamedRoutes`) for **global** names (`blog.post`; the leading dot is optional) — it is a plain importable map and works on the client (it is **not** server-only) — but its paths are **absolute** while `useReverse` mount-prefixes, so it is correct only at the root mount (under a non-root mount it double-prefixes), and importing it pulls every route name and pattern in the app into the client bundle (a small names-to-paths map — not components or loaders), versus the per-module map which exposes only one module's names. So the per-module map is preferred for in-module links; the named-routes map is the escape hatch for global names.
 
 ```tsx
 "use client";
@@ -285,8 +285,8 @@ export function BlogNav() {
 
   return (
     <nav>
-      <Link to={reverse(".index")}>Blog</Link>
-      <Link to={reverse(".post", { postId: "hello" })}>Post</Link>
+      <Link to={reverse("index")}>Blog</Link>
+      <Link to={reverse("post", { postId: "hello" })}>Post</Link>
     </nav>
   );
 }
@@ -294,7 +294,7 @@ export function BlogNav() {
 
 ### How it resolves
 
-1. Strips the leading `.` and looks up the name in the imported `routes` map.
+1. Strips an optional leading `.` and looks up the name in the imported `routes` map.
 2. Joins the local pattern with the surrounding `useMount()` value — the include's URL pattern.
 3. Substitutes params: explicit params from the call, then auto-filled from `useParams()` for anything still unresolved (mount params like `:tenantId` flow in this way).
 4. Appends a query string if a search object is passed and the route has a `search` schema.
@@ -362,14 +362,14 @@ reverse(".search", {}, { q: "hello world", page: 2 });
 
 ### Errors
 
-- Unknown name: throws `Unknown local route: ".not-a-route"`.
+- Unknown name: throws `Unknown route: ".not-a-route"`.
 - Missing required param: throws `Missing param "postId" for route ".detail"`.
 
 Both happen synchronously during `reverse()` — wrap calls in try/catch (or an ErrorBoundary if the throw happens during render) when you need to surface them as UI.
 
-### Names are dot-only on the client
+### The leading dot is optional
 
-`useReverse` accepts only `.name` (and dotted variants like `.nested.index`). There is no global namespace on the client — the import IS the scope. To link into a different module, import that module's `routes`:
+`reverse("post")` and `reverse(".post")` resolve **identically** — the leading dot is cosmetic. The map you import IS the scope, so there is no separate global namespace to disambiguate and the dot carries no meaning; it exists only as a readability convention and for parity with `ctx.reverse(".name")` on the server. To link into a different module, import that module's `routes`:
 
 ```tsx
 import { routes as blogRoutes } from "../urls/blog.gen.js";
@@ -380,8 +380,8 @@ function CrossNav() {
   const shop = useReverse(shopRoutes);
   return (
     <nav>
-      <Link to={blog(".index")}>Blog</Link>
-      <Link to={shop(".cart")}>Cart</Link>
+      <Link to={blog("index")}>Blog</Link>
+      <Link to={shop("cart")}>Cart</Link>
     </nav>
   );
 }

package/skills/loader/SKILL.md

@@ -98,9 +98,9 @@ path("/product/:slug", ProductPage, { name: "product" }, () => [
 >   **client** refresh identity. It groups which mounted reads of one loader
 >   refresh together when one calls `load()`. It never touches the server
 >   request. For refreshing **different** loaders together, tag them with
->   `{ refreshGroup }` and call `useRefreshLoaders(name)()` (plain GET only).
->   See the hooks skill ("Scoping refetch with a `key`" and "Refreshing multiple
->   loaders together").
+>   `{ refreshGroup }` (one name or several) and call `useRefreshLoaders()(name)`
+>   (plain GET only). See the hooks skill ("Scoping refetch with a `key`" and
+>   "Refreshing multiple loaders together").
 > - `cache({ key })` — a **server** cache identity (storage hit/miss/ttl/swr).
 > - `revalidate()` — which **server** segments/loaders recompute during
 >   navigation and action refreshes.

package/skills/rango/SKILL.md

@@ -28,7 +28,10 @@ with the shape, then pick a primitive.
   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; `revalidateTag` cuts across them.
+  `path#export`; all caches share one store. Entries expire by TTL/SWR; cache
+  entries accept an optional `tags` field, but built-in stores do not yet index
+  or invalidate by tag, so tag-based invalidation (`revalidateTag`) is a
+  forward-looking API requiring a custom store.
 - **Type-safe end to end** — route names, params, search schemas, loader return
   types, context vars, and `href` / `reverse` are checked at compile time
   (`/typesafety`).
@@ -82,8 +85,10 @@ To decide where something can live: **does it define a URL? structure, stays in
   (`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;
-  `revalidateTag` cuts across all cache mechanisms.
+- One identity `path#export` (`functionId`/`$$id`/`actionId`); one store. The
+  cross-cutting freshness mechanism today is TTL/SWR expiry; cache entries accept
+  an optional `tags` field, but built-in stores do not yet index or invalidate by
+  tag, so `revalidateTag` is forward-looking (requires a custom store).
 - `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
@@ -106,13 +111,13 @@ To decide where something can live: **does it define a URL? structure, stays in
 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 `revalidatePath` / `revalidateTag` | **Axis 1** (cache) | Cache busting. Rango's tag bust is `revalidateTag`; there is no `revalidatePath`.                                                                              |
-| React Router / Remix `shouldRevalidate`    | **Axis 2**         | This is the correct mental model for Rango's `revalidate()`.                                                                                                   |
-| HTTP `Cache-Control` / ISR                 | **Axis 1**         | Edge/document layer — see `/document-cache`. Separate from both `cache()` and `revalidate()`.                                                                  |
-| 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.       |
+| 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 `revalidatePath` / `revalidateTag` | **Axis 1** (cache) | Cache busting. No shipped equivalent: entries accept `tags`, but built-in stores don't yet index/invalidate by tag, so `revalidateTag` is forward-looking (custom store); today entries expire by TTL/SWR. No `revalidatePath`. |
+| React Router / Remix `shouldRevalidate`    | **Axis 2**         | This is the correct mental model for Rango's `revalidate()`.                                                                                                                                                                    |
+| HTTP `Cache-Control` / ISR                 | **Axis 1**         | Edge/document layer — see `/document-cache`. Separate from both `cache()` and `revalidate()`.                                                                                                                                   |
+| 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.
@@ -215,6 +220,7 @@ Grouped by concern — read when you need to…
 | `/tailwind`         | Set up Tailwind CSS v4 with `?url` imports                                |
 | `/view-transitions` | React View Transitions on layouts, routes, and parallel slots             |
 | `/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**:
 

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`.