@rangojs/router 0.5.1 → 0.6.0

package/skills/hooks/urls.md

@@ -51,26 +51,63 @@ Returns the pathname string without search params or hash. Updates on navigation
 
 ### useSearchParams()
 
-Access the current URL search params:
+Read and write the current URL search params (React Router-style tuple):
 
 ```tsx
 "use client";
 import { useSearchParams } from "@rangojs/router/client";
 
 function SearchResults() {
-  const searchParams = useSearchParams();
+  const [searchParams, setSearchParams] = useSearchParams();
   const query = searchParams.get("q"); // "react"
   const page = searchParams.get("page"); // "2"
 
   return (
     <div>
       Searching for: {query}, page {page}
+      <button onClick={() => setSearchParams({ q: query ?? "", page: "2" })}>
+        Page 2
+      </button>
     </div>
   );
 }
 ```
 
-Returns a `ReadonlyURLSearchParams` (URLSearchParams without mutation methods). During SSR, returns empty params and syncs from the browser URL on mount.
+The first element is a `ReadonlyURLSearchParams` (URLSearchParams without
+mutation methods) from the committed location. During document SSR it
+carries the live request's search (seeded into the SSR store), and the
+browser's first render seeds from its own URL — hydration agrees by
+construction. On ppr routes search is part of shell identity: the shell key
+embeds the sorted search and the capture/resume renders seed that same
+string, so static-part reads are legal and per-shell-correct. Edges: params
+excluded by `cache.searchParams` are absent in shell renders, and
+`.toString()` renders sorted order.
+
+The setter REPLACES the whole search string (React Router semantics) and
+navigates to the current pathname with the new params — a same-route
+navigation, so loaders re-evaluate per their `revalidate()` contract and the
+commit holds previous content. Accepted inits: a string, a `URLSearchParams`,
+a record (numbers/booleans stringified, arrays append, `null`/`undefined`
+skipped), or a function receiving a mutable copy of the current params for
+merging:
+
+```tsx
+// Merge: keep everything, change one key
+setSearchParams((prev) => {
+  prev.set("page", "3");
+  return prev;
+});
+
+// Filter UIs usually want replace + preserved scroll
+setSearchParams({ category: "home" }, { replace: true, scroll: false });
+
+// URL-only update: skip the server fetch for purely client-derived state
+setSearchParams({ view: "grid" }, { revalidate: false });
+```
+
+Options: `replace` (default false — push), `scroll` (default true),
+`revalidate` (default true; `false` skips the server fetch — legal because
+the setter never changes the pathname).
 
 ### useHref()
 

package/skills/loader/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: loader
-description: Define data loaders for fetching data in routes with createLoader. Use when pages need per-request data that stays fresh, data should stream while the page renders, or client components need reactive server data.
-argument-hint: [loader]
+description: Define data loaders for fetching data in routes with createLoader. Use when pages need per-request data that stays fresh, data should stream while the page renders, client components need reactive server data, a loader should throw notFound()/redirect(), set page meta/breadcrumbs from loader data (handle writes), or loader data must be guaranteed in the SSR'd document (stream:"navigation").
+argument-hint: "[loader]"
 ---
 
 # Data Loaders with loader()
@@ -172,23 +172,23 @@ Loaders receive the same context shape as route handlers.
 
 ### Full field surface
 
-| Field          | Type                           | Notes                                                                                                                                                   |
-| -------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `params`       | `TParams`                      | Merged route + explicit loader params; overridable by fetchable `load({ params })`.                                                                     |
-| `routeParams`  | `Record<string, string>`       | Server-trusted route params from URL pattern matching; cannot be overridden.                                                                            |
-| `request`      | `Request`                      | The incoming `Request` (headers, method, body, `signal` for abort).                                                                                     |
-| `url`          | `URL`                          | Parsed request URL.                                                                                                                                     |
-| `pathname`     | `string`                       | URL pathname (shortcut for `ctx.url.pathname`).                                                                                                         |
-| `searchParams` | `URLSearchParams`              | Shortcut for `ctx.url.searchParams`.                                                                                                                    |
-| `search`       | `ResolveSearchSchema<TSearch>` | Typed query params when a search schema is declared on the route; `{}` otherwise.                                                                       |
-| `env`          | `TEnv`                         | Plain bindings from `createRouter<TEnv>()` (DB, KV, secrets, etc.).                                                                                     |
-| `get`          | `(key \| ContextVar) => value` | Reads variables/context-vars set by middleware.                                                                                                         |
-| `use`          | `(loader \| handle) => T`      | Access another loader's data (Promise) or a handle's collected data (after `await ctx.rendered()`).                                                     |
-| `rendered`     | `() => Promise<void>`          | **Experimental.** DSL loaders only — waits for all non-loader segments (including `loading()` streaming handlers) to settle before reading handle data. |
-| `method`       | `string`                       | HTTP method. `"GET"` for SSR loader runs; reflects real method for fetchable loaders.                                                                   |
-| `body`         | `TBody \| undefined`           | Parsed request body for fetchable POST/PUT/PATCH/DELETE calls.                                                                                          |
-| `formData`     | `FormData \| undefined`        | Present when a fetchable loader is invoked via form submission.                                                                                         |
-| `reverse`      | `ScopedReverseFunction`        | Generate type-checked URLs from route names (same scoped semantics as route handlers).                                                                  |
+| Field          | Type                            | Notes                                                                                                                                                                                                    |
+| -------------- | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `params`       | `TParams`                       | Merged route + explicit loader params; overridable by fetchable `load({ params })`.                                                                                                                      |
+| `routeParams`  | `Record<string, string>`        | Server-trusted route params from URL pattern matching; cannot be overridden.                                                                                                                             |
+| `request`      | `Request`                       | The incoming `Request` (headers, method, body, `signal` for abort).                                                                                                                                      |
+| `url`          | `URL`                           | Parsed request URL.                                                                                                                                                                                      |
+| `pathname`     | `string`                        | URL pathname (shortcut for `ctx.url.pathname`).                                                                                                                                                          |
+| `searchParams` | `URLSearchParams`               | Shortcut for `ctx.url.searchParams`.                                                                                                                                                                     |
+| `search`       | `ResolveSearchSchema<TSearch>`  | Typed query params when a search schema is declared on the route; `{}` otherwise.                                                                                                                        |
+| `env`          | `TEnv`                          | Plain bindings from `createRouter<TEnv>()` (DB, KV, secrets, etc.).                                                                                                                                      |
+| `get`          | `(key \| ContextVar \| handle)` | Reads middleware variables/context-vars — or READS a handle's collected data, after `await ctx.rendered()`.                                                                                              |
+| `use`          | `(loader \| handle) => T`       | Access another loader's data (Promise), or WRITE a handle: `ctx.use(Meta)({ title })` returns the push function — handler parity. Reads moved to `get`.                                                  |
+| `rendered`     | `() => Promise<void>`           | **Experimental.** DSL loaders only — waits for all non-loader segments (including `loading()` streaming handlers) to settle before reading handle data. Not with `stream: "navigation"` (cycle; throws). |
+| `method`       | `string`                        | HTTP method. `"GET"` for SSR loader runs; reflects real method for fetchable loaders.                                                                                                                    |
+| `body`         | `TBody \| undefined`            | Parsed request body for fetchable POST/PUT/PATCH/DELETE calls.                                                                                                                                           |
+| `formData`     | `FormData \| undefined`         | Present when a fetchable loader is invoked via form submission.                                                                                                                                          |
+| `reverse`      | `ScopedReverseFunction`         | Generate type-checked URLs from route names (same scoped semantics as route handlers).                                                                                                                   |
 
 ### Example
 
@@ -442,7 +442,10 @@ boundary a parallel loader blocks its parent, so add one to keep the overlap.)
 
 If you come from a framework where the loader is a blocking step that runs
 before the response is built, this is the shift to internalize: here the
-response starts streaming first and loader data fills in.
+response starts streaming first and loader data fills in. (The one deliberate
+exception is per-loader: `loader(Def, { stream: "navigation" })` awaits that
+loader before first flush on document renders — see "`stream: "navigation"`"
+below.)
 
 ### See it: `debugPerformance`
 
@@ -660,6 +663,115 @@ function ProductPage() {
 }
 ```
 
+## Loader Authority: notFound() and redirect()
+
+A loader may **throw** `notFound()` and `redirect()` — data-dependent
+authority lives with the data, so every consumer of the loader inherits the
+signal instead of re-checking existence at each read site:
+
+```typescript
+import { createLoader, notFound, redirect } from "@rangojs/router";
+
+export const ProductLoader = createLoader(async (ctx) => {
+  "use server";
+  const moved = LEGACY_SLUGS[ctx.params.slug];
+  if (moved) throw redirect(`/shop/product/${moved}`);
+
+  // Existence check BEFORE the expensive fetch: a near-instant rejection
+  // usually wins the race to first flush (see the semantics below).
+  if (!(await exists(ctx.params.slug))) notFound(`No "${ctx.params.slug}"`);
+
+  return getProduct(ctx.params.slug);
+});
+```
+
+Semantics by lane:
+
+| Signal       | Document load                                                                                                                                                                                                                                                         | Client navigation                                 |
+| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
+| `notFound()` | Not-found UI resolves server-side (nearest `notFoundBoundary` → router option → default) and rides the envelope; the 404 STATUS is **opportunistic** — real only if the rejection beats Response construction. `stream: "navigation"` (below) makes it deterministic. | 404 UI swaps in, URL preserved, payload stays 200 |
+| `redirect()` | 200 document, then a client-side replace to the target — **no document-lane 302 from loaders**; pre-stream redirect authority belongs to middleware                                                                                                                   | Redirect envelope navigates to the target         |
+
+Session/auth gates belong in middleware (they are request-shaped, not
+data-shaped, and middleware CAN emit a real pre-stream 302). Data-dependent
+"this slug moved / does not exist" belongs in the loader.
+
+## Writing Handles from Loaders (meta, breadcrumbs)
+
+Loader bodies can WRITE handles with handler parity — `ctx.use(Handle)`
+returns the push function, legal for the whole body, streaming loaders
+included. This is how data-derived page titles and breadcrumb trails live
+where the data lives:
+
+```typescript
+import { Meta, Breadcrumbs } from "./handles";
+
+export const ProductLoader = createLoader(async (ctx) => {
+  "use server";
+  const product = await getProduct(ctx.params.slug);
+
+  ctx.use(Meta)({ title: `${product.name} — Shop` });
+  const pushCrumb = ctx.use(Breadcrumbs);
+  pushCrumb({ label: "Shop", href: "/shop" });
+  pushCrumb({ label: product.name, href: `/shop/product/${product.slug}` });
+
+  return product;
+});
+```
+
+Delivery is async **by the race model**: pushes that settle before the handler
+barrier ride the SSR handle snapshot (in the SSR'd document — `<MetaTags />`,
+`useHandle` reads); later pushes stream to the client and apply post-hydration
+on document loads (`metadata.handlesLate`) or progressively on navigations.
+A push before your slow fetch usually beats the barrier; a push derived from
+the fetched data usually does not. When it MUST be in the document, use
+`stream: "navigation"` below.
+
+Reads are the other direction and gated: `ctx.get(handle)` throws unless the
+loader first does `await ctx.rendered()` (DSL-registered loaders only —
+handler-invoked loaders cannot use `rendered()`, and a handler already
+awaiting the loader via `ctx.use()` makes it a detected deadlock).
+
+## `stream: "navigation"` — Guarantee a Loader in the Document
+
+Streaming means nothing a slow loader produces is _guaranteed_ in the SSR'd
+HTML: its section SSRs as the fallback, a late handle push applies
+post-hydration, a late `notFound()` loses the status race. When the loader
+feeds something that must exist in the document — `<head>` meta via a handle,
+or a real 404 status — pass delivery options between the definition and the
+use callback:
+
+```typescript
+path("/product/:slug", ProductPage, { name: "product" }, () => [
+  loader(ProductLoader, { stream: "navigation" }, () => [cache({ ttl: 60 })]),
+  loader(RelatedLoader),   // untouched: still streams behind its boundary
+]),
+```
+
+The name says WHERE streaming still applies, not that it is disabled:
+document renders await this loader before first flush — data is settled
+(`useLoader` reads it synchronously, no fallback paints), handle pushes beat
+the barrier snapshot, and a thrown `notFound()` deterministically precedes
+Response construction (real 404, no warm-up race). Client navigations stream
+exactly as before. Scoped per LOADER: the flagged loader awaits only itself;
+siblings keep streaming.
+
+The costs and constraints:
+
+- Every document load pays the flagged loader's latency before first byte.
+  That is the point — but keep flagged loaders fast, and flag loaders, not
+  routes.
+- A flagged loader must not `await ctx.rendered()` / `ctx.get(handle)` — the
+  document render awaits the loader before the render barrier resolves, so
+  that wait is a cycle by construction; it throws a deadlock error naming the
+  fix.
+- PPR capture renders mask loaders and skip the await — the flag does not
+  bake anything into a shell (`/ppr`).
+
+Also available in `clientUrls()` route groups (`/client-urls`), where the
+loader-heavy shape makes it most useful. `LoaderOptions` is exported from the
+package root.
+
 ## Fetchable Loaders
 
 By default, loaders only run during SSR and navigation. Pass `true` as the second

package/skills/migrate-nextjs/SKILL.md

@@ -657,15 +657,45 @@ 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` |
-| `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")`                                                                                                                                                                         |
+| `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)
+
+Next.js's instant navigations — `<Link>` auto-prefetch feeding the client
+router cache — map to Rango's prefetch system: per-Link
+`prefetch="viewport" | "hover" | "none"` (or the router-wide `defaultPrefetch`
+option) warms the target's partial RSC payload before the click, and a click
+on a warmed link commits the prefetched payload as a whole — the complete
+page lands instantly, no fetch waterfall. Prefetched entries survive being
+used (they re-arm in place) and expire by `prefetchCacheTTL`; actions and
+`invalidateClientCache()` flush them so a stale payload is never committed.
+
+```tsx
+<Link to="/product/widget" prefetch="viewport">
+  Widget
+</Link>
+```
+
+Two differences from Next.js worth knowing: the trigger is an explicit choice
+(viewport vs hover vs none) rather than an internal scheduler, and container
+opt-outs exist for whole DOM sections (`data-prefetch-scope="none"`). See
+`/links` → "Prefetch boundaries".
+
+For **dashboard / admin / settings-shaped sections** — high navigation
+frequency inside one layout, mostly tab/param/filter switches — also consider
+porting that route group to `clientUrls()` (`/client-urls`): the definition
+matches in the browser (instant optimistic pending, no server round-trip to
+start a transition) and browser-run `revalidate()` predicates hold data across
+switches that don't invalidate it, which is the fastest transition shape Rango
+has. Server-component routes and `clientUrls()` groups compose in one tree.
 
 ## 7. Server Actions
 
@@ -694,6 +724,34 @@ const HomePage: Handler<"home"> = (ctx) => {
 };
 ```
 
+`generateMetadata({ params })` — DATA-derived, document-blocking metadata —
+maps to a Meta push from the LOADER that owns the data, plus
+`{ stream: "navigation" }` for the blocking-until-in-head part:
+
+```typescript
+// Next.js: export async function generateMetadata({ params }) {
+//   const product = await getProduct(params.slug);
+//   return { title: product.name };
+// }
+
+// Rango: push from the loader; the flag makes the document render await it,
+// so the title is in the SSR'd <head> like generateMetadata guarantees.
+export const ProductLoader = createLoader(async (ctx) => {
+  "use server";
+  const product = await getProduct(ctx.params.slug);
+  ctx.use(Meta)({ title: product.name });
+  return product;
+});
+
+path("/product/:slug", ProductPage, { name: "product" }, () => [
+  loader(ProductLoader, { stream: "navigation" }),
+]);
+```
+
+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>`:
 
 ```typescript
@@ -780,10 +838,12 @@ See `/theme` for full API including system detection and cookie persistence.
 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`
+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
+        (`generateMetadata` → loader push + `{ stream: "navigation" }`)
 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

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

@@ -59,6 +59,42 @@ React Router v7 has two modes that require different migration paths:
 React Router v6 and Remix v2 follow the same patterns as v7 library mode and
 framework mode respectively.
 
+## Two target shapes: server handlers or clientUrls()
+
+Every RR route lands in one of two Rango shapes — pick per route group, not
+per app (both compose in one `urls()` tree via `include()`):
+
+- **Server handlers** (the default in this guide): the route component becomes
+  a server component, data fetching merges into the handler. This is the shape
+  with the biggest wins — server-first rendering, smaller client bundles — and
+  the right target whenever the component CAN become a server component.
+
+- **`clientUrls()` groups** (`/client-urls`): for route groups whose components
+  are irreducibly hook-heavy client components, this is the mechanical port —
+  the RR route-module shape maps almost 1:1 and nothing changes seat:
+
+  | RR route module                  | clientUrls()                                             |
+  | -------------------------------- | -------------------------------------------------------- |
+  | component (client, hooks)        | stays a client component — no conversion                 |
+  | `loader` (throws `redirect`/404) | `createLoader()` — thrown `redirect()`/`notFound()` kept |
+  | `useLoaderData()`                | `useLoader(Loader)` at the read site, under `<Suspense>` |
+  | `shouldRevalidate` (runs client) | `revalidate()` predicate — ALSO runs in the browser      |
+  | `meta({ data })`                 | `ctx.use(Meta)` push from the loader body                |
+  | `defer` / `Await`                | loaders stream; `<Suspense>` above each read             |
+
+  Note the `shouldRevalidate` row: a server-tree `revalidate()` runs on the
+  server, but a `clientUrls()` predicate runs in the browser with
+  client-computable args — the exact RR semantics. A group ported this way can
+  still be re-migrated to server handlers later, route by route.
+
+Start with server handlers; reach for `clientUrls()` when a route group's
+conversion cost is dominated by rewriting interactive components rather than
+by moving data fetching — or when the group is a **high-navigation-speed
+surface** (dashboard, admin panel, settings): browser-local matching gives
+instant optimistic pending, and browser-run predicates hold data across
+tab/param switches, so transitions are the fastest Rango offers. See
+`/client-urls`.
+
 ## Migration Strategy
 
 Work route-by-route, bottom-up. Start with leaf routes, then layouts, then
@@ -73,19 +109,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()`, `useParams()` from `@rangojs/router/client`         |
-| `useLoaderData`                               | merge the loader into the handler; `useLoader()` only for live client data (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` |
+| `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)                                                                       |
 
 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.

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

@@ -85,19 +85,19 @@ layout(<ShopLayout />, () => [
 
 ## 6. Navigation
 
-| React Router                              | Rango                                                                            |
-| ----------------------------------------- | -------------------------------------------------------------------------------- |
-| `import { Link } from "react-router-dom"` | `import { Link } from "@rangojs/router/client"`                                  |
-| `<Link to="/about">`                      | `<Link to="/about">`                                                             |
-| `useNavigate()`                           | `useRouter()` from `@rangojs/router/client`                                      |
-| `navigate("/about")`                      | `useRouter().push("/about")`                                                     |
-| `navigate("/about", { replace: true })`   | `useRouter().replace("/about")`                                                  |
-| `navigate(-1)`                            | `useRouter().back()`                                                             |
-| `useLocation().pathname`                  | `usePathname()` from `@rangojs/router/client`                                    |
-| `useSearchParams()`                       | `useSearchParams()` from `@rangojs/router/client`                                |
-| `useParams()`                             | `useParams()` from `@rangojs/router/client` (or `ctx.params` in server handlers) |
-| `useParams<T>()`                          | `useParams<T>()` — same generic annotation pattern                               |
-| `<NavLink>`                               | `<Link>` with `usePathname()` for active state                                   |
+| React Router                              | Rango                                                                                                                                                                    |
+| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `import { Link } from "react-router-dom"` | `import { Link } from "@rangojs/router/client"`                                                                                                                          |
+| `<Link to="/about">`                      | `<Link to="/about">`                                                                                                                                                     |
+| `useNavigate()`                           | `useRouter()` from `@rangojs/router/client`                                                                                                                              |
+| `navigate("/about")`                      | `useRouter().push("/about")`                                                                                                                                             |
+| `navigate("/about", { replace: true })`   | `useRouter().replace("/about")`                                                                                                                                          |
+| `navigate(-1)`                            | `useRouter().back()`                                                                                                                                                     |
+| `useLocation().pathname`                  | `usePathname()` from `@rangojs/router/client`                                                                                                                            |
+| `useSearchParams()`                       | `useSearchParams()` from `@rangojs/router/client` — same `[params, setParams]` tuple; setter replaces the whole search string, options `{ replace, scroll, revalidate }` |
+| `useParams()`                             | `useParams()` from `@rangojs/router/client` (or `ctx.params` in server handlers)                                                                                         |
+| `useParams<T>()`                          | `useParams<T>()` — same generic annotation pattern                                                                                                                       |
+| `<NavLink>`                               | `<Link>` with `usePathname()` for active state                                                                                                                           |
 
 ### useNavigate → useRouter
 
@@ -132,6 +132,11 @@ const HomePage: Handler<"home"> = (ctx) => {
 };
 ```
 
+RR's data-derived `meta({ data })` maps to the same push from the LOADER that
+owns the data — `ctx.use(Meta)({ title: data.name })` in the loader body, with
+`loader(Def, { stream: "navigation" })` when the title must be in the SSR'd
+head. See `/loader` → "Writing Handles from Loaders".
+
 Add `<MetaTags />` in the Document component's `<head>`:
 
 ```typescript

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

@@ -40,9 +40,20 @@ Use it only when you need capabilities beyond what the handler provides:
   to all child routes via `ctx.use(Loader)` or `useLoader(Loader)`
 - **Independent revalidation** — `revalidate()` on a specific loader after actions
 - **Per-loader caching** — `loader(L, () => [cache({ ttl: 60 })])`
-
-If the React Router loader just fetches data for its page component, merge it
-into the handler. See `/loader` for when the live data layer is useful.
+- **RR-loader-shaped authority** — a loader that `throw redirect(...)`s or
+  throws a 404 keeps that shape: Rango loaders throw `redirect()`/`notFound()`
+  too (one caveat: a Rango loader redirect is a client-side navigate on
+  document loads, never an HTTP 302 — pre-stream 302s move to middleware)
+- **`meta({ data })` / `handle` exports** — data-derived page metadata becomes
+  a handle push from the loader body (`ctx.use(Meta)({ title: data.name })`),
+  with `loader(L, { stream: "navigation" })` when it must be in the SSR'd head
+
+If the React Router loader just fetches data for its page component AND the
+component can become a server component, merge it into the handler. If the
+component stays a client component, port the whole group with `clientUrls()`
+instead — loader, `useLoader` read, and browser-run `revalidate()` keep the RR
+route-module shape (see the "Two target shapes" section in the main skill and
+`/client-urls`). See `/loader` for when the live data layer is useful.
 
 ### Actions
 

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

@@ -52,9 +52,12 @@ In framework mode, each route is a file with conventional exports (`loader`,
 RR7 route module export     → Rango equivalent
 ─────────────────────────────────────────────────────
 default (Component)         → handler in path()
-loader                      → fetch in handler, or createLoader()
+loader                      → fetch in handler, or createLoader() — a Rango
+                              loader keeps the RR shape: throw redirect()/
+                              notFound(), push meta from the body
 action                      → "use server" function
-meta                        → ctx.use(Meta) in handler
+meta                        → ctx.use(Meta) in handler; meta({ data }) →
+                              ctx.use(Meta) push in the loader that owns data
 headers                     → ctx.header() in handler or middleware
 shouldRevalidate            → revalidate() DSL
 ErrorBoundary               → errorBoundary() DSL
@@ -128,6 +131,16 @@ path("/product/:slug", ProductPage, { name: "product" }, () => [
 Key shift: the route module's scattered exports consolidate into the handler
 (data fetching, meta, headers) and the DSL (revalidation, error boundary, loading).
 
+The loader-shaped variant is equally valid — and closer to the RR module when
+the loader carried authority. A `createLoader()` body can throw `notFound()`
+for the missing product AND push the data-derived meta itself
+(`ctx.use(Meta)({ title: product.name })`); register it with
+`loader(ProductLoader, { stream: "navigation" })` when the 404 status and
+title must be in the document deterministically. See `/loader` → "Loader
+Authority" and "Writing Handles from Loaders". (One RR habit that does NOT
+carry over: a loader `throw redirect()` is a client-side navigate on document
+loads, never an HTTP 302 — pre-stream 302s belong in middleware.)
+
 ### RR7 file routing → urls() DSL
 
 | RR7 file path                            | Rango                                                         |

package/skills/mime-routes/SKILL.md

@@ -132,9 +132,11 @@ response payload types, use one of these surfaces:
 // router.tsx
 export const router = createRouter({ document: Document }).routes(urlpatterns);
 
+type AppRoutes = typeof router.routeMap;
+
 declare global {
   namespace Rango {
-    interface RegisteredRoutes extends typeof router.routeMap {}
+    interface RegisteredRoutes extends AppRoutes {}
   }
 }
 ```

package/skills/parallel/SKILL.md

@@ -99,7 +99,8 @@ path("/dashboard/:id", (ctx) => {
 ## Setting Handles (Meta, Breadcrumbs)
 
 Parallel slot handlers can call `ctx.use(Meta)` or `ctx.use(Breadcrumbs)` to
-push handle data. The data is associated with the **parent** layout or route
+push handle data. (Loader bodies can too — see `/loader` → "Writing Handles
+from Loaders" — which often replaces the UI-less `@meta` slot below.) The data is associated with the **parent** layout or route
 segment, not the parallel segment itself. This is because parallels execute
 after their parent handler and inherit its segment scope.
 
@@ -130,6 +131,15 @@ route overrides via its own `@meta` slot. Since child segments push after
 parents and `collectMeta` uses last-wins deduplication, overrides work
 naturally.
 
+> **Loader-derived metadata: push from the loader instead.** This slot's
+> `await ctx.use(ProductLoader)` routes the data through HANDLER consumption —
+> the baked lane under `cache()`/PPR — just to reach a `ctx.use(Meta)` call.
+> The loader can now push `Meta` itself (`/loader` → "Writing Handles from
+> Loaders"), keeping the data on the live lane; add
+> `loader(Def, { stream: "navigation" })` when the meta must be in the SSR'd
+> head. Keep the `@meta` slot for metadata that is NOT loader-derived
+> (templates, static descriptions, structured data with independent inputs).
+
 ```typescript
 // Layout sets defaults
 layout((ctx) => {
@@ -374,6 +384,27 @@ A `revalidate()` callback may return a hard `boolean`, a soft
 for the full contract — it's the same across `loader()`, `path()`,
 `layout()`, `parallel()`, and `intercept()`.
 
+A route-scoped slot revalidates on ANY params or search change by default —
+including query-only navigations (`?tab=…`) its content doesn't depend on. If
+the slot has no `loading()` of its own, that refresh suspends at the nearest
+boundary above it: the route's `loading()`, replacing the entire route content
+with the route skeleton while one slot refetches. Either scope the slot's
+`revalidate()` (share the route's named contract, as above) or give the slot
+its own `loading()` so the fallback stays local. Don't reach for a bare
+`revalidate(() => false)`: the slot then never refreshes on param changes
+either, and keeps the previous param's content on e.g. a product-to-product
+navigation.
+
+`revalidate()` decides whether to _re_-render a slot, never whether to render
+it the first time. A slot the browser has not rendered yet has nothing cached
+to keep showing, so returning `false` for it would just leave a hole. On that
+first render the decision is clamped to `true` and your callback's `false` is
+ignored; from the second visit onward it is honored and the browser keeps the
+copy it already has. This is what makes `revalidate(() => false)` mean "render
+once, then never refetch" rather than "sometimes never appear at all" — before
+the clamp, landing on a sibling route and navigating in left the slot blank
+until a full reload.
+
 ### Revalidation Contracts for Parallel Dependencies
 
 Prefer named revalidation contracts shared by both the upstream producer and