@rangojs/router 0.0.0-experimental.f2d1a2f1 → 0.0.0-experimental.f4a8e8de

package/skills/middleware/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: middleware
-description: Define middleware for authentication, logging, and request processing in @rangojs/router
+description: Define middleware for authentication, logging, and request processing in @rangojs/router. Use when gating routes behind auth checks, logging requests, or running shared logic before a handler runs.
 argument-hint: [middleware-name]
 ---
 
@@ -10,9 +10,6 @@ Middleware runs before/after route handlers using the onion model.
 
 ## Execution Model
 
-Canonical semantics reference:
-[docs/execution-model.md](../../docs/internal/execution-model.md)
-
 There are two levels of middleware with different execution scopes:
 
 ### Global middleware (`router.use()`)
@@ -32,17 +29,26 @@ When the router has a `basename`, pattern-scoped `.use()` patterns are automatic
 
 Registered inside `urls()` callback. Wraps **rendering only** -- it does NOT wrap server action execution. Actions run before route middleware, so when route middleware executes during post-action revalidation, it can observe state that the action set (cookies, context variables, headers).
 
+> **Implication for auth:** route middleware cannot guard server actions. Use `router.use("/admin/*", requireAuth)` (global, scoped) for action protection, or check inside the action body. See `/server-actions` for action-side auth patterns.
+
 ```
 Request flow (with action):
-  global mw -> action executes -> route mw -> layout -> handler -> loaders
+  global mw -> action executes -> route mw -> render pass
 
 Request flow (no action):
-  global mw -> route mw -> layout -> handler -> loaders
+  global mw -> route mw -> render pass
 
 Progressive enhancement (no-JS form POST):
   global mw -> action executes -> route mw -> full page re-render
 ```
 
+The **render pass** resolves handler, layouts, parallels, and loaders together —
+it is not a handler-then-loaders sequence. Handler-first ordering is guaranteed
+only between a route handler and its child/orphan layouts and parallels (so
+`ctx.set` is visible); loaders run **concurrently** and stream their results, so
+their latency overlaps rendering rather than blocking it. See `/loader` →
+"Parallel and streaming".
+
 The contract is: **route middleware wraps rendering regardless of transport** (JS-enabled RSC stream or no-JS HTML). During PE re-render, route middleware observes action-set state (cookies, context variables) the same way it does during JS-enabled post-action revalidation.
 
 Revalidation is still partial. Route middleware wraps the render pass that
@@ -54,15 +60,21 @@ data itself.
 ### Revalidation Contracts with Middleware-Backed Trees
 
 Middleware can establish request-level context (`ctx.set`) for segments that
-execute in the current render pass. It does not change partial revalidation
-boundaries between handler/layout/parallel segments.
+execute in the current render pass. Because route middleware wraps **every**
+render pass — normal renders, post-action revalidation, PE re-renders — its
+variables are never stale: middleware is the safest `ctx.set` rung on the
+data-passing ladder (`/rango` → "Passing data down the tree"). But it does
+not change partial revalidation boundaries between handler/layout/parallel
+segments.
 
 For shared segment data, use named revalidation contracts on both the producer
 and consumer segments, even when middleware is present in the chain.
 
 ```typescript
-export const revalidateCartData = ({ actionId }) =>
-  actionId?.includes("src/actions/cart.ts#") ?? false;
+import * as CartActions from "./actions/cart";
+
+export const revalidateCartData = (ctx) =>
+  ctx.isAction(CartActions) || undefined;
 
 layout(CartLayout, () => [
   middleware(cartRenderMiddleware),
@@ -185,14 +197,18 @@ export const myMiddleware: Middleware = async (ctx, next) => {
   ctx.request; // Request object
   ctx.url; // Parsed URL
   ctx.params; // Route parameters
+  ctx.build; // in middleware: true only during Prerender + ppr build-shell capture (plain Prerender does not run middleware)
 
   // Access platform bindings (plain bindings from createRouter<TEnv>())
   ctx.env.DB; // D1Database
   ctx.env.KV; // KVNamespace
 
-  // Set variables for downstream handlers (typed via RSCRouter.Vars)
+  // Set variables for downstream handlers (typed via Rango.Vars)
   ctx.set("user", { id: "123", name: "John" });
 
+  // Opt the current request out of PPR shell lookup/capture.
+  ctx.dynamic();
+
   // Continue to next middleware/handler
   await next();
 
@@ -231,8 +247,37 @@ const Dashboard: Handler<"dashboard"> = (ctx) => {
 ```
 
 This works alongside `ctx.get("key")` / `ctx.set("key", value)` (global typing
-via RSCRouter.Vars augmentation). Use `createVar` for route-local or feature-scoped
-data; use RSCRouter.Vars for app-wide middleware state.
+via Rango.Vars augmentation). Use `createVar` for route-local or feature-scoped
+data; use Rango.Vars for app-wide middleware state.
+
+## Build-Time PPR Middleware
+
+Normal `Prerender` Flight payload collection does not run middleware: there is
+no request to wrap. The exception is `Prerender` + `ppr` build-shell capture.
+After the Flight payload exists, the shell producer replays global and route
+middleware for each generated URL before it captures HTML.
+
+In that build-shell pass:
+
+- `ctx.build === true`;
+- `ctx.waitUntil()` is inert;
+- `ctx.dynamic()` skips the baked shell for that URL;
+- context variables set by middleware are visible to the shell render.
+
+Use this to keep side effects predictable:
+
+```typescript
+export const commerceMiddleware: Middleware = async (ctx, next) => {
+  if (ctx.build) {
+    ctx.dynamic(); // leave this shell to runtime PPR
+    return next();
+  }
+
+  const session = await commerce.auth(ctx.request);
+  ctx.set("session", session);
+  return next();
+};
+```
 
 ## Redirect with State in Middleware
 

package/skills/migrate-nextjs/SKILL.md

@@ -32,6 +32,10 @@ Common reasons to migrate:
 - **Build-time rendering** — `Static()` and `Prerender()` provide explicit
   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.
+  See: `/ppr`
 - **Composable route tree** — layouts, includes, middleware, parallels, and
   intercepts compose directly in the route definition.
   See: `/composability`, `/parallel`, `/intercept`
@@ -43,6 +47,52 @@ Common reasons to migrate:
 
 Work route-by-route, bottom-up. Start with leaf pages, then layouts, then middleware. Verify each route works before moving to the next.
 
+### Phase 0: choose the migration boundary
+
+Before changing routes, classify the project. This decides whether existing
+database/auth code can actually carry over:
+
+| Migration           | What stays                                               | Additional work                                                        |
+| ------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------- |
+| Framework only      | runtime, database, auth provider                         | Next-to-Rango surface mapping in this skill                            |
+| Host/runtime swap   | database and auth, but Node becomes Workers/another host | SDK/runtime compatibility, bindings, secrets, filesystem/crypto checks |
+| Datastore/auth swap | host may stay, database or identity provider changes     | schema/data migration, authorization replacement, session cutover      |
+| Both                | only the product behavior stays                          | all of the above, with staged parity and rollback                      |
+
+For Cloudflare Workers, read `/cloudflare` before scaffolding. For a host,
+datastore, or auth swap, also read
+[backend-host-swap.md](backend-host-swap.md). Do not treat RLS policies,
+database functions, provider callbacks, or secret management as incidental
+route work.
+
+## Replace imports, never shim Next
+
+Do NOT create mock `next/*` modules, Vite aliases for `next/*`, or compatibility
+wrapper components (a local `Link` that forwards `href` to `to`, a fake
+`useRouter`, a stubbed `next/headers`). Shims freeze Next semantics into the
+app, hide unsupported behavior until runtime, and keep `next` in the dependency
+graph — the migration looks done but isn't. Replace every `next/*` import at
+its call site with the real Rango API:
+
+| Next import                                                                  | Replace with                                                                                   |
+| ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| `next/link` `Link`                                                           | `Link` from `@rangojs/router/client` — rename `href` to `to` (see §6)                          |
+| `next/navigation` `useRouter`, `usePathname`, `useSearchParams`, `useParams` | same names from `@rangojs/router/client`                                                       |
+| `next/navigation` `redirect`, `notFound`                                     | `redirect`, `notFound` from `@rangojs/router`                                                  |
+| `next/headers` `cookies`, `headers`                                          | `cookies()`, `headers()` from `@rangojs/router` (server-only)                                  |
+| `next/cache` `revalidateTag`, `unstable_cache`                               | `updateTag`/`revalidateTag` from `@rangojs/router`; `"use cache"` (see §3 and `/use-cache`)    |
+| `next/server` `NextResponse`, `NextRequest`                                  | web-standard `Response`/`Request`; middleware via `router.use()` (see §4)                      |
+| `next/image` `Image`                                                         | plain `<img>` (keep explicit `width`/`height`) or your CDN's image URL — no built-in optimizer |
+| `next/font`                                                                  | see `/fonts`                                                                                   |
+| `next/script` `Script`                                                       | see `/scripts`                                                                                 |
+| `next-themes`                                                                | `theme: true` in `createRouter` (see §10)                                                      |
+
+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.
+
+Done means: `grep -rn "from ['\"]next" src/ app/` returns nothing, and `next`
+is gone from `package.json`.
+
 ## 1. Project Setup
 
 Replace Next.js tooling with Vite + Rango:
@@ -88,6 +138,21 @@ The Document component replaces `app/layout.tsx`'s `<html>` wrapper. See `/route
 | `app/shop/[...path]/page.tsx`   | `path("/shop/:path+", CatchAll, { name: "shopCatchAll" })` |
 | `app/docs/[[...slug]]/page.tsx` | `path("/docs/:slug*", Docs, { name: "docs" })`             |
 
+The catch-all remainder is a single string at `ctx.params.<name>` with the `/`
+separators preserved — split it to recover the array Next gives you:
+
+```typescript
+// app/docs/[[...slug]]/page.tsx  ->  params.slug is string[] | undefined in Next
+path("/docs/:slug*", (ctx) => {
+  // "" for /docs, "a/b/c" for /docs/a/b/c
+  const slug = ctx.params.slug === "" ? [] : ctx.params.slug.split("/");
+  return <Docs slug={slug} />;
+}, { name: "docs" });
+```
+
+`[...path]` (required, ≥1 segment) maps to `:path+`; `[[...slug]]` (optional,
+matches the bare parent too) maps to `:slug*` — which binds `""` at `/docs`.
+
 ### Layouts
 
 ```typescript
@@ -153,6 +218,30 @@ export const marketingPatterns = urls(({ path }) => [
 include("/", marketingPatterns, { name: "marketing" }),
 ```
 
+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`, ...                 |
+
+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
+`scopedReverse()` rather than flattening solely for convenience.
+
+Next.js code-splits each route segment automatically. Rango's eager `include()`
+bundles the group into the entry chunk; to get Next-style per-section splitting,
+pass an async provider so the group loads on the first request under its prefix:
+
+```typescript
+// urls/admin.tsx: `export default adminPatterns` — loads on first /admin request
+include("/admin", () => import("./urls/admin"), { name: "admin" }),
+```
+
+Route types, `href()`, and prerender still see every route in the split group.
+See `/composability`.
+
 ### Parallel routes
 
 In Next.js, `@sidebar` and `@main` are both named slots. In Rango, the main content
@@ -193,9 +282,9 @@ The main content always goes through `<Outlet />` via the `path()` handler.
 // Rango: explicit intercept in layout
 layout(<ShopLayout />, () => [
   path("/product/:id", ProductPage, { name: "product" }),
-  intercept("@modal", ".product", <ProductModal />, () => [
-    when(({ from }) => from.pathname.startsWith("/shop")),
-  ]),
+  intercept("@modal", ".product", <ProductModal />, {
+    when: ({ from }) => from.pathname.startsWith("/shop"),
+  }),
 ])
 ```
 
@@ -203,7 +292,10 @@ layout(<ShopLayout />, () => [
 
 ### Server component data fetching
 
-Inline `fetch()` or direct DB calls in server components work as-is — no migration needed:
+Inline `fetch()` or direct DB calls in server components keep the same Rango
+shape when the target runtime, database, driver, and authentication model remain
+compatible. A Node-to-Workers or Postgres-to-D1 move is a separate migration;
+run the Phase 0 audit before carrying those calls over unchanged.
 
 ```typescript
 // Next.js:
@@ -225,7 +317,7 @@ Loaders are Rango's live data layer. Use them when you need:
 
 - **Client-side data refresh** — `useLoader()` in client components for reactive data
 - **Per-loader caching** — opt in with `loader(MyLoader, () => [cache({ ttl: 60 })])`; loaders stay live by default
-- **Revalidation control** — `revalidate()` targets specific loaders after actions
+- **Revalidation control** — `revalidate()` targets specific segments and loaders after actions
 - **Loading skeletons** — `loading()` shows a Suspense fallback while loaders resolve
 
 ```typescript
@@ -288,21 +380,136 @@ export const Product = Passthrough(ProductDef, async (ctx) => {
 Use `Passthrough()` whenever the Next.js route has `dynamicParams: true` (the
 default) or serves an open-ended param space. See `/prerender` for full API.
 
-### Revalidation: different model
+### Rendering-mode segment config
+
+Next.js route segment config maps onto Rango's explicit primitives:
+
+| Next.js segment config                              | Rango                                                        |
+| --------------------------------------------------- | ------------------------------------------------------------ |
+| `dynamic = "force-static"` + `generateStaticParams` | `Static()` / `Prerender()` (see `/prerender`)                |
+| `revalidate = 60` (ISR)                             | `cache({ ttl: 60, swr: ... })` on the route (see `/caching`) |
+| `dynamic = "force-dynamic"`                         | the default — routes are dynamic unless you cache them       |
+| `dynamicParams = true`                              | `Passthrough()` (above)                                      |
+| `experimental_ppr = true`                           | the `ppr` path option (below, and `/ppr`)                    |
+
+### 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
+option — the shell is captured at runtime into the app cache store and resumed
+on later requests, with the holes rendered fresh per request:
+
+```typescript
+// Next.js: app/products/[id]/page.tsx
+export const experimental_ppr = true;
+export default async function Page({ params }) {
+  return (
+    <ProductShell>
+      <Suspense fallback={<PriceSkeleton />}>
+        <LivePrice id={params.id} />
+      </Suspense>
+    </ProductShell>
+  );
+}
 
-Next.js uses path/tag-based cache invalidation (`revalidatePath`, `revalidateTag`)
-to bust cached responses. Rango does not currently have a direct equivalent.
+// 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.
+function ProductPage(ctx: HandlerContext) {
+  const price = fetchPrice(ctx.params.id); // pending promise — NOT awaited
+  return (
+    <ProductShell>
+      <Suspense fallback={<PriceSkeleton />}>
+        <LivePrice price={price} /> {/* use(price) inside */}
+      </Suspense>
+    </ProductShell>
+  );
+}
+path("/products/:id", ProductPage, {
+  name: "product",
+  ppr: { ttl: 600, swr: 120 }, // or ppr: true (default ttl 300s)
+});
 
-In Rango, separate these two concepts:
+// 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.
+path(
+  "/products/:id",
+  ProductPage,
+  { name: "product", ppr: { ttl: 600, swr: 120 } },
+  () => [loader(LivePriceLoader), loading(<PriceSkeleton />)],
+),
+```
 
-**Partial rendering revalidation** — `revalidate()` controls which segments
-(layouts, paths, loaders, parallels) should re-run during partial action
-re-rendering. This is about the segment tree, not cache invalidation:
+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.
+- **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.
+- **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
+  fully dynamic with a once-per-key warning.
+- **Middleware still guards every serve.** Auth middleware (global or route
+  DSL) runs before any shell byte on HIT and MISS alike — no Next-style "PPR
+  bypasses middleware" caveats to migrate around.
+
+A route without `ppr` pays zero cost. See `/ppr` for the full execution matrix,
+hole rules, and pitfalls.
+
+### Revalidation: two distinct axes
+
+Next.js conflates two things under "revalidation." Rango separates them — and
+tag-based cache invalidation now maps directly.
+
+**1. Cache invalidation (bust cached values) — direct equivalent.** Tag entries
+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:
 
 ```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)
+```
+
+`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
+`revalidatePath` has no path-based equivalent — tag the relevant entries instead.
+
+**2. Partial-render selection (which segments re-run after an action).** This is
+NOT cache invalidation — it is `revalidate()`, controlling which segments
+(layouts, paths, loaders, parallels) recompute during partial action
+re-rendering:
+
+```typescript
+import { updateBlog } from "./actions/blog";
+
 // Re-run this layout when a blog action fires
 layout(BlogLayout, () => [
-  revalidate(({ actionId }) => actionId?.includes("updateBlog") ?? false),
+  revalidate((ctx) => ctx.isAction(updateBlog) || undefined),
   path("/blog/:slug", BlogPost, { name: "blogPost" }),
 ]);
 
@@ -323,15 +530,18 @@ cache({ ttl: 60, swr: 300 }, () => [
 ]);
 ```
 
-The key shift is:
+The two axes compose: `updateTag()` / `revalidateTag()` bust cached values;
+`revalidate()` selects which segments re-render and stream to the client after an
+action.
 
-- Next.js asks "which cached path or tag should I invalidate?"
-- Rango asks "which segments should re-run after this action?"
+When migrating:
 
-When migrating `revalidatePath()` / `revalidateTag()` usage, the Rango version
-usually is not a 1:1 API replacement. Instead, decide which layouts, routes,
-loaders, or parallels should recompute after an action and declare
-`revalidate()` at those segment boundaries.
+- `revalidateTag(tag)` → `await updateTag(tag)` (in a server action) or
+  `revalidateTag(tag)` (in a route handler / webhook). Effectively 1:1.
+- `revalidatePath(path)` → no path-based equivalent; tag the entries on that
+  route (`cache({ tags })` / `cacheTag(...)`) and invalidate by tag.
+- To also force specific segments to re-render after the action (independent of
+  cache busting), attach a `revalidate()` rule at those segment boundaries.
 
 ## 4. Middleware
 
@@ -463,6 +673,8 @@ Server actions work the same way — `"use server"` directive, `useActionState`,
 
 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.
+
 ## 8. Metadata / Head
 
 Rango uses the `Meta` handle + `<MetaTags />` client component:
@@ -516,6 +728,21 @@ path.json("/api/users", async (ctx) => {
 path.text("/api/health", () => "ok", { name: "apiHealth" })
 ```
 
+Response routes treat returned responses as control-flow responses. A thrown
+`RouterError` becomes a structured API error. Do not assume every Next
+`NextResponse`/throw pattern maps identically:
+
+| In a response route             | Use                                                                  |
+| ------------------------------- | -------------------------------------------------------------------- |
+| custom status/body/headers      | `return new Response(...)`                                           |
+| structured thrown API error     | `throw new RouterError(...)`                                         |
+| intentional off-origin redirect | validate the target, then `return redirect(url, { external: true })` |
+
+Rango guards every browser-followed cross-origin `Location`. A raw unbranded
+cross-origin 3xx is rewritten to the app root; `{ external: true }` is the
+explicit, auditable opt-out for OAuth/SSO/payment callbacks. Never set it on an
+unvalidated user-provided URL.
+
 See `/response-routes` for full API.
 
 ## 10. Theme / Dark Mode
@@ -545,16 +772,23 @@ See `/theme` for full API including system detection and cookie persistence.
 
 ## Migration Checklist
 
-1. [ ] Set up Vite config with `rango()` plugin
-2. [ ] Create Document component (replaces root `<html>` layout)
-3. [ ] Create `router.tsx` with `createRouter()`
-4. [ ] Convert file-based routes to `urls()` DSL in `urls.tsx`
-5. [ ] Migrate layouts to `layout()` with `<Outlet />`
-6. [ ] Convert data fetching to `createLoader()` + `ctx.use()`
-7. [ ] Migrate `middleware.ts` to `router.use()` (auth, guards, logging)
-8. [ ] Replace `next/link` with `Link` from `@rangojs/router/client`
-9. [ ] Convert loading/error files to `loading()` / `errorBoundary()`
-10. [ ] Migrate API routes to `path.json()` / `path.text()`
-11. [ ] Update metadata to use `Meta` handle + `<MetaTags />` in document head
-12. [ ] Replace `next-themes` with `theme: true` in createRouter (see `/theme`)
-13. [ ] Run `npx rango generate src/` to generate route types
+1. [ ] Classify the migration boundary (framework, host/runtime, datastore/auth, or both)
+2. [ ] Set up Vite config with `rango()` plugin (and read `/cloudflare` for Workers)
+3. [ ] Create Document component (replaces root `<html>` layout)
+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()`
+8. [ ] Migrate `middleware.ts` to `router.use()` (auth, guards, logging)
+9. [ ] Replace `next/link` with `Link` from `@rangojs/router/client`
+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
+13. [ ] Replace `next-themes` with `theme: true` in createRouter (see `/theme`)
+14. [ ] Map rendering-mode segment config: `revalidate = N` → `cache({ ttl })`,
+        `force-static` → `Static()`/`Prerender()`, `experimental_ppr` → the
+        `ppr` path option (loader + `loading()` as the hole)
+15. [ ] Run `npx rango generate src/` to generate route types
+16. [ ] Verify no shims: `grep -rn "from ['\"]next" src/ app/` returns nothing,
+        no mock `next/*` modules or aliases exist, and `next` is out of
+        `package.json`

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

@@ -0,0 +1,120 @@
+# Backend and host swap audit
+
+Use this audit when the Next-to-Rango migration also changes runtime, database,
+or authentication provider. Route parity is not backend parity.
+
+## Contents
+
+- [Choose ownership](#choose-ownership)
+- [Inventory database guarantees](#inventory-database-guarantees)
+- [Replace authorization deliberately](#replace-authorization-deliberately)
+- [Extract shared server services](#extract-shared-server-services)
+- [Keep mutation side effects caller-owned](#keep-mutation-side-effects-caller-owned)
+- [Audit runtime compatibility](#audit-runtime-compatibility)
+- [Plan cutover and rollback](#plan-cutover-and-rollback)
+
+## Choose ownership
+
+Write down which system owns each concern before porting code:
+
+| Concern                     | Existing owner          | Target owner                | Proof required                  |
+| --------------------------- | ----------------------- | --------------------------- | ------------------------------- |
+| session issuance/revocation | auth provider/app       | provider/app                | login, logout, expiry, rotation |
+| tenant authorization        | RLS/service             | DAL/middleware/service      | cross-tenant denial tests       |
+| invariants/atomicity        | DB function/trigger     | DB constraint/batch/service | concurrent mutation tests       |
+| scheduled/background work   | host/provider           | Worker queue/cron/waitUntil | retry/idempotency test          |
+| secrets                     | host env/provider vault | target secret store         | no client bundle leakage        |
+
+Do not let a concern become "application code" without naming the module that
+now enforces it.
+
+## Inventory database guarantees
+
+Search the source database for more than tables:
+
+- row-level security policies and grants;
+- functions/RPCs, triggers, generated columns, views, and extensions;
+- unique/check/foreign-key constraints;
+- transaction isolation, row locks, advisory locks, and sequences;
+- storage objects, realtime subscriptions, and database webhooks.
+
+For each item, choose one target:
+
+1. preserve it in the target database;
+2. replace it with a transaction/batch and application service;
+3. reject the feature as unsupported and surface that product gap.
+
+SQLite/D1 does not provide Postgres RLS, stored procedures, or row-level locking
+semantics. A mechanical schema conversion is therefore incomplete even when
+every table exists.
+
+## Replace authorization deliberately
+
+When RLS disappears, build an actor/tenant-scoped data-access layer. Accept an
+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:
+
+- a user cannot read another tenant by guessing an ID;
+- a member cannot perform an owner/admin mutation;
+- a revoked session/token fails immediately enough for the product contract;
+- background jobs and webhooks use an explicit service identity;
+- every API/loader/action path reaches the same guard.
+
+## Extract shared server services
+
+Search server-only Next code for self-calls such as `fetch("/api/...")` or a
+fully qualified request back to the same deployment. On Workers that is a real
+subrequest with added latency and another authentication pass. Extract the
+business operation into a plain service function instead:
+
+```typescript
+async function createProposal(db, scope, actor, input) {
+  // validate, authorize, and mutate once
+}
+```
+
+Let the HTTP response route and an MCP/OAuth/server caller each authenticate in
+their own protocol, derive the same scope, and call that function in-process.
+Keep the HTTP route as an auth-and-delegate boundary for external clients, not
+as the unit of reuse inside the Worker.
+
+## Keep mutation side effects caller-owned
+
+Audit low-level mutations for bundled effects such as activity rows, audit
+logs, cache invalidation, emails, and webhooks. A primitive written for a direct
+edit can double-log when a reviewed proposal later composes the same primitive.
+Prefer an atomic mutation with caller-selected effects, or expose an explicit
+option such as `{ logActivity: false }`. Test composed flows for effect counts,
+not only final row state.
+
+## Audit runtime compatibility
+
+For a Node-to-Workers move, search for:
+
+- `node:*` modules, filesystem/process access, native addons, and TCP clients;
+- SDKs whose default HTTP or crypto implementation is Node-only;
+- synchronous crypto APIs and `Buffer`-specific formats;
+- long-running/background work that exceeds `waitUntil`;
+- response buffering that would destroy RSC streaming.
+
+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.
+
+## Plan cutover and rollback
+
+Define:
+
+1. schema migration order and backfill scripts;
+2. dual-read/write period, if any;
+3. consistency checks and record counts;
+4. auth/session migration or forced reauthentication;
+5. DNS/traffic cutover;
+6. rollback source of truth and the point after which rollback is unsafe.
+
+Run behavior parity in both the old and new applications for protected reads,
+mutations, OAuth/provider callbacks, billing/webhooks, and failure paths. A page
+rendering successfully is not evidence that the backend contract survived.