@rangojs/router 0.0.0-experimental.fb4fdc18 → 0.0.0-experimental.fce7fbd1

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

@@ -236,22 +236,69 @@ type ProductsData = RouteResponse<typeof apiPatterns, "products">;
 // = ResponseEnvelope<{ id: string; name: string; price: number }[]>
 ```
 
-### PathResponse (global lookup by URL pattern)
+### 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
+`ResponseEnvelope<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">;
+type Health = Rango.PathResponse<"/api/health">;
 // = ResponseEnvelope<{ status: string; timestamp: number }>
 
 // RSC routes return ResponseEnvelope<never>
-type Home = PathResponse<"/">;
+type Home = Rango.PathResponse<"/">;
 // = ResponseEnvelope<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";
+
+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"); // ResponseEnvelope<Product>
+```
+
+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 `ResponseEnvelope<{ 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
@@ -361,14 +408,16 @@ export const urlpatterns = urls(({ path, include }) => [
 
 ```typescript
 import type { RouteResponse } from "@rangojs/router";
-import type { PathResponse, ParamsFor } from "@rangojs/router/client";
+import type { ParamsFor } from "@rangojs/router/client";
 
-// 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 }>
 
-// After mounting -- names get prefixed
-type BlogStats = PathResponse<"/blog/api/stats">;
+// After mounting -- names get prefixed.
+// Rango.PathResponse needs `RegisteredRoutes extends typeof router.routeMap` (see above),
+// otherwise it resolves to ResponseEnvelope<never>.
+type BlogStats = Rango.PathResponse<"/blog/api/stats">;
 // = ResponseEnvelope<{ views: number; visitors: number }>
 
 // Params work through nested includes

package/skills/route/SKILL.md

@@ -234,14 +234,22 @@ Cacheable vars (the default) can be read freely inside cache scopes.
 
 ### Revalidation Contracts for Handler Data
 
+> **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".
+
 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.
 
 ```typescript
 // revalidation-contracts.ts
+// 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 = ({ actionId }) =>
-  actionId?.includes("src/actions/checkout.ts#") ?? false;
+  actionId?.includes("src/actions/checkout.ts#") || undefined;
 
 path("/checkout", CheckoutPage, { name: "checkout" }, () => [
   revalidate(revalidateCheckoutData), // producer (route handler) reruns
@@ -270,9 +278,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
@@ -403,6 +408,10 @@ urls(({ path, layout }) => [
 ])
 ```
 
+## 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.

package/skills/router-setup/SKILL.md

@@ -71,7 +71,7 @@ urls(
 ## Router Options
 
 ```typescript
-interface RSCRouterOptions<TEnv> {
+interface RangoOptions<TEnv> {
   // URL patterns from urls() function
   urls: UrlPatterns;
 
@@ -405,7 +405,7 @@ interface AppBindings {
   KV: KVNamespace;
 }
 
-// Variables declared via module augmentation
+// Variables declared via global namespace augmentation
 interface AppVariables {
   user?: { id: string; name: string };
 }
@@ -417,7 +417,7 @@ const router = createRouter<AppBindings>({
 
 // Register types globally for implicit typing
 declare global {
-  namespace RSCRouter {
+  namespace Rango {
     interface Env extends AppBindings {}
     interface Vars extends AppVariables {}
   }

package/skills/server-actions/SKILL.md

@@ -32,35 +32,37 @@ Actions mutate state; route handlers and loaders read the latest state. After
 an action finishes, Rango performs a server-side revalidation render for the
 matched route so the UI receives fresh segment output and loader data.
 
-The main control point is `revalidate(({ actionId }) => ...)` on the segment
-that owns the data. This applies to `path()` handlers, `layout()` handlers,
-`parallel()` slots, `intercept()` routes, and loader registrations:
+The main control point is `revalidate((ctx) => ...)` on the segment that owns
+the data. Match specific actions by imported reference with `ctx.isAction()`;
+use raw `actionId` only when you intentionally need path or directory matching.
+This applies to `path()` handlers, `layout()` handlers, `parallel()` slots,
+`intercept()` routes, and loader registrations:
 
 ```typescript
 // urls.tsx — path/layout/parallel/intercept/loader/revalidate are passed in by urls()
 import { urls } from "@rangojs/router";
+import * as CartActions from "./actions/cart";
 
 export const urlpatterns = urls(({ path, loader, revalidate }) => [
   // The loader belongs to the route that consumes its data — nest it inside
   // the owning path() so the segment owns its data dependency.
   path("/cart", CartPage, { name: "cart" }, () => [
-    revalidate(
-      ({ actionId }) => actionId?.startsWith("src/actions/cart.ts#") ?? false,
-    ),
+    revalidate((ctx) => ctx.isAction(CartActions) || undefined),
     loader(CartLoader, () => [
-      revalidate(
-        ({ actionId }) => actionId?.startsWith("src/actions/cart.ts#") ?? false,
-      ),
+      revalidate((ctx) => ctx.isAction(CartActions) || undefined),
     ]),
   ]),
 ]);
 ```
 
-For module-level `"use server"` files, the `actionId` passed to every
+`ctx.isAction()` resolves the imported action reference the same way the router
+derives `actionId`, so it matches in both dev and production and survives action
+renames/moves as type errors instead of silent substring drift.
+
+For module-level `"use server"` files, the raw `actionId` passed to every
 server-side `revalidate()` predicate is path-bearing in the server/RSC
-environment in both dev and production: `src/actions/cart.ts#addToCart`. This
-is intentional so path, layout, parallel, intercept, and loader revalidation
-predicates can filter by action file, directory, or export name.
+environment in both dev and production: `src/actions/cart.ts#addToCart`. This is
+the escape hatch for broad filters by action file, directory, or export name.
 
 Actions and the follow-up revalidation render share one request context.
 Values written in the action with `ctx.set(MyVar, value)` or `ctx.set("key",
@@ -91,15 +93,18 @@ export async function switchTenant(tenantId: string) {
 ```typescript
 // urls.tsx
 import { urls } from "@rangojs/router";
+import * as TenantActions from "./actions/tenant";
 import { ChangedTenant } from "./context";
 
 export const urlpatterns = urls(({ path, revalidate }) => [
   path("/dashboard/:tenantId", DashboardPage, { name: "dashboard" }, () => [
-    revalidate(
-      ({ actionId, context }) =>
-        actionId?.startsWith("src/actions/tenant.ts#") &&
-        context.get(ChangedTenant) === context.params.tenantId,
-    ),
+    revalidate((ctx) => {
+      if (!ctx.isAction(TenantActions)) return undefined;
+      return (
+        ctx.context.get(ChangedTenant) === ctx.context.params.tenantId ||
+        undefined
+      );
+    }),
   ]),
 ]);
 ```
@@ -380,13 +385,18 @@ re-render so the UI updates. Rango runs the action, then evaluates
 `revalidate()` on matched segments and loaders. Each path, layout, parallel,
 intercept, or loader rule decides whether that piece re-renders/re-resolves.
 
-The `actionId` arrives as part of the revalidation context — match it to
-scope re-runs to specific actions.
+Use `ctx.isAction()` for specific actions or modules. It accepts one action,
+several actions, or a namespace import (`import * as CartActions`). Pair it with
+`|| undefined` for "revalidate on match, otherwise defer to defaults/downstream
+rules."
 
 ```typescript
 // urls.tsx — inside the urls() callback. Nest each loader inside the path(),
 // layout(), or parallel() that owns its data so the route tree mirrors the
 // data dependencies.
+import * as AccountActions from "./actions/account";
+import * as CartActions from "./actions/cart";
+
 urls(({ path, loader, revalidate }) => [
   path("/", HomePage, { name: "home" }, () => [
     // Loader data re-runs by default after any action. Opt out with revalidate(() => false).
@@ -395,36 +405,37 @@ urls(({ path, loader, revalidate }) => [
 
   // Re-render the cart page handler AND re-resolve its loader after cart actions
   path("/cart", CartPage, { name: "cart" }, () => [
-    revalidate(
-      ({ actionId }) => actionId?.startsWith("src/actions/cart.ts#") ?? false,
-    ),
+    revalidate((ctx) => ctx.isAction(CartActions) || undefined),
     loader(CartLoader, () => [
-      revalidate(
-        ({ actionId }) => actionId?.startsWith("src/actions/cart.ts#") ?? false,
-      ),
+      revalidate((ctx) => ctx.isAction(CartActions) || undefined),
     ]),
   ]),
 
-  // Re-run after any action under src/actions/account/
+  // Re-run after any action exported by the account actions module
   path("/account", AccountPage, { name: "account" }, () => [
     loader(AccountLoader, () => [
-      revalidate(
-        ({ actionId }) => actionId?.startsWith("src/actions/account/") ?? false,
-      ),
+      revalidate((ctx) => ctx.isAction(AccountActions) || undefined),
     ]),
   ]),
 ]);
 ```
 
-`actionId` is stable per action. For actions exported from a module-level
-`"use server"` file, the ID is prefixed with the source file path
-(`src/actions/cart.ts#addToCart`), so substring matching by file path is the
-recommended scope. **Inline `"use server"` actions** (declared inside an RSC
-component) intentionally keep their hashed IDs — file paths are withheld
-from the client for security. If you need file-path-based revalidation
-predicates, define the action in a module-level `"use server"` file rather
-than inline. See `/loader` for the full revalidation contract (deferred
-returns, soft suggestions).
+The raw `actionId` string stays available for broad path filters:
+
+```typescript
+// Match any action under src/actions/account/, including modules not imported here.
+revalidate(
+  ({ actionId }) => actionId?.startsWith("src/actions/account/") || undefined,
+);
+```
+
+For actions exported from a module-level `"use server"` file, the ID is prefixed
+with the source file path (`src/actions/cart.ts#addToCart`). **Inline `"use
+server"` actions** (declared inside an RSC component) intentionally keep their
+hashed IDs — file paths are withheld from the client for security. If you need
+file-path-based revalidation predicates, define the action in a module-level
+`"use server"` file rather than inline. See `/loader` for the full revalidation
+contract (deferred returns, soft suggestions).
 
 ### Cross-segment dependencies
 
@@ -434,8 +445,9 @@ stale context. Share the same `revalidate` predicate on both producer and
 consumer:
 
 ```typescript
-const revalidateCart = ({ actionId }) =>
-  actionId?.startsWith("src/actions/cart.ts#") ?? false;
+import * as CartActions from "./actions/cart";
+
+const revalidateCart = (ctx) => ctx.isAction(CartActions) || undefined;
 
 urls(({ path, layout, loader, revalidate }) => [
   layout(CartLayout, () => [