@rangojs/router 0.16.0 → 0.18.0

package/skills/migrate-nextjs/SKILL.md

@@ -6,6 +6,13 @@ argument-hint: [path-to-nextjs-app]
 
 # Migrate from Next.js App Router to @rangojs/router
 
+This skill maps a Next.js App Router project onto Rango: project setup, the
+`app/` file conventions to the `urls()` DSL, data fetching and rendering modes
+(SSG, ISR, PPR), middleware, navigation, server actions, metadata, API routes,
+and theming. Use it when porting a Next.js app, or when a Next.js habit needs a
+Rango equivalent. For a side-by-side evaluation rather than a port, see
+`/comparison`; for React Router or Remix apps, see `/migrate-react-router`.
+
 ## Why Rango
 
 Common reasons to migrate:
@@ -33,8 +40,10 @@ Common reasons to migrate:
   build-time rendering instead of mixing rendering and caching behind conventions.
   See: `/prerender`
 - **Partial prerendering, shipped** — the `ppr` path option caches a page's
-  HTML shell and resumes only the live holes on each request; loaders stay
-  fresh. The equivalent of Next's `experimental_ppr`, stable and per-route.
+  HTML shell and resumes its holes per request: loaders without `ssr: false`,
+  read under `loading()` or an inline `<Suspense>`. Handler output bakes into
+  the shell. It maps to Next's `experimental_ppr`, stable and per-route, but
+  holes come from loaders, not from any `<Suspense>`.
   See: `/ppr`
 - **Composable route tree** — layouts, includes, middleware, parallels, and
   intercepts compose directly in the route definition.
@@ -86,6 +95,13 @@ its call site with the real Rango API:
 | `next/font`                                                                  | see `/fonts`                                                                                   |
 | `next/script` `Script`                                                       | see `/scripts`                                                                                 |
 | `next-themes`                                                                | `theme: true` in `createRouter` (see §10)                                                      |
+| `next/dynamic` `dynamic(() => import(...), { ssr: false })`                  | render it after mount in a `"use client"` component (see the note below)                       |
+
+`next/dynamic`'s `{ ssr: false }` keeps a component out of server rendering:
+render it only after mount in a `"use client"` component (a `useEffect` flag,
+with `React.lazy()` if its code should split out). Do not map it to
+`loader(L, { ssr: false })`, which does the opposite: the server settles that
+loader before the first flush, and under `ppr` it bakes into the shell.
 
 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.
@@ -99,10 +115,14 @@ Replace Next.js tooling with Vite + Rango:
 
 ```bash
 npm remove next @next/env
-npm install @rangojs/router @vitejs/plugin-react
+npm install @rangojs/router   # keep react and react-dom
 npm install -D vite
 ```
 
+`rango()` already 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 (see `/react-compiler`).
+
 ```typescript
 // vite.config.ts
 import { defineConfig } from "vite";
@@ -119,7 +139,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);
 ```
@@ -223,8 +243,8 @@ The `include()` name has three deliberate modes:
 | Form                                            | Child route names                                                       |
 | ----------------------------------------------- | ----------------------------------------------------------------------- |
 | `include("/", patterns)`                        | private to the included module; omitted from the app-wide generated map |
-| `include("/", patterns, { name: "marketing" })` | globally registered as `marketing.home`, `marketing.pricing`, ...       |
-| `include("/", patterns, { name: "" })`          | flattened into the parent map as `home`, `pricing`, ...                 |
+| `include("/", patterns, { name: "marketing" })` | globally registered as `marketing.landing`, `marketing.pricing`, ...    |
+| `include("/", patterns, { name: "" })`          | flattened into the parent map as `landing`, `pricing`, ...              |
 
 Use the empty-string form only when the child names are intentionally global
 and unique. Inside a private/namespaced module, prefer dot-local reversal or
@@ -300,17 +320,23 @@ run the Phase 0 audit before carrying those calls over unchanged.
 ```typescript
 // Next.js:
 async function ProductPage({ params }) {
-  const product = await fetch(`/api/products/${params.slug}`).then(r => r.json());
+  const product = await fetch(`https://api.example.com/products/${params.slug}`).then(r => r.json());
   return <div>{product.name}</div>;
 }
 
 // Rango: same pattern, params come from ctx
+import type { Handler } from "@rangojs/router";
+
 const ProductPage: Handler<"product"> = async (ctx) => {
-  const product = await fetch(`/api/products/${ctx.params.slug}`).then(r => r.json());
+  const product = await fetch(`https://api.example.com/products/${ctx.params.slug}`).then(r => r.json());
   return <div>{product.name}</div>;
 };
 ```
 
+If the Next page fetched its own `/api/...` route, call the underlying service
+function directly instead of making a request back to the same app (see
+[backend-host-swap.md](backend-host-swap.md#extract-shared-server-services)).
+
 ### When to use createLoader
 
 Loaders are Rango's live data layer. Use them when you need:
@@ -360,9 +386,11 @@ export const ProductDef = Prerender<{ slug: string }>(
 );
 
 // Rango (with live fallback — matches Next.js dynamicParams behavior):
-import { Prerender, Passthrough } from "@rangojs/router";
+import { Prerender, Passthrough, notFound } from "@rangojs/router";
 
-const ProductDef = Prerender<{ slug: string }>(
+// Keep the definition exported: the Vite plugin injects the stable id only
+// into `export const X = Prerender(...)` (or `const X = ...; export { X }`).
+export const ProductDef = Prerender<{ slug: string }>(
   async () => [{ slug: "a" }, { slug: "b" }],
   async (ctx) => {
     const product = await getProduct(ctx.params.slug);
@@ -373,8 +401,12 @@ const ProductDef = Prerender<{ slug: string }>(
 
 export const Product = Passthrough(ProductDef, async (ctx) => {
   const product = await getProduct(ctx.params.slug);
+  if (!product) notFound();
   return <ProductPage product={product} />;
 });
+
+// In urls:
+path("/products/:slug", Product, { name: "product" });
 ```
 
 Use `Passthrough()` whenever the Next.js route has `dynamicParams: true` (the
@@ -395,9 +427,12 @@ Next.js route segment config maps onto Rango's explicit primitives:
 ### Partial prerendering → the `ppr` path option
 
 Next.js PPR statically prerenders a shell at build time and streams the parts
-inside `<Suspense>` at request time. Rango ships the same model as a path
+inside `<Suspense>` at request time. Rango ships a similar model as a path
 option — the shell is captured at runtime into the app cache store and resumed
-on later requests, with the holes rendered fresh per request:
+on later requests, with the holes rendered fresh per request. The difference is
+what counts as a hole: in Rango everything a handler produces is shell
+material, as it is under `cache()`, including a promise it hands to a component
+under `<Suspense>`. A live hole is loader data:
 
 ```typescript
 // Next.js: app/products/[id]/page.tsx
@@ -412,11 +447,14 @@ export default async function Page({ params }) {
   );
 }
 
-// Rango, step 1 — direct carry-over. Your Suspense tree IS the hole model:
-// hand the un-awaited promise down, keep the boundary, add the ppr option.
-// No loader, no loading(), no restructuring.
+// Rango: the direct carry-over BAKES. Under ppr the capture awaits a promise
+// the handler hands down (bounded by ppr.captureTimeout), and every shell HIT
+// shows the captured price.
+import { Suspense } from "react";
+import type { HandlerContext } from "@rangojs/router";
+
 function ProductPage(ctx: HandlerContext) {
-  const price = fetchPrice(ctx.params.id); // pending promise — NOT awaited
+  const price = fetchPrice(ctx.params.id); // awaited at capture, then frozen
   return (
     <ProductShell>
       <Suspense fallback={<PriceSkeleton />}>
@@ -425,44 +463,54 @@ function ProductPage(ctx: HandlerContext) {
     </ProductShell>
   );
 }
-path("/products/:id", ProductPage, {
-  name: "product",
-  ppr: { ttl: 600, swr: 120 }, // or ppr: true (default ttl 300s)
-});
 
-// Rango, step 2 (optional refinement) — promote the fetch to a loader for a
-// GUARANTEED hole: loaders are masked at capture and fresh on every serve,
-// even when the value resolves instantly (a raw promise that settles fast
-// would bake into the shell). loading() is the loader's hole boundary.
+// Rango, live price: a loader without ssr: false, read with
+// useLoader(LivePriceLoader) in a client component. loading() (or an inline
+// <Suspense> around the reader) is the hole boundary (/ppr → The loader lane
+// rule).
+function ProductPageLive() {
+  return (
+    <ProductShell>
+      <LivePriceFromLoader /> {/* "use client": useLoader(LivePriceLoader) */}
+    </ProductShell>
+  );
+}
 path(
   "/products/:id",
-  ProductPage,
-  { name: "product", ppr: { ttl: 600, swr: 120 } },
+  ProductPageLive,
+  { name: "product", ppr: { ttl: 600, swr: 120 } }, // or ppr: true (ttl 300s)
   () => [loader(LivePriceLoader), loading(<PriceSkeleton />)],
 ),
 ```
 
 Differences that matter during migration:
 
-- **The Suspense/promise model carries over.** As in Next, a still-pending
-  promise handed to a component that suspends under its own `<Suspense>`
-  postpones at capture and becomes a hole — existing Next PPR trees keep
-  working as-is, no `loading()` required. One container rule everywhere
-  (handlers, handles, loaders): awaited/settled data bakes into the shell; a
-  promise nested inside your data stays a live hole. For loaders, `loading()`
-  selects the lane: present = guaranteed live (masked at capture, fresh every
-  serve, immune to fast resolution — prefer it for per-request data); absent =
-  the bake lane (the settled container bakes and is snapshot-pinned per shell,
-  nested promises stay live). Identity reads (`cookies()`/`headers()`) where
-  the value would bake refuse the capture by construction.
+- **Handler output bakes; loader data is the hole.** Unlike Next, a pending
+  promise the handler hands to a component under `<Suspense>` does NOT make a
+  hole. Everything a handler produces — that promise, an async server
+  component, a nested promise in a handle it pushes, a loader it awaits — is
+  awaited at capture (bounded by `ppr.captureTimeout`) and served frozen for
+  the shell's lifetime; a shell HIT never runs a handler. Keep the parts that
+  must be fresh in loaders without `ssr: false`, read with `useLoader` under
+  `loading()` or an inline `<Suspense>`; inside an `ssr: false` loader, return
+  them as nested promises. For loaders, `ssr: false` (not `loading()`) selects
+  the lane — see `/ppr` → The loader lane rule.
 - **Shell freshness is explicit.** Next's PPR shell is fixed until the next
   build; Rango's has `ttl`/`swr`/`tags` per route, and `updateTag()` /
   `revalidateTag()` drop the shell (`revalidate()` does not — it is a data
-  lever and never touches shell HTML).
-- **`cookies()`/`headers()` in shell material THROW during capture** (in Next
-  they silently force dynamic rendering). Per-user reads must move behind a
-  `loading()` boundary (the live loader lane) or into a nested promise — the
-  refusal surfaces at migration time, which is the point.
+  lever and never touches shell HTML). Under a route `cache()`, the shell
+  lives no longer than that entry: its ttl/swr are capped by the entry's (dev
+  warns when an explicit `ppr` window is reduced). A route `cache({ key })`
+  gives one shell per key value, and `cache(false)` or a false `condition()`
+  means no shell.
+- **Request-scoped reads in shell material refuse the capture** (in Next they
+  silently force dynamic rendering). `cookies()`, `headers()`, a
+  `{ cache: false }` variable, and `ctx.dynamic()` refuse it anywhere the
+  capture waits: a handler, a promise it passes or pushes, an async component,
+  a loader it awaits. Per-user reads must move into a live loader (no
+  `ssr: false`; a nested promise does not help). A normal `ctx.get()` value is
+  not guarded and bakes as the capturing request's value. The refusal surfaces
+  at migration time, which is the point.
 - **A store is required.** PPR needs the app-level `createRouter({ cache })`
   store to implement the shell family (`MemorySegmentCacheStore`,
   `CFCacheStore`, `VercelCacheStore`). Without one the route quietly stays
@@ -483,20 +531,27 @@ tag-based cache invalidation now maps directly.
 with `cache({ tags })` or runtime `cacheTag(...tags)`. `cacheTag()` works inside a
 `"use cache"` function (tags that entry) AND render-callable in a plain server
 component (no `"use cache"` needed — it tags the document / PPR shell the component
-renders into). Then invalidate by tag:
+renders into, and the route `cache()` entry it renders inside). Then invalidate by tag:
 
 ```typescript
 // Next.js                    Rango
 // revalidateTag("products")  →  await updateTag("products")  // in a server action: awaitable,
 //                                                            // read-your-own-writes (next render is fresh)
 //                            or  revalidateTag("products")    // in a route handler / webhook:
-//                                                            // background, non-blocking (hard-purge)
+//                                                            // background, non-blocking (evicts)
 ```
 
 `updateTag` is awaitable and immediate; `revalidateTag` is fire-and-forget. Both
-hard-purge (the next read re-renders fresh); the only difference is awaitability —
-despite the Next.js name, `revalidateTag` here is NOT stale-while-revalidate.
-Built-in stores (`MemorySegmentCacheStore`, `CFCacheStore`) index by tag. Next's
+evict (despite the Next.js name, `revalidateTag` here is NOT
+stale-while-revalidate), and the request that calls either reads its own
+writes. `updateTag()` also waits for the durable write and rejects when it
+fails; `revalidateTag()` runs it in the background. The mutating user's next
+requests skip the stores' per-isolate PPR shell memos via the fresh-reads
+cookie (`rango-state-fresh`); other users, and other locations on
+`CFCacheStore`, see the invalidation once the memo refreshes and KV
+propagates (`/caching` → "The fresh-reads cookie").
+Built-in stores (`MemorySegmentCacheStore`, `CFCacheStore`, `VercelCacheStore`)
+index by tag. Next's
 `revalidatePath` has no path-based equivalent — tag the relevant entries instead.
 
 **2. Partial-render selection (which segments re-run after an action).** This is
@@ -507,7 +562,8 @@ re-rendering:
 ```typescript
 import { updateBlog } from "./actions/blog";
 
-// Re-run this layout when a blog action fires
+// Re-run this layout when a blog action fires (layouts above the route are
+// skipped after actions by default; undefined defers otherwise)
 layout(BlogLayout, () => [
   revalidate((ctx) => ctx.isAction(updateBlog) || undefined),
   path("/blog/:slug", BlogPost, { name: "blogPost" }),
@@ -617,12 +673,14 @@ path("/dashboard", DashboardPage, { name: "dashboard" }, () => [
 "use client";
 export default function Error({ error, reset }) { ... }
 
-// Rango: errorBoundary wrapping a group of routes
+// Rango: errorBoundary wrapping a group of routes. The fallback renders on the
+// server and receives only `error` — there is no `reset` (a server render
+// cannot be retried in place; the user navigates away or reloads).
 layout(<DashboardLayout />, () => [
-  errorBoundary(({ error, reset }) => (
+  errorBoundary(({ error }) => (
     <div>
       <h2>Something went wrong</h2>
-      <button onClick={reset}>Try again</button>
+      <p>{error.message}</p>
     </div>
   )),
   path("/dashboard", DashboardIndex, { name: "dashboard" }),
@@ -630,6 +688,30 @@ layout(<DashboardLayout />, () => [
 ])
 ```
 
+For client-side render errors with a "Try again" button (Next's `reset`), wrap
+the client subtree in `ErrorBoundary` from `@rangojs/router/client`; its
+function fallback receives `{ error, reset }`:
+
+```tsx
+"use client";
+import { ErrorBoundary } from "@rangojs/router/client";
+
+export function ChartPanel() {
+  return (
+    <ErrorBoundary
+      fallback={({ error, reset }) => (
+        <div>
+          <p>{error.message}</p>
+          <button onClick={reset}>Try again</button>
+        </div>
+      )}
+    >
+      <Chart />
+    </ErrorBoundary>
+  );
+}
+```
+
 ```typescript
 // Next.js: app/not-found.tsx
 export default function NotFound() { ... }
@@ -657,15 +739,17 @@ children in their scope — handlers, loaders, and nested segments.
 
 ## 6. Navigation
 
-| Next.js                         | Rango                                                                                                                                                                                                   |
-| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `import Link from "next/link"`  | `import { Link } from "@rangojs/router/client"`                                                                                                                                                         |
-| `<Link href="/about">`          | `<Link to="/about">`                                                                                                                                                                                    |
-| `useRouter().push("/about")`    | `useRouter().push("/about")`                                                                                                                                                                            |
-| `useRouter().replace("/about")` | `useRouter().replace("/about")`                                                                                                                                                                         |
-| `usePathname()`                 | `usePathname()` from `@rangojs/router/client`                                                                                                                                                           |
-| `useSearchParams()`             | `useSearchParams()` from `@rangojs/router/client` — returns an RR-style TUPLE, so destructure the reader: `const [searchParams] = useSearchParams()`; the second element is a setter Next does not have |
-| `redirect("/login")` (server)   | `redirect("/login")` from `@rangojs/router`                                                                                                                                                             |
+| Next.js                                              | Rango                                                                                                                                                                                                   |
+| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `import Link from "next/link"`                       | `import { Link } from "@rangojs/router/client"`                                                                                                                                                         |
+| `<Link href="/about">`                               | `<Link to="/about">`                                                                                                                                                                                    |
+| `useRouter().push("/about")`                         | `useRouter().push("/about")`                                                                                                                                                                            |
+| `useRouter().replace("/about")`                      | `useRouter().replace("/about")`                                                                                                                                                                         |
+| `useRouter().back()` / `refresh()` / `prefetch(url)` | same methods on `useRouter()` from `@rangojs/router/client`                                                                                                                                             |
+| `useParams()`                                        | `useParams()` from `@rangojs/router/client` (or `ctx.params` in a server handler)                                                                                                                       |
+| `usePathname()`                                      | `usePathname()` from `@rangojs/router/client`                                                                                                                                                           |
+| `useSearchParams()`                                  | `useSearchParams()` from `@rangojs/router/client` — returns an RR-style TUPLE, so destructure the reader: `const [searchParams] = useSearchParams()`; the second element is a setter Next does not have |
+| `redirect("/login")` (server)                        | `redirect("/login")` from `@rangojs/router`                                                                                                                                                             |
 
 ### "Instant navigations" (Link prefetching)
 
@@ -699,22 +783,22 @@ has. Server-component routes and `clientUrls()` groups compose in one tree.
 
 ## 7. Server Actions
 
-Server actions work the same way — `"use server"` directive, `useActionState`, form actions. No migration needed for action logic.
+Server actions work the same way — `"use server"` directive, `useActionState`, form actions. No migration needed for action logic. Keep passing the imported action itself to `<form action={...}>` or `useActionState(action, initial)` (not a client-side closure around it) so the form still submits with JavaScript disabled.
 
 Key difference: in Rango, route middleware does NOT wrap action execution. Actions only see global middleware context. Use `getRequestContext()` in actions to access `ctx.set()`/`ctx.get()`.
 
-Next.js's `revalidateTag()` maps directly: tag entries via `cache({ tags })` / `cacheTag(...)`, then invalidate. **In a server action use `await updateTag(tag)`** — it is read-your-own-writes, so the action's own re-render sees fresh data; `revalidateTag(tag)` is a background (non-blocking) hard-purge and is NOT read-your-own-writes, so reserve it for route handlers / webhooks (calling it from an action can leave that action's re-render stale). `revalidatePath()` has no path-based equivalent — tag the route's entries instead. Separately, to force specific matched segments (path/layout/parallel/intercept) and their loaders to re-render after an action, attach a `revalidate(({ actionId }) => ...)` rule to that segment or loader registration. See `/server-actions` for the full pattern (validation, error handling, file uploads), `/caching` for tag invalidation, and `/loader` for revalidation rule semantics.
+Next.js's `revalidateTag()` maps directly: tag entries via `cache({ tags })` / `cacheTag(...)`, then invalidate. **In a server action use `await updateTag(tag)`** — it is read-your-own-writes, so the action's own re-render sees fresh data, and it rejects when the store's durable write fails; `revalidateTag(tag)` is a background (non-blocking) hard-purge for route handlers / webhooks. The request that calls `revalidateTag()` also reads its own writes, but a failed durable write only reaches `onError`. `revalidatePath()` has no path-based equivalent — tag the route's entries instead. Separately, the route, the segments inside its `path()`, and all loaders already re-run after every action; layouts and parallels above the route are skipped. To re-render one of those skipped segments after an action, attach `revalidate((ctx) => ctx.isAction(updateBlog) || undefined)` to it; to narrow a loader or route segment to one action, use `revalidate((ctx) => (ctx.isAction() ? ctx.isAction(updateBlog) : undefined))` (match the imported action by reference, as in §3). See `/server-actions` for the full pattern (validation, error handling, file uploads), `/caching` for tag invalidation, and `/loader` for revalidation rule semantics.
 
 ## 8. Metadata / Head
 
-Rango uses the `Meta` handle + `<MetaTags />` client component:
+Rango uses the `Meta` handle + `<Html.Meta />` client component:
 
 ```typescript
 // Next.js: export const metadata = { title: "Home" }
 // Next.js: export function generateMetadata({ params }) { ... }
 
-// Rango: Meta handle in handlers (server), MetaTags in document <head> (client)
-import { Meta } from "@rangojs/router";
+// Rango: Meta handle in handlers (server), Html.Meta in document <head> (client)
+import { Meta, type Handler } from "@rangojs/router";
 
 const HomePage: Handler<"home"> = (ctx) => {
   const meta = ctx.use(Meta);
@@ -751,16 +835,16 @@ Without the flag the push still applies, but a slow loader's title lands
 post-hydration instead of in the document — see `/loader` → "Writing Handles
 from Loaders" for the delivery race.
 
-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>
@@ -835,13 +919,15 @@ See `/theme` for full API including system detection and cookie persistence.
 4. [ ] Create `router.tsx` with `createRouter()`
 5. [ ] Convert file-based routes to `urls()` DSL in `urls.tsx`
 6. [ ] Migrate layouts to `layout()` with `<Outlet />`
-7. [ ] Convert data fetching to `createLoader()` + `ctx.use()`
+7. [ ] Keep inline server `fetch`/DB calls in handlers; add `createLoader()` +
+       `loader()` only where you need live, refreshable, or independently
+       cached data (§3)
 8. [ ] Migrate `middleware.ts` to `router.use()` (auth, guards, logging)
 9. [ ] Replace `next/link` with `Link` from `@rangojs/router/client`; keep
        "instant navigations" via `prefetch="viewport"`/`defaultPrefetch` (§6)
 10. [ ] Convert loading/error files to `loading()` / `errorBoundary()`
 11. [ ] Migrate API routes to `path.json()` / `path.text()`
-12. [ ] Update metadata to use `Meta` handle + `<MetaTags />` in document head
+12. [ ] Update metadata to use `Meta` handle + `<Html.Meta />` in document head
         (`generateMetadata` → loader push + `{ ssr: false }`)
 13. [ ] Replace `next-themes` with `theme: true` in createRouter (see `/theme`)
 14. [ ] Map rendering-mode segment config: `revalidate = N` → `cache({ ttl })`,

package/skills/migrate-nextjs/backend-host-swap.md

@@ -55,7 +55,9 @@ actor and tenant scope at the repository boundary, verify membership/role, and
 perform the data query through that scope. Avoid exporting an unrestricted DB
 handle to page handlers.
 
-Tests must prove denial, not only success:
+Tests must prove denial, not only success (the `/testing` skill's `runMiddleware`,
+`runLoader`, and `runInRequestContext` take your DB double through `env`; see its
+`bindings.md`):
 
 - a user cannot read another tenant by guessing an ID;
 - a member cannot perform an owner/admin mutation;
@@ -102,7 +104,8 @@ For a Node-to-Workers move, search for:
 
 Prefer web standards (`fetch`, `Request`, `Response`, WebCrypto) and provider
 bindings. Test the production bundle in `vite preview`; a successful TypeScript
-check does not prove an SDK runs in workerd.
+check does not prove an SDK runs in workerd. `/cloudflare` covers bindings,
+local D1, streaming, and deploying the built Worker.
 
 ## Plan cutover and rollback
 

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
 
@@ -28,7 +33,8 @@ Common reasons to migrate:
   See: `/middleware`, `/loader`
 - **Live data layer** — `createLoader()` and `loader()` keep data fresh
   independently of cached UI. A route can serve cached segments while loaders
-  still resolve live on every request.
+  still resolve live on every request (on a `ppr` route, a loader registered
+  with `ssr: false` bakes into the cached HTML shell instead; see `/ppr`).
   See: `/loader`, `/caching`, `/cache-guide`
 - **Explicit caching model** — `cache()` DSL, `revalidate()`, `use cache`, and
   custom cache stores make data and render caching a first-class part of the router.
@@ -109,19 +115,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 +148,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).