@rangojs/router 0.16.0 → 0.17.0

package/skills/migrate-react-router/SKILL.md

@@ -6,7 +6,12 @@ argument-hint: path-to-react-router-app
 
 # Migrate from React Router to @rangojs/router
 
-Covers React Router v7 (framework mode and library mode), v6, and Remix v2.
+Covers React Router v7 (framework mode and library mode), v6, and Remix v2:
+choosing a target shape per route group, replacing imports, route mapping,
+loaders and actions, middleware, error/loading states, navigation, metadata,
+resource routes, theming, and Workers deployment. Use it when porting one of
+those apps to Rango. For Next.js apps see `/migrate-nextjs`; for a feature
+comparison rather than a port see `/comparison`.
 
 ## Why Rango
 
@@ -109,19 +114,19 @@ unsupported behavior until runtime, and keep the old packages in the dependency
 graph. Replace every `react-router` / `react-router-dom` / `@remix-run/*`
 import at its call site:
 
-| React Router import                           | Replace with                                                                                                         |
-| --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
-| `Link`, `NavLink`                             | `Link` from `@rangojs/router/client` (`NavLink` active state via `usePathname()`, see §6)                            |
-| `Outlet`                                      | `Outlet` from `@rangojs/router/client`                                                                               |
-| `useNavigate`                                 | `useRouter()` from `@rangojs/router/client` (see §6)                                                                 |
-| `useLocation`, `useSearchParams`, `useParams` | `usePathname()`, `useSearchParams()` (same `[params, setParams]` tuple), `useParams()` from `@rangojs/router/client` |
-| `useLoaderData`                               | merge the loader into the handler; `useLoader()` for live client data or `clientUrls()` routes (see §3)              |
-| `useActionData`                               | `useActionState` (standard React, see §3)                                                                            |
-| `Form`                                        | `<form action={serverAction}>` with a `"use server"` function (see §3)                                               |
-| `useFetcher`                                  | submits → server actions + `useActionState`/`useOptimistic`; reads → `useLoader()`                                   |
-| `defer` / `Await`                             | `loading()` DSL / plain `<Suspense>` (see §5)                                                                        |
-| `json()`, `redirect()`                        | plain return values; `redirect` from `@rangojs/router`                                                               |
-| `useRouteError`                               | the `error` prop of `errorBoundary()` (see §5)                                                                       |
+| React Router import                           | Replace with                                                                                                                                                                       |
+| --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Link`, `NavLink`                             | `Link` from `@rangojs/router/client` (`NavLink` active state via `usePathname()`, see §6)                                                                                          |
+| `Outlet`                                      | `Outlet` from `@rangojs/router/client`                                                                                                                                             |
+| `useNavigate`                                 | `useRouter()` from `@rangojs/router/client` (see §6)                                                                                                                               |
+| `useLocation`, `useSearchParams`, `useParams` | `usePathname()`, `useSearchParams()` (same `[params, setParams]` tuple), `useParams()` from `@rangojs/router/client`; `location.state` → typed `useLocationState()` (see `/hooks`) |
+| `useLoaderData`                               | merge the loader into the handler; `useLoader()` for live client data or `clientUrls()` routes (see §3)                                                                            |
+| `useActionData`                               | `useActionState` (standard React, see §3)                                                                                                                                          |
+| `Form`                                        | `<form action={serverAction}>` with a `"use server"` function (see §3)                                                                                                             |
+| `useFetcher`                                  | submits → server actions + `useActionState`/`useOptimistic`; reads → `useLoader()` / `useFetchLoader()` (see `/hooks`)                                                             |
+| `defer` / `Await`                             | `loading()` DSL / plain `<Suspense>` (see §5)                                                                                                                                      |
+| `json()`, `redirect()`                        | plain return values; `redirect` from `@rangojs/router`                                                                                                                             |
+| `useRouteError`                               | the `error` prop of `errorBoundary()` (see §5)                                                                                                                                     |
 
 If an import has no row here and no obvious Rango equivalent, stop and surface
 it to the user — do not mock it to keep the build green.
@@ -142,48 +147,54 @@ Each numbered step's full walkthrough lives in a companion file linked below.
 
 ## 11. Key Conceptual Differences
 
-| Concept             | React Router                        | Rango                                  |
-| ------------------- | ----------------------------------- | -------------------------------------- |
-| Rendering           | Client-side by default, SSR opt-in  | Server components by default (RSC)     |
-| Data loading        | `loader()` + `useLoaderData()`      | Direct fetch in server components      |
-| Form actions        | Route-scoped `action()`             | Function-scoped `"use server"`         |
-| Route definition    | File-based or `createBrowserRouter` | `urls()` DSL with `path()`, `layout()` |
-| Middleware          | Not built-in (use loaders)          | `router.use()` + DSL `middleware()`    |
-| Parallel routes     | Not built-in                        | `parallel()` DSL                       |
-| Intercepting routes | Not built-in                        | `intercept()` DSL                      |
-| Caching             | Not built-in                        | `cache()` DSL, `"use cache"`           |
-| Type-safe routes    | Partial (v7 framework mode)         | Full: params, names, href, reverse     |
+| Concept             | React Router                                                                | Rango                                  |
+| ------------------- | --------------------------------------------------------------------------- | -------------------------------------- |
+| Rendering           | Client-side by default, SSR opt-in                                          | Server components by default (RSC)     |
+| Data loading        | `loader()` + `useLoaderData()`                                              | Direct fetch in server components      |
+| Form actions        | Route-scoped `action()`                                                     | Function-scoped `"use server"`         |
+| Route definition    | File-based or `createBrowserRouter`                                         | `urls()` DSL with `path()`, `layout()` |
+| Middleware          | v7: route `middleware` export; v6 / Remix v2: none (guards live in loaders) | `router.use()` + DSL `middleware()`    |
+| Parallel routes     | Not built-in                                                                | `parallel()` DSL                       |
+| Intercepting routes | Not built-in                                                                | `intercept()` DSL                      |
+| Caching             | Not built-in                                                                | `cache()` DSL, `"use cache"`           |
+| Type-safe routes    | Partial (v7 framework mode)                                                 | Full: params, names, href, reverse     |
 
 ## Migration Checklist
 
 1. [ ] Set up Vite config with `rango()` plugin
-2. [ ] Create Document component with `<MetaTags />` in head
+2. [ ] Create Document component with `<Html.Meta />` in head
 3. [ ] Create `router.tsx` with `createRouter()`
 4. [ ] Convert route config / file routes to `urls()` DSL
 5. [ ] Migrate layouts — keep `<Outlet />` (import from `@rangojs/router/client`)
-6. [ ] Merge loaders + components into handler functions (fetch + render in one place)
+6. [ ] Merge loaders + components into handler functions (fetch + render in one place),
+       or port hook-heavy groups with `clientUrls()` (see "Two target shapes")
 7. [ ] Convert React Router actions to `"use server"` functions
 8. [ ] Migrate auth guards from loaders to `router.use()`
 9. [ ] Replace `react-router-dom` Link/navigation with `@rangojs/router/client`
 10. [ ] Convert error boundaries to `errorBoundary()` DSL
-11. [ ] Update metadata to use `Meta` handle + `<MetaTags />`
+11. [ ] Update metadata to use `Meta` handle + `<Html.Meta />`
 12. [ ] Replace custom theme provider with `theme: true` in createRouter (see `/theme`)
 13. [ ] Run `npx rango generate src/` to generate route types
 14. [ ] Verify no shims: `grep -rnE "from ['\"](react-router|@remix-run)" src/ app/`
         returns nothing, no mock modules or aliases exist, and the packages are
         out of `package.json`
 
-**Cloudflare Workers (if migrating an RR7-on-Workers app):**
+**Cloudflare Workers (if migrating an RR7-on-Workers app):** the linked
+sections are in [`../cloudflare/references/streaming-and-deploy.md`](../cloudflare/references/streaming-and-deploy.md).
 
-14. [ ] Audit the custom worker entry — the `router.fetch()` response must pass
+15. [ ] Audit the custom worker entry — the `router.fetch()` response must pass
         through as a **stream** (`new Response(response.body, response)`); remove
         any `.text()`/`.arrayBuffer()`/`HTMLRewriter` buffering from the Rango
-        path (keep it only on legacy/proxy branches). See §10a.
-15. [ ] Switch local dev to `vite dev` / `vite preview` (they stream + load
+        path (keep it only on legacy/proxy branches). See
+        [Keep streamed responses intact](../cloudflare/references/streaming-and-deploy.md#keep-streamed-responses-intact).
+16. [ ] Switch local dev to `vite dev` / `vite preview` (they stream + load
         `.dev.vars` + provide bindings); stop using `wrangler dev` for local
-        verification — it gzip-buffers and kills streaming. See §10b.
-16. [ ] Move build output paths from RR7's `build/` to vite's `dist/` in
-        `wrangler.toml` (`assets` → `./dist/client/`) and cleanup scripts. See §10d.
-17. [ ] Fix deploy to use the built config `dist/<env>/wrangler.json`
-        (`no_bundle: true`), not a root `wrangler deploy` against the source
-        worker entry (which can't bundle Rango's virtual modules). See §10e.
+        verification — its local gzip can buffer and hide streaming. See
+        [Use Vite for local RSC work](../cloudflare/references/streaming-and-deploy.md#use-vite-for-local-rsc-work).
+17. [ ] Move build output paths from RR7's `build/` to vite's `dist/`: client
+        assets land in `dist/client/`; update cleanup scripts to match.
+18. [ ] Deploy with the generated config (`wrangler deploy -c dist/rsc/wrangler.json`,
+        or `dist/<name>/wrangler.json` for a custom RSC environment name), not a
+        root `wrangler deploy` against the source worker entry (Wrangler cannot
+        rebuild Rango's Vite virtual modules). See
+        [Deploy the built Worker](../cloudflare/references/streaming-and-deploy.md#deploy-the-built-worker).

package/skills/migrate-react-router/component-migration.md

@@ -2,7 +2,8 @@
 
 ## 4. Middleware / Route Protection
 
-React Router doesn't have built-in middleware. Protection is typically done in loaders:
+React Router v6 and Remix v2 have no middleware, so protection is typically done
+in loaders (v7 route `middleware` exports map to the same Rango shape below):
 
 ```typescript
 // React Router: auth check in loader
@@ -13,9 +14,27 @@ export async function loader({ request }) {
 }
 
 // Rango: router.use() for request-level auth
+import {
+  createRouter,
+  cookies,
+  redirect,
+  type Middleware,
+} from "@rangojs/router";
+
+const authInit: Middleware = async (ctx, next) => {
+  const session = cookies().get("session")?.value;
+  if (session) ctx.set("user", await getUserFromSession(session));
+  await next();
+};
+
+const requireAuth: Middleware = async (ctx, next) => {
+  if (!ctx.get("user")) return redirect("/login");
+  await next();
+};
+
 const router = createRouter({})
   .use(authInit) // all routes — resolves session
-  .use("/dashboard/*", requireAuth) // scoped guard
+  .use("/dashboard/*", requireAuth) // /dashboard and everything under it
   .routes(urlpatterns);
 ```
 
@@ -122,7 +141,7 @@ export function meta() {
 }
 
 // Rango: Meta handle in server handlers
-import { Meta } from "@rangojs/router";
+import { Meta, type Handler } from "@rangojs/router";
 
 const HomePage: Handler<"home"> = (ctx) => {
   const meta = ctx.use(Meta);
@@ -137,16 +156,16 @@ owns the data — `ctx.use(Meta)({ title: data.name })` in the loader body, with
 `loader(Def, { ssr: false })` when the title must be in the SSR'd
 head. See `/loader` → "Writing Handles from Loaders".
 
-Add `<MetaTags />` in the Document component's `<head>`:
+Add `<Html.Meta />` in the Document component's `<head>`:
 
 ```typescript
-import { MetaTags } from "@rangojs/router/client";
+import { Html } from "@rangojs/router/client";
 
 function Document({ children }: { children: ReactNode }) {
   return (
     <html>
       <head>
-        <MetaTags />
+        <Html.Meta />
       </head>
       <body>{children}</body>
     </html>

package/skills/migrate-react-router/data-and-actions.md

@@ -20,6 +20,8 @@ function ProductPage() {
 }
 
 // Rango: handler fetches and renders directly
+import type { Handler } from "@rangojs/router";
+
 const ProductPage: Handler<"product"> = async (ctx) => {
   const product = await getProduct(ctx.params.slug);
   return <div>{product.name}</div>;
@@ -76,6 +78,7 @@ function EditProfile() {
 }
 
 // Rango: "use server" action + native form or useActionState
+// actions/profile.ts
 "use server";
 import { redirect } from "@rangojs/router";
 
@@ -84,7 +87,10 @@ export async function updateProfile(formData: FormData): Promise<void> {
   throw redirect("/profile");
 }
 
-// Client component:
+// EditProfile.tsx — a server or client component; passing the action itself
+// (not a wrapper function) keeps the form working with JavaScript disabled.
+import { updateProfile } from "./actions/profile";
+
 function EditProfile() {
   return (
     <form action={updateProfile}>
@@ -122,9 +128,12 @@ function ProductPrice() {
 }
 ```
 
-`useLoader()` provides live data that stays fresh — it re-fetches on navigation
-and after actions (controlled by `revalidate()`). This is different from
-`useLoaderData()` which just reads a snapshot.
+`useLoader()` provides live data that stays fresh — the loader re-runs on
+navigation and after actions (controlled by `revalidate()`), and the result also
+exposes `isLoading`, `error`, `load`, and `refetch`. Register the loader on the
+route (`loader(PriceLoader)`) so its data is in the tree the component reads;
+the read suspends until it arrives, so keep a `<Suspense>` or `loading()` above
+it. See `/loader` and `/hooks`.
 
 ### useActionData
 
@@ -155,8 +164,12 @@ function EditForm() {
 // Rango: useActionState (standard React hook)
 "use client";
 import { useActionState } from "react";
-import { saveForm } from "../actions"; // "use server" function
+// "use server" function with the useActionState shape:
+//   export async function saveForm(prev: State, formData: FormData): Promise<State>
+import { saveForm } from "../actions";
 
+// Pass the imported action straight to useActionState — not an inline closure —
+// so the form still posts and re-renders with JavaScript disabled.
 function EditForm() {
   const [state, action, pending] = useActionState(saveForm, null);
   return (

package/skills/migrate-react-router/route-mapping.md

@@ -10,9 +10,13 @@ npm remove react-router @react-router/dev @react-router/node @react-router/serve
 # Library mode:
 npm remove react-router react-router-dom
 
-npm install @rangojs/router
+npm install @rangojs/router   # keep react and react-dom
 ```
 
+`rango()` includes `@vitejs/plugin-rsc` and supplies the client and server
+entries. Add `@vitejs/plugin-react` only if you want Fast Refresh or the React
+Compiler.
+
 Replace the `@react-router/dev` Vite plugin with `rango()`:
 
 ```typescript
@@ -34,7 +38,7 @@ import { createRouter } from "@rangojs/router";
 import { Document } from "./document";
 import { urlpatterns } from "./urls";
 
-export default createRouter({
+export const router = createRouter({
   document: Document,
 }).routes(urlpatterns);
 ```
@@ -58,7 +62,7 @@ loader                      → fetch in handler, or createLoader() — a Rango
 action                      → "use server" function
 meta                        → ctx.use(Meta) in handler; meta({ data }) →
                               ctx.use(Meta) push in the loader that owns data
-headers                     → ctx.header() in handler or middleware
+headers                     → ctx.headers.set() in a handler; ctx.header() in middleware
 shouldRevalidate            → revalidate() DSL
 ErrorBoundary               → errorBoundary() DSL
 HydrateFallback             → loading() DSL
@@ -107,15 +111,15 @@ export function ErrorBoundary() {
 
 ```typescript
 // Rango: urls.tsx + handler
-import { notFound } from "@rangojs/router";
+import { Meta, notFound, type Handler } from "@rangojs/router";
 
 const ProductPage: Handler<"product"> = async (ctx) => {
   const product = await getProduct(ctx.params.slug);
-  if (!product) notFound("Product not found");
+  if (!product) notFound("Product not found"); // throws: nearest notFoundBoundary, else the router's notFound
 
   const meta = ctx.use(Meta);
   meta({ title: product.name });
-  ctx.header("Cache-Control", "max-age=300");
+  ctx.headers.set("Cache-Control", "max-age=300"); // response headers
 
   return <div>{product.name}</div>;
 };
@@ -130,6 +134,8 @@ path("/product/:slug", ProductPage, { name: "product" }, () => [
 
 Key shift: the route module's scattered exports consolidate into the handler
 (data fetching, meta, headers) and the DSL (revalidation, error boundary, loading).
+The `action` export becomes a `"use server"` function (see
+[`./data-and-actions.md`](./data-and-actions.md)).
 
 The loader-shaped variant is equally valid — and closer to the RR module when
 the loader carried authority. A `createLoader()` body can throw `notFound()`

package/skills/mime-routes/SKILL.md

@@ -15,12 +15,14 @@ See also: `/response-routes` for the base response route API (path.json, path.te
 ## Defining Negotiated Routes
 
 Declare the same URL pattern with both an RSC route and one or more response-type routes.
-Order within the `urls()` array does not matter — the trie merges them at build time.
+The trie merges them into one negotiated leaf at build time, whatever their order. Order
+only decides the default for `*/*`, a missing `Accept`, or an `Accept` no variant serves:
+the first-defined route wins (rule 4 below).
 
 ```typescript
 import { urls } from "@rangojs/router";
 
-export const urlpatterns = urls(({ path, layout, include }) => [
+export const urlpatterns = urls(({ path }) => [
   // RSC page + JSON API on the same URL
   path("/products/:id", ProductPage, { name: "product" }),
   path.json(
@@ -38,10 +40,10 @@ When an API client requests the same URL (`Accept: application/json`), the JSON
 
 ## Negotiation Rules
 
-1. **Q-value priority** — higher `q` wins (`Accept: application/json;q=0.9, text/html;q=1.0` serves RSC)
+1. **Q-value priority** — higher `q` wins (`Accept: application/json;q=0.9, text/html;q=1.0` serves RSC); `q=0` entries are ignored
 2. **Client order tiebreaker** — when q-values are equal, the type listed first in Accept wins (matches Express/Hono behavior)
-3. **Specific MIME match** — the variant whose MIME type appears in Accept wins
-4. **Wildcard / empty Accept** — `*/*` and missing Accept fall back to route definition order (the first-defined variant wins); when the RSC route wins this way, it serves the HTML document
+3. **Specific MIME match** — the variant whose MIME type appears in Accept wins; a type wildcard such as `text/*` picks the first candidate of that type
+4. **Wildcard / empty / unmatched Accept** — `*/*`, a missing Accept, and an Accept that no candidate serves fall back to route definition order (the first-defined variant wins); when the RSC route wins this way, it serves the HTML document
 5. **All responses** on a negotiated URL get `Vary: Accept` header, including the RSC side
 
 RSC participates as a candidate alongside response-type variants under two MIME
@@ -150,9 +152,12 @@ no payloads, so response types resolve to `never`.
 1. **Build time**: `buildRouteTrie()` calls `mergeLeaves()` when multiple routes share a pattern.
    RSC routes become the primary trie leaf; response-type routes are stored in the `nv`
    (negotiate variants) array on the leaf. The `rf` (rsc-first) flag tracks definition order.
-2. **Runtime**: `previewRoute()` reads `negotiateVariants` from the trie match result.
+2. **Runtime**: `negotiateRoute()` (called during request classification) reads `negotiateVariants` from the trie match result.
    It parses the `Accept` header (extracting q-values and order), builds a candidate list
-   (RSC as `text/html` + response-type variants), and calls `pickNegotiateVariant()`.
+   (the response-type variants in definition order, plus RSC as `text/html` and `text/x-component` —
+   placed first when the RSC route was defined first, otherwise last),
+   and calls `pickNegotiateVariant()`. When a variant with different param names wins
+   (`/widgets/:id` vs `/widgets/:file`), params are re-keyed to the variant's names.
 3. **Candidate matching**: walks the client's sorted Accept list (by q desc, then order asc),
    matching each entry against candidates. Wildcards (`*/*`, `text/*`) fall back to definition order.
 4. **Vary header**: both the response-route handler wrapper and the RSC handler wrapper

package/skills/observability/SKILL.md

@@ -9,15 +9,17 @@ argument-hint:
 Use this when you need to understand request latency, cache decisions,
 revalidation behavior, loader overlap, or production traces.
 
-Rango exposes two complementary observability surfaces:
+Rango exposes three complementary observability surfaces:
 
 1. **Performance timeline** (`debugPerformance`) — per-request waterfall for
    local or targeted debugging. It prints to the console and emits
    `Server-Timing`.
-2. **Structured telemetry** (`telemetry`) — lifecycle events sent to a pluggable
-   sink for production monitoring, OpenTelemetry, or custom metrics.
+2. **Structured telemetry** (`telemetry`) — discrete lifecycle events sent to a
+   pluggable sink for production monitoring, OpenTelemetry, or custom metrics.
+3. **Tracing** (`tracing`) — the same phases as the timeline, emitted as spans
+   into OpenTelemetry, Cloudflare Workers, or Vercel traces.
 
-The essentials are below. The exported `TelemetryEvent` union type
+All three are off by default. The essentials are below. The exported `TelemetryEvent` union type
 (`import type { TelemetryEvent } from "@rangojs/router"`) is the full event
 contract — every event kind and its fields are typed there.
 
@@ -35,7 +37,8 @@ const router = createRouter({
 });
 ```
 
-Or enable for selected requests from middleware:
+Or enable for selected requests from middleware (route `middleware()` inside
+`urls()`, or `router.use()` for every request):
 
 ```typescript
 middleware(async (ctx, next) => {
@@ -52,11 +55,19 @@ shared-axis waterfall and adds a `Server-Timing` header.
 Read the timeline as intervals:
 
 - `handler:total` is the whole router request.
-- `render:total` / `ssr-render-html` show the render pass.
-- `loader:*` rows should overlap render work. If a loader starts only after the
-  render bar, it is serialized latency.
-- Cache, route matching, middleware pre/post, RSC serialization, and SSR phases
-  appear as separate spans, so the slow phase is visible without guessing.
+- `render:total:<routeName>` (or `render:total` for unnamed routes) and
+  `ssr:render-html` show the render pass.
+- `loader:<id>` rows should overlap render work. If a loader starts only after
+  the render bar, it is serialized latency.
+- Route matching (`match:*`), middleware (`middleware:<name>:pre` / `:post`),
+  actions (`action:<id>`), cache, RSC serialization, and SSR setup appear as
+  separate rows, so the slow phase is visible without guessing.
+
+The console waterfall uses these labels as written. In the `Server-Timing`
+header, colons become hyphens and other non-alphanumeric characters are
+dropped (`ssr:render-html` → `ssr-render-html`, `handler:total` →
+`handler-total`), and nested rows get a `d<depth>-` prefix. The full metric
+list is in the repository's `packages/rangojs-router/docs/telemetry.md`.
 
 **Deployed Cloudflare caveat**: on production Workers, timers are frozen
 during request execution (Spectre mitigation), so `Server-Timing` durations
@@ -106,7 +117,9 @@ const router = createRouter({
 On **Cloudflare Workers**, use `createCloudflareTracing` for the `tracing` slot
 instead — it emits the same phases as native Cloudflare custom spans (in the
 Workers trace waterfall, next to the automatic KV/D1/fetch spans), with no
-`@opentelemetry/api` dependency:
+`@opentelemetry/api` dependency. It reads the tracer from the `ctx` your Worker
+passes to `router.fetch(request, { env, ctx })`, and is a pass-through when
+Workers tracing is not enabled for the Worker:
 
 ```typescript
 import { createRouter } from "@rangojs/router";
@@ -226,6 +239,7 @@ Then inspect:
 
 ## Zero-overhead defaults
 
-`debugPerformance` is off by default, and `telemetry` emits nothing unless a sink
-is configured. Per-request `ctx.debugPerformance()` lets you turn on the
-waterfall only for the route, user, or query param you are investigating.
+`debugPerformance` is off by default, `telemetry` emits nothing unless a sink
+is configured, and with `tracing` unset every span call runs the work directly.
+Per-request `ctx.debugPerformance()` lets you turn on the waterfall only for the
+route, user, or query param you are investigating.