@rangojs/router 0.16.0 → 0.17.0

package/skills/middleware/SKILL.md

@@ -1,12 +1,17 @@
 ---
 name: middleware
-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.
+description: Define global (router.use) and route (middleware()) middleware in @rangojs/router — auth gates, logging, response headers, context variables, redirects. Use when gating routes behind auth checks, logging requests, setting headers or ctx variables before a handler runs, or deciding whether middleware wraps server actions.
 argument-hint: [middleware-name]
 ---
 
 # Middleware
 
-Middleware runs before/after route handlers using the onion model.
+Middleware runs before and after route handlers using the onion model: code
+before `await next()` runs on the way in, code after it runs on the way out
+with the downstream `Response` available. This skill covers the two
+registration levels (global `router.use()` and route `middleware()`), what each
+wraps (actions, renders, fetchable loaders), the middleware context, and
+common patterns.
 
 ## Execution Model
 
@@ -23,13 +28,15 @@ const router = createRouter<AppEnv>({})
   .routes(urlpatterns);
 ```
 
-When the router has a `basename`, pattern-scoped `.use()` patterns are automatically prefixed. For example, with `basename: "/app"`, `.use("/admin/*", mw)` matches `/app/admin/*`.
+Scope patterns use the route pattern syntax: `:param` (typed on `ctx.params`), optional `:param?`, constrained `:locale(en|gb)`, and a trailing `*` wildcard. When the router has a `basename`, pattern-scoped `.use()` patterns are automatically prefixed. For example, with `basename: "/app"`, `.use("/admin/*", mw)` matches `/app/admin/*`.
+
+A pattern matches the request URL. Server actions are posted to the current page's URL, but an action can be invoked through any URL that matches a route, so a pattern-scoped guard is not an authorization boundary for actions. Authorize sensitive actions inside the action body (see `/server-actions` → "Authorization in actions").
 
 ### Route middleware (`middleware()` in `urls()`)
 
 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.
+> **Implication for auth:** route middleware cannot guard server actions. Load identity in global `router.use()` middleware (it wraps actions) and check authorization inside the action body. See `/server-actions` for action-side auth patterns.
 
 ```
 Request flow (with action):
@@ -74,9 +81,10 @@ For shared segment data, use named revalidation contracts on both the producer
 and consumer segments, even when middleware is present in the chain.
 
 ```typescript
+import type { Revalidate } from "@rangojs/router";
 import * as CartActions from "./actions/cart";
 
-export const revalidateCartData = (ctx) =>
+export const revalidateCartData: Revalidate = (ctx) =>
   ctx.isAction(CartActions) || undefined;
 
 layout(CartLayout, () => [
@@ -104,7 +112,7 @@ layout(CartLayout, () => [
 ]);
 ```
 
-Route middleware is the right place for per-route concerns that affect rendering (setting context variables for handlers, adding response headers, reading cookies set by actions). It is NOT the right place for action guards -- use global middleware for that.
+Route middleware is the right place for per-route concerns that affect rendering (setting context variables for handlers, adding response headers, reading cookies set by actions). It is NOT the right place for action guards -- use global middleware to load identity and check authorization in the action body.
 
 ## Basic Middleware
 
@@ -125,6 +133,13 @@ export const authMiddleware: Middleware = async (ctx, next) => {
 };
 ```
 
+Every middleware must either call `next()` or return (or throw) a `Response`.
+Returning or throwing a `Response` short-circuits the chain; downstream
+middleware and the handler do not run, and headers/cookies already set on the
+context are merged into it. A middleware that does neither throws an error; any
+other return value is ignored with a warning. `await next()` resolves to the
+downstream `Response`, so `return next()` and `await next()` are both fine.
+
 ## Using Middleware in Routes
 
 ```typescript
@@ -132,7 +147,7 @@ import { urls } from "@rangojs/router";
 import { authMiddleware, loggerMiddleware } from "./middleware";
 
 export const urlpatterns = urls(({ path, layout, middleware }) => [
-  // Global middleware for all routes in this file
+  // Route middleware for every route in this urls() tree (wraps renders, not actions)
   middleware(loggerMiddleware),
 
   // Layout with scoped middleware
@@ -192,31 +207,90 @@ middleware([authMw, loggingMw], () => [
 This creates a transparent layout (`<Outlet />`) that carries the middleware.
 The middleware does not affect sibling routes outside the callback.
 
+That scope comes from the routes inside the callback. With no routes inside,
+the wrapper scopes nothing: its middleware runs for every route of the
+enclosing path or layout. Such a wrapper cannot contain `layout()`;
+`router.routes()` throws and points to the flat form:
+
+```typescript
+// throws at definition time
+path("/account", AccountPage, { name: "account" }, () => [
+  middleware(requireAuth, () => [layout(<AccountNav />)]),
+]);
+// same behavior, written flat
+path("/account", AccountPage, { name: "account" }, () => [
+  middleware(requireAuth),
+  layout(<AccountNav />),
+]);
+```
+
 ## Middleware Context
 
 ```typescript
-export const myMiddleware: Middleware = async (ctx, next) => {
-  // Access request
-  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)
+import { cookies, headers } from "@rangojs/router";
+import type { Middleware } from "@rangojs/router";
+import { FlashMessage } from "./location-states";
 
-  // Access platform bindings (plain bindings from createRouter<TEnv>())
+export const myMiddleware: Middleware = async (ctx, next) => {
+  // Request
+  ctx.request; // incoming Request (raw URL, method, body)
+  ctx.url; // URL with internal _rsc* params stripped (also ctx.pathname, ctx.searchParams)
+  ctx.params; // params from the router.use() pattern or the matched route
+  ctx.routeName; // matched route name (reliable after await next() in global middleware)
+  ctx.build; // true only during Prerender + ppr build-shell capture (plain Prerender does not run middleware)
+  headers().get("accept-language"); // read-only request headers (free function)
+  cookies().get("session")?.value; // request cookies (free function; also .set/.delete)
+
+  // Platform bindings (plain bindings from createRouter<TEnv>())
   ctx.env.DB; // D1Database
-  ctx.env.KV; // KVNamespace
+  ctx.waitUntil(async () => {}); // work after the response is sent
 
-  // Set variables for downstream handlers (typed via Rango.Vars)
+  // Variables for downstream middleware, handlers, and loaders (typed via Rango.Vars)
   ctx.set("user", { id: "123", name: "John" });
+  ctx.get("user");
+
+  // Response shaping
+  ctx.header("X-Frame-Options", "DENY"); // set one response header
+  ctx.headers; // response Headers (stub before next(), the real response after)
+  ctx.setLocationState(FlashMessage({ text: "Saved" })); // history state for the client
+  ctx.reverse("home"); // URL for a global route name (no ".name", no param auto-fill)
 
   // Opt the current request out of PPR shell lookup/capture.
   ctx.dynamic();
+  // Print the per-request performance timeline (see /loader → "debugPerformance").
+  ctx.debugPerformance();
+
+  // Continue to the next middleware / the handler
+  const response = await next();
+
+  // After the handler: the real Response is available
+  console.log(response.status);
+};
+```
+
+Cookies and request headers are not `ctx` members; use the free functions
+`cookies()` and `headers()` from `@rangojs/router`.
+
+### Changing the response after `next()`
 
-  // Continue to next middleware/handler
+After `await next()`, `ctx.header()` and `ctx.headers` write to the real
+downstream response. Returning a different `Response` replaces it.
+
+```typescript
+export const securityHeaders: Middleware = async (ctx, next) => {
   await next();
+  ctx.header("Strict-Transport-Security", "max-age=63072000");
+  ctx.headers.set("X-Content-Type-Options", "nosniff");
+};
 
-  // After handler (response intercepting)
-  console.log("Handler completed");
+export const timing: Middleware = async (ctx, next) => {
+  const start = performance.now();
+  try {
+    await next();
+  } finally {
+    // try/catch around next() also sees downstream errors
+    console.log(`${ctx.pathname} ${(performance.now() - start).toFixed(1)}ms`);
+  }
 };
 ```
 
@@ -229,7 +303,8 @@ import { createVar } from "@rangojs/router";
 import type { Middleware } from "@rangojs/router";
 
 interface AuthUser { id: string; email: string; role: string }
-export const CurrentUser = createVar<AuthUser>();
+// cache: false — per-user data must never bake into a cache() segment
+export const CurrentUser = createVar<AuthUser>({ cache: false });
 
 export const authMiddleware: Middleware = async (ctx, next) => {
   const token = ctx.request.headers.get("Authorization");
@@ -241,6 +316,7 @@ export const authMiddleware: Middleware = async (ctx, next) => {
 };
 
 // In a handler -- typed read
+import type { Handler } from "@rangojs/router";
 import { CurrentUser } from "./middleware";
 
 const Dashboard: Handler<"dashboard"> = (ctx) => {
@@ -253,6 +329,18 @@ This works alongside `ctx.get("key")` / `ctx.set("key", value)` (global typing
 via Rango.Vars augmentation). Use `createVar` for route-local or feature-scoped
 data; use Rango.Vars for app-wide middleware state.
 
+Mark request-specific data (sessions, users, tokens) non-cacheable: either on
+the token (`createVar<T>({ cache: false })`) or per write
+(`ctx.set("user", user, { cache: false })`). Reading it with `ctx.get()` inside
+a `cache()` boundary or a `"use cache"` function then throws instead of baking
+one user's data into a shared entry (inside `"use cache"`, also through a
+middleware `ctx` passed in); loaders can still read it because they always run
+fresh (a `"use cache"` function a loader calls cannot). A middleware `ctx`
+passed to a `"use cache"` function keys the call by host, pathname, params and
+search, plus the route name once the route is matched (a global middleware
+before `next()` has none yet), and its `set()`, `header()` and `headers` writes
+throw inside the function (`/use-cache`).
+
 ## Build-Time PPR Middleware
 
 Normal `Prerender` Flight payload collection does not run middleware: there is
@@ -285,12 +373,20 @@ export const commerceMiddleware: Middleware = async (ctx, next) => {
 ## Redirect with State in Middleware
 
 ```typescript
-import { redirect, createLocationState } from "@rangojs/router";
-import type { Middleware } from "@rangojs/router";
+// location-states.ts — shared module; the client component that reads the
+// state must import the same definition
+import { createLocationState } from "@rangojs/router";
 
 export const FlashMessage = createLocationState<{ text: string }>({
   flash: true,
 });
+```
+
+```typescript
+// middleware/auth.ts
+import { redirect } from "@rangojs/router";
+import type { Middleware } from "@rangojs/router";
+import { FlashMessage } from "../location-states";
 
 export const requireAuthMiddleware: Middleware = async (ctx, next) => {
   const token = ctx.request.headers.get("Authorization");
@@ -400,7 +496,7 @@ import {
 } from "./middleware";
 
 export const urlpatterns = urls(({ path, layout, middleware }) => [
-  // Global middleware
+  // Route middleware for every route in this tree (use router.use() to also wrap actions)
   middleware(loggerMiddleware),
   middleware(mockAuthMiddleware),
 

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:
@@ -99,10 +106,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 +130,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 +234,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 +311,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 +377,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 +392,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
@@ -415,6 +438,9 @@ 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.
+import { Suspense } from "react";
+import type { HandlerContext } from "@rangojs/router";
+
 function ProductPage(ctx: HandlerContext) {
   const price = fetchPrice(ctx.params.id); // pending promise — NOT awaited
   return (
@@ -430,10 +456,9 @@ path("/products/:id", ProductPage, {
   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, step 2 (optional refinement) — promote the fetch to a live loader
+// (no ssr: false) for a GUARANTEED hole, even when the value resolves
+// instantly; loading() is its boundary (/ppr → The loader lane rule).
 path(
   "/products/:id",
   ProductPage,
@@ -449,20 +474,18 @@ Differences that matter during migration:
   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.
+  promise nested inside your data stays a live hole. For loaders, `ssr: false`
+  (not `loading()`) selects the lane — see `/ppr` → The loader lane rule.
+  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.
+  they silently force dynamic rendering). Per-user reads must move into a live
+  loader (no `ssr: false`; a nested promise does not help). 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
@@ -496,7 +519,8 @@ renders into). Then invalidate by tag:
 `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
+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 +531,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 +642,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 +657,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 +708,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 +752,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; `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, 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 +804,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 +888,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