@rangojs/router 0.0.0-experimental.35 → 0.0.0-experimental.358c376d

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

@@ -0,0 +1,236 @@
+# Data Fetching and Actions
+
+## 3. Data Fetching
+
+### Loaders → handler (the default migration)
+
+In React Router, loaders and components are separate: the loader fetches data,
+the component renders it via `useLoaderData()`. In Rango, server component
+handlers do both — combine the loader and component into a single handler:
+
+```typescript
+// React Router: separate loader + component
+export async function loader({ params }) {
+  const product = await getProduct(params.slug);
+  return { product };
+}
+function ProductPage() {
+  const { product } = useLoaderData();
+  return <div>{product.name}</div>;
+}
+
+// Rango: handler fetches and renders directly
+const ProductPage: Handler<"product"> = async (ctx) => {
+  const product = await getProduct(ctx.params.slug);
+  return <div>{product.name}</div>;
+};
+```
+
+This is the standard migration path. The handler IS the loader — it fetches
+data, then returns JSX. No separate data-fetching layer needed.
+
+### When to use createLoader()
+
+Rango's `createLoader()` is a live data layer, not a loader migration target.
+Use it only when you need capabilities beyond what the handler provides:
+
+- **Client-side reactive data** — `useLoader()` in client components for data
+  that updates without a full page navigation
+- **Shared data across segments** — a loader registered on a layout is available
+  to all child routes via `ctx.use(Loader)` or `useLoader(Loader)`
+- **Independent revalidation** — `revalidate()` on a specific loader after actions
+- **Per-loader caching** — `loader(L, () => [cache({ ttl: 60 })])`
+- **RR-loader-shaped authority** — a loader that `throw redirect(...)`s or
+  throws a 404 keeps that shape: Rango loaders throw `redirect()`/`notFound()`
+  too (one caveat: a Rango loader redirect is a client-side navigate on
+  document loads, never an HTTP 302 — pre-stream 302s move to middleware)
+- **`meta({ data })` / `handle` exports** — data-derived page metadata becomes
+  a handle push from the loader body (`ctx.use(Meta)({ title: data.name })`),
+  with `loader(L, { stream: "navigation" })` when it must be in the SSR'd head
+
+If the React Router loader just fetches data for its page component AND the
+component can become a server component, merge it into the handler. If the
+component stays a client component, port the whole group with `clientUrls()`
+instead — loader, `useLoader` read, and browser-run `revalidate()` keep the RR
+route-module shape (see the "Two target shapes" section in the main skill and
+`/client-urls`). See `/loader` for when the live data layer is useful.
+
+### Actions
+
+React Router form actions map to Rango server actions:
+
+```typescript
+// React Router:
+export async function action({ request }) {
+  const formData = await request.formData();
+  await updateUser(formData.get("name"));
+  return redirect("/profile");
+}
+function EditProfile() {
+  return (
+    <Form method="post">
+      <input name="name" />
+      <button type="submit">Save</button>
+    </Form>
+  );
+}
+
+// Rango: "use server" action + native form or useActionState
+"use server";
+import { redirect } from "@rangojs/router";
+
+export async function updateProfile(formData: FormData): Promise<void> {
+  await updateUser(formData.get("name") as string);
+  throw redirect("/profile");
+}
+
+// Client component:
+function EditProfile() {
+  return (
+    <form action={updateProfile}>
+      <input name="name" />
+      <button type="submit">Save</button>
+    </form>
+  );
+}
+```
+
+Key difference: React Router actions are route-scoped (declared per route).
+Rango actions are function-scoped (`"use server"` on any exported async function).
+
+### useLoaderData
+
+There is no `useLoaderData()` in Rango. For most cases, the handler fetches
+and renders directly (see above). When a client component needs live reactive
+data, use `createLoader()` + `useLoader()`:
+
+```typescript
+// React Router: useLoaderData() in client component
+function ProductPrice() {
+  const { price } = useLoaderData();
+  return <span>{price}</span>;
+}
+
+// Rango: useLoader() reads from a registered loader (live data layer)
+"use client";
+import { useLoader } from "@rangojs/router/client";
+import { PriceLoader } from "../loaders";
+
+function ProductPrice() {
+  const { data } = useLoader(PriceLoader);
+  return <span>{data.price}</span>;
+}
+```
+
+`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.
+
+### useActionData
+
+React Router's `useActionData()` reads the return value of a route-scoped
+`action()`. In Rango, actions are standard React server actions (`"use server"`),
+so all React patterns apply directly:
+
+```typescript
+// React Router:
+export async function action({ request }) {
+  const form = await request.formData();
+  const errors = validate(form);
+  if (errors) return { errors };
+  await save(form);
+  return { ok: true };
+}
+function EditForm() {
+  const data = useActionData();
+  return (
+    <Form method="post">
+      {data?.errors && <p>{data.errors}</p>}
+      <input name="title" />
+      <button>Save</button>
+    </Form>
+  );
+}
+
+// Rango: useActionState (standard React hook)
+"use client";
+import { useActionState } from "react";
+import { saveForm } from "../actions"; // "use server" function
+
+function EditForm() {
+  const [state, action, pending] = useActionState(saveForm, null);
+  return (
+    <form action={action}>
+      {state?.errors && <p>{state.errors}</p>}
+      <input name="title" />
+      <button disabled={pending}>Save</button>
+    </form>
+  );
+}
+```
+
+Since Rango uses RSC server actions, all React action patterns work:
+`useActionState`, `useOptimistic`, `useTransition`, `startTransition`,
+and plain `<form action={serverAction}>`. No framework-specific hook needed.
+
+For the full guide — defining actions, validation with Zod, error handling,
+revalidation rules, file uploads, and progressive enhancement — see
+`/server-actions`.
+
+### clientLoader / clientAction (framework mode)
+
+RR7 framework mode's `clientLoader` and `clientAction` run in the browser.
+Rango does not have a framework-level client loader/action concept — these
+migrate to standard React client-side code:
+
+```typescript
+// RR7: clientLoader fetching from a third-party API
+export async function clientLoader() {
+  const res = await fetch("https://api.weather.com/current?city=london");
+  return res.json();
+}
+
+// Rango: "use client" component with hooks
+"use client";
+import { useState, useEffect } from "react";
+
+function WeatherWidget() {
+  const [weather, setWeather] = useState(null);
+  useEffect(() => {
+    fetch("https://api.weather.com/current?city=london")
+      .then((r) => r.json())
+      .then(setWeather);
+  }, []);
+  if (!weather) return <span>Loading...</span>;
+  return <span>{weather.temp}°C</span>;
+}
+```
+
+The general rule: anything that ran in `clientLoader`/`clientAction` moves into
+React hooks (`useState`, `useEffect`, `useActionState`, `useOptimistic`) inside
+a `"use client"` component. There is no framework wrapper — it's just React.
+
+### shouldRevalidate (framework mode)
+
+RR7's `shouldRevalidate` export maps directly to Rango's `revalidate()` DSL:
+
+```typescript
+// RR7:
+export function shouldRevalidate({ actionResult, currentParams, nextParams }) {
+  if (actionResult) return true;
+  return currentParams.slug !== nextParams.slug;
+}
+
+// Rango:
+path("/product/:slug", ProductPage, { name: "product" }, () => [
+  revalidate(({ actionId, currentParams, nextParams }) => {
+    if (actionId) return true;
+    return currentParams.slug !== nextParams.slug;
+  }),
+]);
+```
+
+Note: RR7's `shouldRevalidate` controls client-side loader re-fetching. Rango's
+`revalidate()` controls which segments re-run during partial rendering after
+navigation or actions. The intent is the same — skip unnecessary work — but
+the mechanism is segment-level rather than loader-level.

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

@@ -0,0 +1,284 @@
+# Project Setup and Route Mapping
+
+## 1. Project Setup
+
+Replace React Router tooling with Vite + Rango:
+
+```bash
+# Framework mode:
+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
+```
+
+Replace the `@react-router/dev` Vite plugin with `rango()`:
+
+```typescript
+// vite.config.ts
+// Before: import { reactRouter } from "@react-router/dev/vite";
+import { defineConfig } from "vite";
+import { rango } from "@rangojs/router/vite";
+
+export default defineConfig({
+  plugins: [rango()],
+});
+```
+
+Delete `react-router.config.ts` — route configuration moves to the `urls()` DSL.
+
+```typescript
+// src/router.tsx
+import { createRouter } from "@rangojs/router";
+import { Document } from "./document";
+import { urlpatterns } from "./urls";
+
+export default createRouter({
+  document: Document,
+}).routes(urlpatterns);
+```
+
+## 2. Route Mapping
+
+### RR7 framework mode: route modules → urls() DSL
+
+In framework mode, each route is a file with conventional exports (`loader`,
+`action`, `default`, `meta`, `headers`, `shouldRevalidate`, `handle`,
+`ErrorBoundary`, `HydrateFallback`). In Rango, all of these become part of the
+`urls()` DSL or move into the server component handler:
+
+```text
+RR7 route module export     → Rango equivalent
+─────────────────────────────────────────────────────
+default (Component)         → handler in path()
+loader                      → fetch in handler, or createLoader() — a Rango
+                              loader keeps the RR shape: throw redirect()/
+                              notFound(), push meta from the body
+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
+shouldRevalidate            → revalidate() DSL
+ErrorBoundary               → errorBoundary() DSL
+HydrateFallback             → loading() DSL
+handle                      → createHandle() for cross-segment data (breadcrumbs, etc.)
+clientLoader / clientAction → "use client" component with React hooks
+```
+
+#### Example: full route module migration
+
+```typescript
+// RR7 framework mode: app/routes/product.$slug.tsx
+import type { Route } from "./+types/product.$slug";
+
+export async function loader({ params }: Route.LoaderArgs) {
+  const product = await getProduct(params.slug);
+  if (!product) throw new Response("Not Found", { status: 404 });
+  return { product };
+}
+
+export async function action({ request }: Route.ActionArgs) {
+  const formData = await request.formData();
+  await addToCart(formData.get("productId") as string);
+  return { ok: true };
+}
+
+export function meta({ data }: Route.MetaArgs) {
+  return [{ title: data.product.name }];
+}
+
+export function headers() {
+  return { "Cache-Control": "max-age=300" };
+}
+
+export function shouldRevalidate({ actionResult }) {
+  return !!actionResult;
+}
+
+export default function ProductPage({ loaderData }: Route.ComponentProps) {
+  return <div>{loaderData.product.name}</div>;
+}
+
+export function ErrorBoundary() {
+  return <div>Product error</div>;
+}
+```
+
+```typescript
+// Rango: urls.tsx + handler
+import { notFound } from "@rangojs/router";
+
+const ProductPage: Handler<"product"> = async (ctx) => {
+  const product = await getProduct(ctx.params.slug);
+  if (!product) notFound("Product not found");
+
+  const meta = ctx.use(Meta);
+  meta({ title: product.name });
+  ctx.header("Cache-Control", "max-age=300");
+
+  return <div>{product.name}</div>;
+};
+
+// In urls.tsx:
+path("/product/:slug", ProductPage, { name: "product" }, () => [
+  revalidate(({ actionId }) => !!actionId),
+  errorBoundary(() => <div>Product error</div>),
+  loading(<ProductSkeleton />),
+])
+```
+
+Key shift: the route module's scattered exports consolidate into the handler
+(data fetching, meta, headers) and the DSL (revalidation, error boundary, loading).
+
+The loader-shaped variant is equally valid — and closer to the RR module when
+the loader carried authority. A `createLoader()` body can throw `notFound()`
+for the missing product AND push the data-derived meta itself
+(`ctx.use(Meta)({ title: product.name })`); register it with
+`loader(ProductLoader, { stream: "navigation" })` when the 404 status and
+title must be in the document deterministically. See `/loader` → "Loader
+Authority" and "Writing Handles from Loaders". (One RR habit that does NOT
+carry over: a loader `throw redirect()` is a client-side navigate on document
+loads, never an HTTP 302 — pre-stream 302s belong in middleware.)
+
+### RR7 file routing → urls() DSL
+
+| RR7 file path                            | Rango                                                         |
+| ---------------------------------------- | ------------------------------------------------------------- |
+| `app/routes/_index.tsx`                  | `path("/", HomePage, { name: "home" })`                       |
+| `app/routes/about.tsx`                   | `path("/about", AboutPage, { name: "about" })`                |
+| `app/routes/blog.$slug.tsx`              | `path("/blog/:slug", BlogPost, { name: "blogPost" })`         |
+| `app/routes/files.$.tsx` (splat)         | `path("/files/:path*", FileBrowser, { name: "files" })`       |
+| `app/routes/dashboard.tsx` (layout)      | `layout(<DashboardLayout />, () => [...])`                    |
+| `app/routes/dashboard._index.tsx`        | `path("/dashboard", DashboardIndex, { name: "dashboard" })`   |
+| `app/routes/dashboard.settings.tsx`      | `path("/dashboard/settings", Settings, { name: "settings" })` |
+| `app/routes/_auth.tsx` (pathless layout) | `layout(<AuthLayout />, () => [...])`                         |
+| `app/routes/_auth.login.tsx`             | `path("/login", LoginPage, { name: "login" })`                |
+
+### Library mode: config routes → urls() DSL
+
+| React Router                           | Rango                                                   |
+| -------------------------------------- | ------------------------------------------------------- |
+| `path: "/"`                            | `path("/", HomePage, { name: "home" })`                 |
+| `path: "about"`                        | `path("/about", AboutPage, { name: "about" })`          |
+| `path: "blog/:slug"`                   | `path("/blog/:slug", BlogPost, { name: "blogPost" })`   |
+| `path: "files/*"` (splat)              | `path("/files/:path*", FileBrowser, { name: "files" })` |
+| `path: "docs/:lang?"` (optional param) | `path("/docs/:lang?", Docs, { name: "docs" })`          |
+
+The RR splat (`$` / `*`) matches the bare parent too (`/files` binds `""`), so
+it maps to `:path*` (zero-or-more). Use `:path+` only when you require at least
+one trailing segment. RR reads the splat at `params["*"]`; Rango exposes it as a
+named string at `ctx.params.path` with the `/` separators preserved (split to
+recover RR's array):
+
+```typescript
+path("/files/:path*", (ctx) => {
+  const parts = ctx.params.path === "" ? [] : ctx.params.path.split("/");
+  return <FileBrowser path={parts} />;
+}, { name: "files" });
+```
+
+### Layouts
+
+React Router layouts use `<Outlet />` — same concept in Rango:
+
+```typescript
+// React Router:
+function DashboardLayout() {
+  return (
+    <div className="dashboard">
+      <Outlet />
+    </div>
+  );
+}
+
+// route config:
+{ path: "dashboard", element: <DashboardLayout />, children: [...] }
+
+// Rango: same <Outlet />, from @rangojs/router/client
+import { Outlet } from "@rangojs/router/client";
+
+layout(<DashboardLayout />, () => [
+  path("/dashboard", DashboardIndex, { name: "dashboard" }),
+  path("/dashboard/settings", Settings, { name: "settings" }),
+])
+```
+
+### Dynamic layouts (with data)
+
+```typescript
+// React Router: useLoaderData() in layout component
+function DashboardLayout() {
+  const { user } = useLoaderData();
+  return <Shell user={user}><Outlet /></Shell>;
+}
+
+// Rango: handler function layout (server component)
+layout(async (ctx) => {
+  const user = ctx.get("user");
+  return (
+    <Shell user={user}>
+      <Outlet />
+    </Shell>
+  );
+}, () => [
+  path("/dashboard", DashboardIndex, { name: "dashboard" }),
+])
+```
+
+### Nested routes
+
+React Router's nested route tree maps directly to Rango's `layout()` nesting:
+
+```typescript
+// React Router:
+createBrowserRouter([{
+  path: "/",
+  element: <RootLayout />,
+  children: [
+    { path: "dashboard",
+      element: <DashboardLayout />,
+      children: [
+        { index: true, element: <DashboardIndex /> },
+        { path: "settings", element: <Settings /> },
+      ]
+    },
+  ]
+}])
+
+// Rango:
+urls(({ path, layout }) => [
+  layout(<RootLayout />, () => [
+    layout(<DashboardLayout />, () => [
+      path("/dashboard", DashboardIndex, { name: "dashboard" }),
+      path("/dashboard/settings", Settings, { name: "settings" }),
+    ]),
+  ]),
+])
+```
+
+### Route groups / pathless layouts
+
+React Router's pathless routes (layout routes without a path) are Rango's
+layouts without a URL prefix:
+
+```typescript
+// React Router: { element: <AuthLayout />, children: [...] }
+
+// Rango: layout with no URL segment
+layout(<AuthLayout />, () => [
+  path("/login", LoginPage, { name: "login" }),
+  path("/register", RegisterPage, { name: "register" }),
+])
+```
+
+### Index routes
+
+```typescript
+// React Router: { index: true, element: <Home /> }
+
+// Rango: path with "/" inside a layout
+layout(<RootLayout />, () => [
+  path("/", HomePage, { name: "home" }),
+])
+```

package/skills/mime-routes/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: mime-routes
-description: Content negotiation — serve different response types (RSC, JSON, text, XML) from the same URL based on Accept header
+description: Content negotiation — serve different response types (RSC, JSON, text, XML) from the same URL based on Accept header. Use when the same URL needs to return JSON for API clients and HTML/RSC for browsers, or branching a handler on the Accept header.
 argument-hint: [negotiate|vary|accept]
 ---
 
@@ -41,26 +41,33 @@ When an API client requests the same URL (`Accept: application/json`), the JSON
 1. **Q-value priority** — higher `q` wins (`Accept: application/json;q=0.9, text/html;q=1.0` serves RSC)
 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)
+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
 5. **All responses** on a negotiated URL get `Vary: Accept` header, including the RSC side
 
-RSC participates as a `text/html` candidate alongside response-type variants.
-There is no special short-circuit — RSC follows the same negotiation rules as other types.
+RSC participates as a candidate alongside response-type variants under two MIME
+types: `text/html` (the document — its canonical representation) and
+`text/x-component` (the RSC flight wire format). There is no special
+short-circuit — RSC follows the same negotiation rules as other types.
 
 The MIME mapping used for matching:
 
-| Tag                  | MIME type                                                    |
-| -------------------- | ------------------------------------------------------------ |
-| RSC (plain `path()`) | `text/html` (negotiation) / `text/x-component` (wire format) |
-| `json`               | `application/json`                                           |
-| `text`               | `text/plain`                                                 |
-| `xml`                | `application/xml`                                            |
-| `html`               | `text/html`                                                  |
-| `md`                 | `text/markdown`                                              |
-
-RSC routes negotiate as `text/html` but respond with `text/x-component` (the RSC wire format).
-The browser's RSC runtime decodes this transparently — clients requesting `text/html` get
-the RSC page rendered normally.
+| Tag                  | MIME type                              |
+| -------------------- | -------------------------------------- |
+| RSC (plain `path()`) | `text/html` **and** `text/x-component` |
+| `json`               | `application/json`                     |
+| `text`               | `text/plain`                           |
+| `xml`                | `application/xml`                      |
+| `html`               | `text/html`                            |
+| `md`                 | `text/markdown`                        |
+
+Which representation an RSC win renders is decided by the same Accept header:
+the flight wire format is **explicit opt-in only** (`Accept: text/x-component`,
+or the internal `_rsc_*`/`__rsc` transport params the client runtime sends).
+Everything else — browsers, `curl` (`*/*`), a missing Accept header, mismatched
+types like `application/json` on a URL with no JSON variant — gets the HTML
+document. A generic HTTP client never sees the wire format by accident, and an
+explicit `Accept: text/x-component` selects the RSC flight stream even on a
+route where a response variant is defined first.
 
 Tags `image`, `stream`, and `any` are pass-through and do not participate in Accept matching.
 
@@ -77,11 +84,12 @@ export const urlpatterns = urls(({ path }) => [
 ]);
 ```
 
-- `Accept: text/html` — RSC page
+- `Accept: text/html` — RSC page (HTML document)
 - `Accept: application/json` — JSON handler
 - `Accept: text/plain` — text handler
 - `Accept: application/xml` — XML handler
-- `Accept: */*` — first variant (JSON, since it was registered first)
+- `Accept: */*` — RSC page as HTML (the primary, since it was registered first)
+- `Accept: text/x-component` — RSC page as the flight wire format
 
 ## Wildcard Routes
 
@@ -108,6 +116,35 @@ path.text("/api/data", () => "plain text version", { name: "dataText" }),
 Without an RSC primary, there is no `text/html` candidate — the Accept header
 picks among the response-type candidates directly.
 
+## Type Safety For Negotiated Paths
+
+`router.named-routes.gen.ts` validates route names, params, search, `href()`, and
+the `Rango.Path` type, but it does not carry response payload metadata. For MIME or
+response payload types, use one of these surfaces:
+
+- `RouteResponse<typeof patterns, "routeName">` for a specific response variant
+  by route name. This is the clearest option when several MIME variants share
+  one URL pattern.
+- `Rango.PathResponse<"/products/:id">` (ambient, no import) for global lookup by URL pattern or concrete path after the app
+  registers `typeof router.routeMap`:
+
+```typescript
+// router.tsx
+export const router = createRouter({ document: Document }).routes(urlpatterns);
+
+type AppRoutes = typeof router.routeMap;
+
+declare global {
+  namespace Rango {
+    interface RegisteredRoutes extends AppRoutes {}
+  }
+}
+```
+
+`RegisteredRoutes` is what exposes the richer routeMap entries containing
+response payload metadata. Without it, URL-pattern response lookup has paths but
+no payloads, so response types resolve to `never`.
+
 ## How It Works
 
 1. **Build time**: `buildRouteTrie()` calls `mergeLeaves()` when multiple routes share a pattern.