@rangojs/router 0.12.1 → 0.12.3

package/dist/vite/index.js

@@ -3746,7 +3746,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.12.1",
+  version: "0.12.3",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.12.1",
+  "version": "0.12.3",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",
@@ -206,8 +206,8 @@
     "esbuild": "^0.28.1",
     "happy-dom": "^20.10.1",
     "jiti": "^2.7.0",
-    "react": "^19.2.8",
-    "react-dom": "^19.2.8",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
     "vitest": "^4.1.9",
     "@shared/e2e": "0.0.1"
   },

package/skills/catalog.json

@@ -197,7 +197,7 @@
     },
     {
       "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.",
+      "description": "Enable the React Compiler in a Rango app with @vitejs/plugin-react 6.1's native `compiler` option (oxc-transform-react) — one flag, client components only, no Babel. Use when a consumer wants to turn React Compiler on, hits the dead plugin-react v6 `react({ babel })` path, sees an unmet-peer / ERESOLVE on oxc-transform-react, or is unsure why server components aren't being compiled.",
       "argumentHint": "",
       "path": "skills/react-compiler/SKILL.md"
     },

package/skills/rango/SKILL.md

@@ -289,7 +289,7 @@ Grouped by concern — read when you need to…
 | `/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                                                                 |
+| `/react-compiler`   | Enable React Compiler (opt-in) via plugin-react's native `compiler` option; client-only scope                                      |
 
 **Observability & production health**:
 

package/skills/react-compiler/SKILL.md

@@ -1,45 +1,49 @@
 ---
 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.
+description: Enable the React Compiler in a Rango app with @vitejs/plugin-react 6.1's native `compiler` option (oxc-transform-react) — one flag, client components only, no Babel. Use when a consumer wants to turn React Compiler on, hits the dead plugin-react v6 `react({ babel })` path, sees an unmet-peer / ERESOLVE on oxc-transform-react, 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.
+React Compiler is **opt-in** in Rango, and it is one option on the plugin you
+already have: `@vitejs/plugin-react` 6.1 ships a native React Compiler behind
+`react({ compiler: true })`, backed by
+[`oxc-transform-react`](https://www.npmjs.com/package/oxc-transform-react),
+Oxc's Rust port of the compiler. No Babel, no extra plugin, no ordering rules.
+Upstream marks the option experimental; the previous Babel wiring still works
+and is kept below as the [fallback](#babel-fallback).
 
 ## 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
+- **One option:** `react({ compiler: true })`. Needs `@vitejs/plugin-react` 6.1+
+  and its optional peer `oxc-transform-react`.
+- **It is client-only.** plugin-react runs the compiler only in environments
+  whose `consumer` is not `"server"`. Server/RSC components are not compiled,
+  and that is plugin-react's contract — 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).
+- **It owns JSX and Fast Refresh too.** With `compiler` on, plugin-react hands
+  TypeScript, JSX and Fast Refresh to the same native pass and disables Vite's
+  built-in refresh injection. Nothing to configure, and dev line numbers still
+  point at your source.
+- **Rango's build-time prerender is unaffected.** 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
+pnpm add -D oxc-transform-react@^0.145.0
 ```
 
+Take the range from `@vitejs/plugin-react`'s `peerDependencies` (`^0.145.0` for
+6.1.x) rather than npm's latest. `oxc-transform-react` cuts a new minor every
+couple of weeks and plugin-react widens its range in its own releases, so a newer
+binding shows up as an unmet-peer warning under pnpm and an `ERESOLVE` error
+under npm (vitejs/vite-plugin-react#1437). Bump both together.
+
 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.
+to install and **no** `target` option to set. Only pass `target: '17' | '18'` if
+you are on an older React.
 
 ## Step 2: Wire it in
 
@@ -48,16 +52,11 @@ to install and **no** `target` option to set. Only pass `target: '17' | '18'` to
 ```ts
 // vite.config.ts
 import { defineConfig } from "vite";
-import react, { reactCompilerPreset } from "@vitejs/plugin-react";
-import babel from "@rolldown/plugin-babel";
+import react from "@vitejs/plugin-react";
 import { rango } from "@rangojs/router/vite";
 
 export default defineConfig({
-  plugins: [
-    react(),
-    babel({ presets: [reactCompilerPreset()] }),
-    rango(), // supplies @vitejs/plugin-rsc
-  ],
+  plugins: [react({ compiler: true }), rango()],
 });
 ```
 
@@ -66,29 +65,29 @@ export default defineConfig({
 ```ts
 // vite.config.ts
 import { cloudflare } from "@cloudflare/vite-plugin";
-import react, { reactCompilerPreset } from "@vitejs/plugin-react";
-import babel from "@rolldown/plugin-babel";
+import react from "@vitejs/plugin-react";
 import { defineConfig } from "vite";
 import { rango } from "@rangojs/router/vite";
 
 export default defineConfig({
   plugins: [
-    react(),
-    babel({ presets: [reactCompilerPreset()] }),
+    react({ compiler: true }),
     rango({ preset: "cloudflare" }),
     cloudflare({
       /* ... */
-    }), // supplies @vitejs/plugin-rsc
+    }),
   ],
 });
 ```
 
+Both layouts keep `react()` ahead of `rango()` / `cloudflare()`, which is what
+Rango's own e2e apps run.
+
 ## 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**:
+plugin-react's `vite:react-compiler` transform runs in every environment, but
+passes `reactCompiler: false` whenever `environment.config.consumer === "server"`.
+Server environments only get the TypeScript/JSX pass:
 
 | Environment | `consumer` | Compiled? |
 | ----------- | ---------- | --------- |
@@ -96,43 +95,53 @@ even though the babel plugin is top-level, the transform runs **only in the
 | 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
+If you genuinely need to compile **server** components, the native option cannot
+do it; you would have to run `babel-plugin-react-compiler` yourself. That is not
 covered here.
 
 ## Options
 
-`reactCompilerPreset()` forwards to `babel-plugin-react-compiler`:
+`compiler` takes `true` or the React Compiler configuration plus one plugin-level
+flag:
+
+| 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+.                                                                         |
+| `logDiagnostics: true`          | Log recoverable compiler diagnostics (why a component was skipped) through Vite. Default `false`. Fatal diagnostics always fail the transform. |
 
-| 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+.                 |
+`logDiagnostics` can only relay what the binding reports. `oxc-transform-react`
+0.145.x, the range plugin-react 6.1 declares, reports bail-out reasons. 0.148.0
+dropped them (oxc-project/oxc#26318), so the flag goes silent once plugin-react's
+peer range moves past it; 0.146 and 0.147 still report but need a later
+plugin-react. Callback-valued Babel
+options (`logger`, function-valued `sources`) do not exist on the native path;
+`sources` takes an array of filename substrings.
 
 ## 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()`.
+(`resolveId` / `load`) and denies every `vite:*` plugin, so `vite:react-compiler`
+never runs there. 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 is compiled by the `react({ compiler: true })` in your
+app's own plugin array.
 
 ## Step 3: Verify the compiler actually ran
 
-A compiled module imports the cache allocator from `react/compiler-runtime` and
+The native compiler emits the same shape as `babel-plugin-react-compiler`. 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:
+reliable per-module signal in dev, and a compiled module also carries Fast
+Refresh's `$RefreshReg$(...)` registration:
 
 ```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\("
+  | grep -E "compiler-runtime|_c\(|\\\$RefreshReg\\\$\("
 ```
 
 For a production build, grep the built client bundle for the compiler's
@@ -150,19 +159,48 @@ 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.
 
+Output is not byte-identical to Babel's: the port tracks React's experimental
+compiler channel, so a handful of components memoize a different number of
+values, and comments inside a compiled function body are dropped. Neither changes
+rendered output.
+
+## Babel fallback
+
+On `@vitejs/plugin-react` < 6.1, or if you need a Babel-only compiler option, the
+previous wiring still works: a top-level
+[`@rolldown/plugin-babel`](https://www.npmjs.com/package/@rolldown/plugin-babel)
+running `reactCompilerPreset()` from `@vitejs/plugin-react`, placed **after
+`react()`** and **before the plugin that supplies `@vitejs/plugin-rsc`**. The
+preset gates itself to `consumer === "client"`, so the client-only contract is
+the same. Do not combine it with `compiler: true`.
+
+```bash
+pnpm add -D @rolldown/plugin-babel @babel/core babel-plugin-react-compiler @types/babel__core
+```
+
+```ts
+import react, { reactCompilerPreset } from "@vitejs/plugin-react";
+import babel from "@rolldown/plugin-babel";
+
+// plugins: [react(), babel({ presets: [reactCompilerPreset()] }), rango()]
+```
+
 ## 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. |
+| Symptom                                                                       | Cause / fix                                                                                                                                                                                             |
+| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `React Compiler requires the optional oxc-transform-react package` on startup | Install it (Step 1). plugin-react checks in its `config` hook, so the error is immediate.                                                                                                               |
+| Nothing is compiled; no `compiler-runtime` import anywhere                    | You used `react({ babel: { plugins: [...] } })`. plugin-react v6 has no internal Babel — use `react({ compiler: true })`.                                                                               |
+| pnpm warns `unmet peer oxc-transform-react`, npm fails with `ERESOLVE`        | The binding is newer than plugin-react's peer range. Pin the range plugin-react declares.                                                                                                               |
+| Client compiled, but server/RSC components are not                            | Expected. The option is client-only (see the table). Not a bug.                                                                                                                                         |
+| `logDiagnostics: true` prints nothing                                         | You are on `oxc-transform-react` 0.148.0 or later, which dropped recoverable diagnostics. On plugin-react 6.1.x stay on 0.145.x; 0.146 and 0.147 also report, but need a later plugin-react peer range. |
+| 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` repository — not shipped in this
-package: `docs/react-compiler.md` and the `react-compiler.test.ts` files under
-`e2e/e2e-basic`, `tests/cloudflare-basic`, and `tests/vite-rsc-demo`.
+contract and the Fast Refresh check) lives in the `@rangojs/router` repository —
+not shipped in this package: `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/view-transitions/SKILL.md

@@ -9,9 +9,9 @@ argument-hint: [layout|route|parallel|intercept]
 `transition()` opts a route (or group of routes) into transition-driven navigation. It does two things, and you choose how far to go:
 
 1. **`startTransition` (the foundation).** The navigation commit is driven through React's `startTransition`. That holds the previous content across a same-route navigation (stale-while-revalidate — no loading-skeleton flash) and is the **precondition** for any view-transition animation. Works on **all** React versions.
-2. **`<ViewTransition>` (the animation, layered on top).** On experimental React, rango also wraps the segment content in React's `<ViewTransition>` so the swap cross-fades/morphs. This is the only part that needs experimental React; pass `viewTransition: false` to keep #1 without it (and place your own `<ViewTransition>` where you want it).
+2. **`<ViewTransition>` (the animation, layered on top).** On React 19.3+ (or an experimental build), rango also wraps the segment content in React's `<ViewTransition>` so the swap cross-fades/morphs. This is the only part that needs 19.3+; pass `viewTransition: false` to keep #1 without it (and place your own `<ViewTransition>` where you want it).
 
-> The `<ViewTransition>` layer requires React experimental (the build that exports `<ViewTransition>` / `addTransitionType`). On stable React that layer is a no-op — but the `startTransition` driving (content hold) still applies.
+> The `<ViewTransition>` layer requires a React that exports `<ViewTransition>` / `addTransitionType`: stable 19.3+ or an experimental build. Rango feature-detects it; on React 19.2 that layer is a no-op — but the `startTransition` driving (content hold) still applies.
 
 ## Purpose: `startTransition` vs `<ViewTransition>`
 
@@ -24,11 +24,11 @@ These are two **independent** mechanisms. `startTransition` controls _fallbacks_
 
 The bottom-left cell is the key constraint: a view transition cannot exist without a `startTransition`. So once you reach for `transition()`, the only real choice is _startTransition_ vs _startTransition + ViewTransition_:
 
-| What you want                          | Config                                              | Effect                                                                                                 |
-| -------------------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
-| nothing (default nav)                  | no `transition()`                                   | remount + skeleton on param change                                                                     |
-| `startTransition` only                 | `transition({ viewTransition: false })`             | hold content; place your own `<ViewTransition>` where you want it                                      |
-| `startTransition` + `<ViewTransition>` | `transition({})` / `transition({ enter, exit, … })` | hold + router cross-fade (experimental React; on stable it degrades to the `startTransition`-only row) |
+| What you want                          | Config                                              | Effect                                                                                                        |
+| -------------------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| nothing (default nav)                  | no `transition()`                                   | remount + skeleton on param change                                                                            |
+| `startTransition` only                 | `transition({ viewTransition: false })`             | hold content; place your own `<ViewTransition>` where you want it                                             |
+| `startTransition` + `<ViewTransition>` | `transition({})` / `transition({ enter, exit, … })` | hold + router cross-fade (React 19.3+ or experimental; on 19.2 it degrades to the `startTransition`-only row) |
 
 `createRouter({ viewTransition: "auto" \| false })` sets the app-wide default for the third row; a per-segment `viewTransition` wins. See [Opting out of the router boundary](#opting-out-of-the-router-boundary-place-your-own-viewtransition) for the full opt-out story.
 
@@ -322,6 +322,24 @@ On stable React the "VT" column is always a no-op (there is no `<ViewTransition>
 
 > On **stable** React there is no `<ViewTransition>` at all, so `viewTransition: false` is visually a no-op there — but the startTransition driving and content-hold still apply, identical to `transition({})`.
 
+## Testing a transition() route
+
+On React 19.3+ a transition commit briefly keeps the exiting `<ViewTransition>`
+host in the DOM next to the entering one (hidden, carrying React's `vt-*`
+attributes) for a few hundred milliseconds. A strict Playwright locator on a
+test id that exists in both the old and the new view (same route, different
+params; a hard load followed by a revalidation commit) resolves to two elements
+during that window. Target the entering host, which is appended after the
+exiting one:
+
+```ts
+const page$ = page.getByTestId("feature-page").last();
+await expect(page$).toBeVisible();
+```
+
+Waiting for `toHaveCount(1)` first is not enough: the count passes through 1
+before the second host is inserted.
+
 ## Recommendations
 
 **Put `<ParallelOutlet />` in layouts, not routes.** A route-level `transition` wraps the route component itself, so a `<ParallelOutlet />` rendered directly inside that route component remains inside the route VT subtree — modal opens on a route with a parallel outlet _will_ trigger the route's VT walker. The narrowing fix only applies at layout boundaries. If you combine intercept modals with route-level transitions, mount the slot one level up in a layout.

package/src/segment-system.tsx

@@ -40,8 +40,9 @@ function segDebugLog(msg: string, details?: Record<string, unknown>): void {
   console.log(prefix);
 }
 
-// ViewTransition is only available in React experimental.
-// Access via namespace import to avoid compile-time errors on stable React.
+// ViewTransition ships in React 19.3+ (and experimental builds); older stable
+// releases lack it. Feature-detect via the namespace import so the router
+// compiles against any supported React and degrades to a no-op boundary.
 const ReactViewTransition: any =
   "ViewTransition" in React ? (React as any).ViewTransition : null;
 
@@ -435,7 +436,7 @@ export async function renderSegments(
       nodeContent = registerLazyRef(resolvedComponent);
     }
 
-    // Wrap with <ViewTransition> if transition config exists (React experimental only).
+    // Wrap with <ViewTransition> if transition config exists (React 19.3+ / experimental).
     // An empty config ({}) creates a bare <ViewTransition> boundary that participates
     // in transitions without adding custom animation classes. Named element-level
     // <ViewTransition> components inside (with name/share props) morph independently