@rangojs/router 0.0.0-experimental.15 → 0.0.0-experimental.151

package/README.md

@@ -1,45 +1,24 @@
-# @rangojs/router
+# Rango
 
-Django-inspired RSC router with type-safe partial rendering for Vite.
+A code-first, type-safe React Server Components router. Django-inspired:
+routes are expressed in one visible tree, URLs are built from names, and
+everything past the core is opt-in.
 
-> **Experimental:** This package is under active development. APIs may change between releases. Install with `@experimental` tag.
+> **Experimental:** This package is under active development. APIs may change
+> between releases. Install with `@experimental` tag.
 
-## Features
+This page is a tour: it builds one small shop and meets the entire core API
+along the way — about six primitives. Everything else is opt-in and linked at
+the end. For the design rationale behind these APIs, read
+[Why Rango](https://github.com/ivogt/vite-rsc/blob/main/packages/rangojs-router/docs/why-rango.md); this page shows how it feels, that page
+argues why it's right.
 
-- **Composable URL patterns** — Django-style `urls()` DSL with `path`, `layout`, `include`
-- **Named routes** — `reverse("blogPost", { slug })` for type-safe URL generation (Django-style)
-- **Data loaders** — `createLoader()` with automatic streaming and Suspense integration
-- **Layouts & nesting** — Nested layouts with `<Outlet />` and parallel routes
-- **Segment-level caching** — `cache()` DSL with TTL/SWR and pluggable cache stores
-- **Middleware** — Route-level middleware with cookie and header access
-- **Pre-rendering** — `Prerender()` and `Static()` handlers for build-time rendering
-- **Theme support** — Light/dark mode with FOUC prevention and system detection
-- **Host routing** — Multi-app routing by domain/subdomain via `@rangojs/router/host`
-- **Response routes** — `path.json()`, `path.text()`, `path.xml()` for API endpoints
-- **CLI codegen** — `rango generate` for route type generation
-
-## Installation
-
-```bash
-npm install @rangojs/router@experimental
-```
-
-Peer dependencies:
+## Install
 
 ```bash
-npm install react @vitejs/plugin-rsc
+npm install @rangojs/router@experimental react @vitejs/plugin-rsc
 ```
 
-For Cloudflare Workers:
-
-```bash
-npm install @cloudflare/vite-plugin
-```
-
-## Quick Start
-
-### Vite Config
-
 ```ts
 // vite.config.ts
 import react from "@vitejs/plugin-react";
@@ -47,557 +26,435 @@ import { defineConfig } from "vite";
 import { rango } from "@rangojs/router/vite";
 
 export default defineConfig({
-  plugins: [
-    react(),
-    rango({ preset: "cloudflare" }),
-  ],
+  plugins: [react(), rango({ preset: "cloudflare" })],
 });
 ```
 
-### Router
+The `cloudflare` preset targets Cloudflare Workers (add
+`@cloudflare/vite-plugin`); the `vercel` preset emits a ready-to-deploy
+`.vercel/output` (Build Output API) from a plain `vite build` — see the
+[`/vercel` skill](./skills/vercel/SKILL.md); omit `preset` for the default
+Node setup.
+
+## Using the skills with your coding agent
+
+This package ships 43 agent skills in `node_modules/@rangojs/router/skills/` —
+task-focused guides written for LLM coding agents. Start at
+`skills/rango/SKILL.md` (the mental model + catalog); a machine-readable index
+is at `skills/catalog.json`.
+
+- **Claude Code**: point it at the skills (e.g. "read
+  node_modules/@rangojs/router/skills/rango/SKILL.md before routing work"), or
+  copy/symlink the directories you use into your project's `.claude/skills/`.
+- **Other agents (Cursor, Codex CLI, Gemini CLI, ...)**: these harnesses
+  auto-discover skills from `.agents/skills/` in your project (or
+  `~/.agents/skills/`) — copy or symlink the skill directories you use from
+  `node_modules/@rangojs/router/skills/<name>` into `.agents/skills/<name>`.
+  The files are plain markdown; cross-references like `/loader` name sibling
+  skill directories.
+
+## 1. Pages
+
+A router is a tree. `path()` places a page, `layout()` wraps children,
+`{ name }` gives a route an identity:
 
 ```tsx
 // src/router.tsx
 import { createRouter, urls } from "@rangojs/router";
 import { Document } from "./document";
+import { ShopLayout } from "./layouts/shop";
+import { HomePage } from "./routes/home";
+import { ProductPage } from "./routes/product";
 
 const urlpatterns = urls(({ path, layout }) => [
-  layout(<MainLayout />, () => [
+  layout(<ShopLayout />, () => [
     path("/", HomePage, { name: "home" }),
-    path("/about", AboutPage, { name: "about" }),
-    path("/blog/:slug", BlogPostPage, { name: "blogPost" }),
+    path("/products/:slug", ProductPage, { name: "product" }),
   ]),
 ]);
 
-export const router = createRouter({ document: Document })
-  .routes(urlpatterns);
-
-// Export typed reverse function for URL generation by route name
-export const reverse = router.reverse;
+export const router = createRouter({ document: Document }).routes(urlpatterns);
 ```
 
-### Document
+```tsx
+// src/layouts/shop.tsx
+import { Outlet } from "@rangojs/router/client";
+
+export function ShopLayout() {
+  return (
+    <div>
+      <nav>Shop</nav>
+      <main>
+        <Outlet /> {/* child routes render here */}
+      </main>
+    </div>
+  );
+}
+```
 
 ```tsx
 // src/document.tsx
 "use client";
 
 import type { ReactNode } from "react";
-import { MetaTags } from "@rangojs/router/client";
+import { MetaTags, Scripts } from "@rangojs/router/client";
 
 export function Document({ children }: { children: ReactNode }) {
   return (
     <html lang="en">
       <head>
         <MetaTags />
+        <Scripts />
       </head>
-      <body>{children}</body>
+      <body>
+        <Scripts position="body" />
+        {children}
+      </body>
     </html>
   );
 }
 ```
 
-## Defining Routes
-
-### Path Patterns
-
-```tsx
-import { urls } from "@rangojs/router";
-
-const urlpatterns = urls(({ path }) => [
-  path("/", HomePage, { name: "home" }),
-  path("/product/:slug", ProductPage, { name: "product" }),
-  path("/search/:query?", SearchPage, { name: "search" }),
-  path("/files/*", FilesPage, { name: "files" }),
-]);
-```
-
-### Typed Handlers
+(The built-in `DefaultDocument` already wires all of this — a custom document
+is optional.)
 
-Route handlers receive a typed context with params, search params, and `reverse()`:
+A handler is a function of `ctx`. Typing it by route name gives typed params
+— the Vite plugin generates the route map automatically, nothing to register:
 
 ```tsx
+// src/routes/product.tsx
 import type { Handler } from "@rangojs/router";
 
 export const ProductPage: Handler<"product"> = (ctx) => {
-  const { slug } = ctx.params; // typed from pattern
-  const homeUrl = ctx.reverse("home"); // type-safe URL by route name
-  return <h1>Product: {slug}</h1>;
-};
-```
-
-### Search Params
-
-Define a search schema on the route for type-safe search parameters:
-
-```tsx
-const urlpatterns = urls(({ path }) => [
-  path("/search", SearchPage, {
-    name: "search",
-    search: { q: "string", page: "number?", sort: "string?" },
-  }),
-]);
-
-// Handler receives typed searchParams
-const SearchPage: Handler<"search"> = (ctx) => {
-  const { q, page, sort } = ctx.searchParams;
-  // q: string, page: number | undefined, sort: string | undefined
+  return <h1>{ctx.params.slug}</h1>; // slug: string, from the pattern
 };
 ```
 
-### Response Routes
-
-Define API endpoints that bypass the RSC pipeline:
+And because routes have names, URLs are built, never hand-written:
 
 ```tsx
-const urlpatterns = urls(({ path }) => [
-  path.json("/api/health", () => ({ status: "ok" }), { name: "health" }),
-  path.text("/robots.txt", () => "User-agent: *\nAllow: /", { name: "robots" }),
-  path.xml("/feed.xml", () => "<rss>...</rss>", { name: "feed" }),
-]);
-```
-
-Response types available: `path.json()`, `path.text()`, `path.html()`, `path.xml()`, `path.image()`, `path.stream()`, `path.any()`.
-
-## Layouts & Nesting
-
-### Layouts with Outlet
-
-```tsx
-import { urls } from "@rangojs/router";
-
-const urlpatterns = urls(({ path, layout }) => [
-  layout(<MainLayout />, () => [
-    path("/", HomePage, { name: "home" }),
-    path("/about", AboutPage, { name: "about" }),
-  ]),
-]);
+const url = ctx.reverse("product", { slug: "espresso-cup" });
+// "/products/espresso-cup" — name and params compile-time checked
 ```
 
-```tsx
-"use client";
-import { Outlet } from "@rangojs/router/client";
+Rename `/products/:slug` to `/shop/:slug` in the one place it's defined and
+every link, redirect, and prefetch follows. In client components, `href()`
+validates static paths against the registered patterns:
+`<Link to={href("/")}>Home</Link>`.
 
-function MainLayout() {
-  return (
-    <div>
-      <nav>...</nav>
-      <Outlet />
-    </div>
-  );
-}
-```
+The tree is also lazy-first, which is the shape serverless cold starts want.
+`include()` mounts a whole route module under a prefix — and with the async
+form, `include("/shop", () => import("./shop"))`, the group is code-split:
+its module doesn't load or run until a request matches it, a group nobody
+visits never evaluates at all, and warm requests run zero route handlers.
+Boot cost stays flat as the app grows — one module body at startup, not one
+per group — while matching stays an `O(path length)` prefix trie, identical
+in dev and production. None of this is assumed: the trie is benchmarked
+in-repo against multi-thousand-route manifests, and the lazy guarantees are
+pinned by run-count tests (see
+[matching & lazy discovery](https://github.com/ivogt/vite-rsc/blob/main/packages/rangojs-router/docs/internal/matching-and-lazy-discovery.md)).
+Grow the tree without watching the boot time.
 
-### Loading Skeletons
+That's a working site. Everything below adds to this app.
 
-```tsx
-const urlpatterns = urls(({ path, loading }) => [
-  path("/product/:slug", ProductPage, { name: "product" }, () => [
-    loading(<ProductSkeleton />),
-  ]),
-]);
-```
+## 2. Data
 
-### Parallel Routes
+The product page needs data. A handler is an async server component — fetch
+where you render:
 
 ```tsx
-const urlpatterns = urls(({ path, layout, parallel, loader, loading }) => [
-  layout(BlogLayout, () => [
-    parallel({ "@sidebar": BlogSidebarHandler }, () => [
-      loader(BlogSidebarLoader),
-      loading(<SidebarSkeleton />),
-    ]),
-    path("/blog", BlogIndexPage, { name: "blog" }),
-    path("/blog/:slug", BlogPostPage, { name: "blogPost" }),
-  ]),
-]);
+// src/routes/product.tsx
+export const ProductPage: Handler<"product"> = async (ctx) => {
+  const product = await db.products.find(ctx.params.slug);
+  ctx.use(Meta)({ title: product.name }); // metadata where the data is
+  return <ProductView product={product} />;
+};
 ```
 
-## Data Loaders
+That's the default data path. React Router and Remix split data into a
+loader beside the component because components couldn't fetch; RSC collapses
+the split, and Rango doesn't reintroduce it. (That `ctx.use(Meta)` line is
+also the whole metadata story: push tags where the data already is, layouts
+set title templates, deeper segments override — no separate metadata export,
+no second fetch.)
 
-### Creating a Loader
+Loaders enter when data needs a life of its own. First case: a **client
+component** needs server data — the stock badge is interactive, but the
+stock lives in the database:
 
 ```tsx
+// src/loaders/stock.ts
 import { createLoader } from "@rangojs/router";
 
-export const BlogSidebarLoader = createLoader(async (ctx) => {
-  const posts = await db.getRecentPosts();
-  return { posts, loadedAt: new Date().toISOString() };
+export const StockLoader = createLoader(async (ctx) => {
+  "use server";
+  return db.stockFor(ctx.params.slug);
 });
 ```
 
-### Using in Server Components (Handlers)
-
 ```tsx
-import type { HandlerContext } from "@rangojs/router";
-import { BlogSidebarLoader } from "./loaders/blog";
-
-async function BlogSidebarHandler(ctx: HandlerContext) {
-  const { posts } = await ctx.use(BlogSidebarLoader);
-  return <ul>{posts.map(p => <li key={p.slug}>{p.title}</li>)}</ul>;
-}
+path("/products/:slug", ProductPage, { name: "product" }, () => [
+  loader(StockLoader),
+  loading(<ProductSkeleton />),
+]),
 ```
 
-### Using in Client Components
-
 ```tsx
+// src/components/stock-badge.tsx
 "use client";
 import { useLoader } from "@rangojs/router/client";
-import { BlogSidebarLoader } from "./loaders/blog";
+import { StockLoader } from "../loaders/stock";
 
-function BlogSidebar() {
-  const { posts } = useLoader(BlogSidebarLoader);
-  return <ul>{posts.map(p => <li key={p.slug}>{p.title}</li>)}</ul>;
+export function StockBadge() {
+  const { data } = useLoader(StockLoader);
+  return <span>{data.inStock ? "In stock" : "Sold out"}</span>;
 }
 ```
 
-### Attaching Loaders to Routes
-
-```tsx
-const urlpatterns = urls(({ path, loader }) => [
-  path("/blog", BlogIndexPage, { name: "blog" }, () => [
-    loader(BlogSidebarLoader),
-  ]),
-]);
-```
+Loaders run in parallel with the handler and stream; `loading()` opts the
+segment into skeleton-then-stream. Without it, document requests arrive
+**ready** — the HTML ships with data in place; the skeleton is a per-segment
+choice, not the first impression.
 
-## Navigation & Links
+The rule of thumb: fetch in the **handler** when the data belongs to the
+rendered page — it will be frozen with the shell if you cache it (step 4).
+Put data in a **loader** when it must outlive the shell: shared with client
+components, fresh on every hit even when the segment is cached, refetchable
+from the client, or revalidated on its own after actions.
 
-### Named Routes with `reverse()` (Server Components)
+## 3. Mutations
 
-In server components, use `reverse()` to generate URLs by route name:
+Users add to cart. A server action is a plain `"use server"` function; the
+form posts to it with standard React 19 hooks — and it works without
+JavaScript:
 
 ```tsx
-import { Link } from "@rangojs/router/client";
-import { reverse } from "./router";
+// src/actions/cart.ts
+"use server";
 
-function BlogIndex() {
-  return (
-    <nav>
-      <Link to={reverse("home")}>Home</Link>
-      <Link to={reverse("blogPost", { slug: "my-post" })}>My Post</Link>
-      <Link to={reverse("about")}>About</Link>
-    </nav>
-  );
+export async function addToCart(productId: string) {
+  await db.cart.insert({ productId });
 }
 ```
 
-`reverse()` is type-safe — route names and required params are checked at compile time. Included routes use dotted names: `reverse("api.health")`.
-
-Handlers also have `ctx.reverse()` directly on the context:
-
-```tsx
-const BlogPostPage: Handler<"blogPost"> = (ctx) => {
-  const backUrl = ctx.reverse("blog");
-  return <Link to={backUrl}>Back to blog</Link>;
-};
-```
-
-### `href()` for Path Validation (Client Components)
-
-In client components, use `href()` for compile-time path validation:
-
-```tsx
-"use client";
-import { Link, href } from "@rangojs/router/client";
-
-function Nav() {
-  return (
-    <nav>
-      <Link to={href("/")}>Home</Link>
-      <Link to={href("/blog")} prefetch="intent">Blog</Link>
-      <Link to={href("/about")}>About</Link>
-    </nav>
-  );
-}
-```
-
-`href()` validates that the path matches a registered route pattern at compile time (e.g. `/blog/my-post` matches `/blog/:slug`).
-
-### Navigation Hook
-
-```tsx
-"use client";
-import { useNavigation } from "@rangojs/router/client";
-
-function SearchForm() {
-  const { navigate, isPending } = useNavigation();
-
-  function handleSubmit(query: string) {
-    navigate(`/search?q=${encodeURIComponent(query)}`);
-  }
-
-  return <form onSubmit={...}>{isPending && <Spinner />}</form>;
-}
-```
-
-### Scroll Restoration
-
 ```tsx
+// src/components/add-to-cart.tsx
 "use client";
-import { ScrollRestoration } from "@rangojs/router/client";
+import { useActionState } from "react";
+import { addToCart } from "../actions/cart";
 
-function Document({ children }) {
+export function AddToCart({ productId }: { productId: string }) {
+  const [, action, pending] = useActionState(() => addToCart(productId), null);
   return (
-    <html>
-      <body>
-        {children}
-        <ScrollRestoration />
-      </body>
-    </html>
+    <form action={action}>
+      <button disabled={pending}>{pending ? "Adding…" : "Add to cart"}</button>
+    </form>
   );
 }
 ```
 
-## Includes (Composable Modules)
-
-Split URL patterns into composable modules with `include()`:
+After an action, route segments and loaders re-render by default so the UI
+reflects the new state. `revalidate()` narrows that to the segments that
+actually own the data — matched by action **reference**, so renames are
+compile errors, not stale predicates:
 
 ```tsx
-// src/api/urls.tsx
-import { urls } from "@rangojs/router";
-
-export const apiPatterns = urls(({ path }) => [
-  path.json("/health", () => ({ status: "ok" }), { name: "health" }),
-  path.json("/products", getProducts, { name: "products" }),
-]);
-
-// src/urls.tsx
-import { urls } from "@rangojs/router";
-import { apiPatterns } from "./api/urls";
+import * as CartActions from "./actions/cart";
 
-export const urlpatterns = urls(({ path, include }) => [
-  path("/", HomePage, { name: "home" }),
-  include("/api", apiPatterns, { name: "api" }),
-  // Mounts apiPatterns under /api: /api/health, /api/products
-]);
-```
-
-Included route names are prefixed with the include name: `reverse("api.health")`, `reverse("api.products")`.
-
-## Middleware
-
-```tsx
-const urlpatterns = urls(({ path, middleware }) => [
-  middleware(async (ctx, next) => {
-    const start = Date.now();
-    const response = await next();
-    console.log(`${ctx.request.method} ${ctx.url.pathname} ${Date.now() - start}ms`);
-    return response;
-  }, () => [
-    path("/dashboard", DashboardPage, { name: "dashboard" }),
+path("/cart", CartPage, { name: "cart" }, () => [
+  loader(CartLoader, () => [
+    revalidate((ctx) => ctx.isAction(CartActions) || undefined),
   ]),
-]);
+]),
 ```
 
-## Caching
+Notice what you didn't write: no API endpoint, no fetch wrapper, and no
+client-cache invalidation call. Actions invalidate the client-side caches
+(history entries, prefetches, HTTP cache key) automatically — a no-op action
+can opt out per invocation with `keepClientCache()`.
+
+## 4. Speed
 
-### Route-Level Caching
+Production traffic. Wrap a segment in `cache()` and the rendered shell —
+including everything the handler fetched — is stored, while every loader on
+it keeps running fresh on each hit. This is where the handler-vs-loader
+choice from step 2 pays off: handler data freezes with the shell, the
+`StockLoader` stays live. Cached shell, live data, one line:
 
 ```tsx
-const urlpatterns = urls(({ path, cache }) => [
-  cache({ ttl: 60, swr: 300 }, () => [
-    path("/blog", BlogIndexPage, { name: "blog" }),
-    path("/blog/:slug", BlogPostPage, { name: "blogPost" }),
+const urlpatterns = urls(({ path, layout, loader, loading, cache }) => [
+  layout(<ShopLayout />, () => [
+    path("/", HomePage, { name: "home" }),
+    cache({ ttl: 600, swr: 3600, tags: ["products"] }, () => [
+      path("/products/:slug", ProductPage, { name: "product" }, () => [
+        loader(StockLoader), // never cached: re-runs on every hit
+        loading(<ProductSkeleton />),
+      ]),
+    ]),
   ]),
 ]);
 ```
 
-### Cache Store Configuration
+Wire a store once on the router (`MemorySegmentCacheStore` for dev,
+`CFCacheStore` for Cloudflare — see the [`/caching` skill](./skills/caching/SKILL.md)),
+and bust by tag from the mutation that changes the data:
 
 ```tsx
-import { createRouter } from "@rangojs/router";
-import { CFCacheStore, createDocumentCacheMiddleware } from "@rangojs/router/cache";
-
-export const router = createRouter({
-  document: Document,
-  cache: (env) => ({
-    store: new CFCacheStore({
-      defaults: { ttl: 60, swr: 300 },
-      ctx: env.ctx,
-    }),
-  }),
-})
-  .use(createDocumentCacheMiddleware())
-  .routes(urlpatterns);
-```
+// src/actions/products.ts
+"use server";
+import { updateTag } from "@rangojs/router";
 
-Available cache stores:
-- `CFCacheStore` — Cloudflare edge cache (production)
-- `MemorySegmentCacheStore` — In-memory cache (development/testing)
-
-## Pre-rendering
-
-Pre-rendering generates route segments at build time. The worker handles all requests — there are no static files served from assets.
-
-### Static Segments
-
-Use `Static()` for segments rendered once at build time (no params). Works on `path()`, `layout()`, and `parallel()`:
-
-```tsx
-import { Static } from "@rangojs/router";
-
-export const AboutPage = Static(async () => {
-  return <article>...</article>;
-});
-
-export const DocsNav = Static(async () => {
-  const items = await readDocsNavItems();
-  return <nav>{items.map(i => <a key={i.slug} href={i.slug}>{i.title}</a>)}</nav>;
-});
+export async function renameProduct(id: string, name: string) {
+  await db.products.rename(id, name);
+  await updateTag("products"); // awaitable, read-your-own-writes
+}
 ```
 
-### Dynamic Routes with Prerender
-
-Use `Prerender()` for route-scoped pre-rendering. With params, provide `getParams` first, handler second:
+Navigation speed is a `Link` prop away:
 
 ```tsx
-import { Prerender } from "@rangojs/router";
-
-export const BlogPost = Prerender(
-  async () => {
-    const slugs = await getAllBlogSlugs();
-    return slugs.map(slug => ({ slug }));
-  },
-  async (ctx) => {
-    const post = await getPost(ctx.params.slug);
-    return <article>{post.content}</article>;
-  },
-);
+<Link to={url} prefetch="viewport">
+  {product.name}
+</Link>
 ```
 
-### Passthrough for Unknown Params
-
-```tsx
-import { Prerender } from "@rangojs/router";
-
-export const ProductPage = Prerender(
-  async () => {
-    const featured = await db.getFeaturedProducts();
-    return featured.map(p => ({ id: p.id }));
-  },
-  async (ctx) => {
-    const product = await db.getProduct(ctx.params.id);
-    return <Product data={product} />;
-  },
-  { passthrough: true },
-);
-```
+A fully-prefetched navigation commits a **finished page** — no skeleton, no
+loading flash — and staying correct is the router's job: every action
+invalidates the prefetch caches by default, so a prefetched page can't show
+pre-mutation data.
 
-With `passthrough: true`, known params are served from the build-time cache and unknown params fall through to live rendering.
+To move the shell's cost to build time entirely, `Prerender()` bakes it while
+loaders stay live at runtime — same mental model, earlier cache write. See
+the [`/prerender` skill](./skills/prerender/SKILL.md).
 
-## Theme
+## 5. An API, when you need one
 
-### Router Configuration
+Response routes live in the same tree — `path.json()`, `path.text()`,
+`path.xml()`, `path.image()`, `path.stream()`:
 
 ```tsx
-export const router = createRouter({
-  document: Document,
-  theme: {
-    defaultTheme: "light",
-    themes: ["light", "dark", "system"],
-    attribute: "class",
-    enableSystem: true,
-  },
-}).routes(urlpatterns);
+path("/products/:slug", ProductPage, { name: "product" }),
+path.json("/products/:slug", (ctx) => db.products.find(ctx.params.slug), {
+  name: "productJson",
+}),
 ```
 
-### Theme Toggle
+Same URL: browsers get the page, API clients get JSON, negotiated by
+`Accept` header in the route trie. Handlers return bare values; errors
+serialize as RFC 9457 `application/problem+json`. The payload type is
+inferred from the handler — no codegen:
 
-```tsx
-"use client";
-import { useTheme } from "@rangojs/router/theme";
-
-function ThemeToggle() {
-  const { theme, setTheme, themes } = useTheme();
-  return (
-    <select value={theme} onChange={e => setTheme(e.target.value)}>
-      {themes.map(t => <option key={t}>{t}</option>)}
-    </select>
-  );
-}
-```
-
-## Host Routing
-
-Route requests to different apps based on domain/subdomain patterns using `@rangojs/router/host`:
-
-```tsx
-// worker.rsc.tsx
-import { createHostRouter } from "@rangojs/router/host";
-
-const hostRouter = createHostRouter();
-
-hostRouter.host(["*.localhost"]).map(() => import("./apps/admin/handler.js"));
-hostRouter.host(["localhost"]).map(() => import("./apps/site/handler.js"));
-hostRouter.fallback().map(() => import("./apps/site/handler.js"));
-
-export default {
-  async fetch(request, env, ctx) {
-    return hostRouter.match(request, { Bindings: env, Variables: {}, ctx });
-  },
-};
-```
-
-Each sub-app has its own `createRouter()` and `urls()`. The host router lazily imports the matched app's handler. Patterns are matched in registration order — register more specific patterns (subdomains) before catch-alls.
-
-## Meta Tags
-
-Accumulate meta tags across route segments using the built-in `Meta` handle:
-
-```tsx
-import { Meta } from "@rangojs/router";
-import type { HandlerContext } from "@rangojs/router";
+```ts
+type Product = RouteResponse<typeof urlpatterns, "productJson">;
+```
+
+See the [`/api-client` skill](./skills/api-client/SKILL.md) for a small typed
+client over these endpoints.
+
+## Everything else, when you need it
+
+That was the core: `path`/`layout`/`include`, names, loaders, actions +
+`revalidate`, `cache`, response routes. The rest is opt-in — reach for it
+when the requirement appears:
+
+| I need to…                                      | Skill                                                                                        |
+| ----------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| guard or shape requests (auth, headers)         | [`/middleware`](./skills/middleware/SKILL.md)                                                |
+| multi-column layouts, independent slots         | [`/parallel`](./skills/parallel/SKILL.md)                                                    |
+| open a route as a modal on soft navigation      | [`/intercept`](./skills/intercept/SKILL.md)                                                  |
+| compose route modules / sub-apps                | [`/route`](./skills/route/SKILL.md), [`/composability`](./skills/composability/SKILL.md)     |
+| cache a single function or component            | [`/use-cache`](./skills/use-cache/SKILL.md), [`/cache-guide`](./skills/cache-guide/SKILL.md) |
+| feed live loaders from a cached shell           | [`/shell-manifest`](./skills/shell-manifest/SKILL.md)                                        |
+| edge caching with Cache-Control                 | [`/document-cache`](./skills/document-cache/SKILL.md)                                        |
+| light/dark mode without FOUC                    | [`/theme`](./skills/theme/SKILL.md)                                                          |
+| analytics / third-party scripts with CSP nonce  | [`/scripts`](./skills/scripts/SKILL.md)                                                      |
+| locale routing                                  | [`/i18n`](./skills/i18n/SKILL.md)                                                            |
+| SSE and WebSockets                              | [`/streams-and-websockets`](./skills/streams-and-websockets/SKILL.md)                        |
+| multi-app routing by domain                     | [`/host-router`](./skills/host-router/SKILL.md)                                              |
+| animate navigations                             | [`/view-transitions`](./skills/view-transitions/SKILL.md)                                    |
+| test loaders, middleware, handlers, Flight      | [`/testing`](./skills/testing/SKILL.md)                                                      |
+| see where request time goes                     | [`/observability`](./skills/observability/SKILL.md)                                          |
+| deploy to Vercel (cache store, tracing, output) | [`/vercel`](./skills/vercel/SKILL.md)                                                        |
+| compare Rango with Next.js / TanStack / Waku    | [`/comparison`](./skills/comparison/SKILL.md)                                                |
+
+The [`/rango` skill](./skills/rango/SKILL.md) is the full catalog and the
+mental model that ties it together.
+
+## Reference
+
+### Imports and subpaths
+
+| Export                    | Description                                                                                                                    |
+| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `@rangojs/router`         | Server/RSC core and shared types: `createRouter`, `urls`, `createLoader`, `Handler`, `Prerender`, `Meta`                       |
+| `@rangojs/router/client`  | Client: `Link`, `Outlet`, `href`, `useNavigation`, `useLoader`, `MetaTags`                                                     |
+| `@rangojs/router/cache`   | Cache: `CFCacheStore`, `VercelCacheStore`, `MemorySegmentCacheStore`, `createDocumentCacheMiddleware`                          |
+| `@rangojs/router/theme`   | Theme: `useTheme`, `ThemeProvider`, `ThemeScript`                                                                              |
+| `@rangojs/router/host`    | Host routing: `createHostRouter`, `defineHosts`, `isNoRouteMatchError`                                                         |
+| `@rangojs/router/vercel`  | Vercel: `createVercelTracing` (phase spans via `@vercel/otel`'s global tracer)                                                 |
+| `@rangojs/router/vite`    | Vite plugin: `rango()`                                                                                                         |
+| `@rangojs/router/testing` | Consumer testing primitives: `runLoader`, `runMiddleware`, `dispatch` (plus `/testing/dom`, `/testing/flight`, `/testing/e2e`) |
+| `@rangojs/router/rsc`     | Advanced server pipeline APIs: `createRSCHandler`, request-context access                                                      |
+| `@rangojs/router/ssr`     | Advanced SSR bridge APIs: `createSSRHandler`                                                                                   |
+
+Use only subpaths that are explicitly exported; avoid deep imports.
+
+The root entry is conditionally resolved: server-only APIs (`createRouter`,
+`urls`, `redirect`, `Prerender`, `cookies`) run under the `react-server`
+condition and throw guidance errors elsewhere. If you hit a root-entrypoint
+stub error: hooks and components (`Link`, `Outlet`, `useLoader`, `MetaTags`)
+live in `@rangojs/router/client`; cache APIs in `@rangojs/router/cache`;
+host APIs in `@rangojs/router/host`.
+
+### Type safety
+
+The Vite plugin generates `router.named-routes.gen.ts` automatically (on dev
+startup, HMR, and builds), registering route names, params, and search
+schemas globally via `Rango.GeneratedRouteMap`. That powers `Handler<"name">`,
+`ctx.reverse()`, and `RouteParams<"name">` with no manual registration.
+
+For response-aware and path-based utilities (`href()`, `Rango.Path`,
+`RouteResponse`), augment `Rango.RegisteredRoutes` once:
 
-export function BlogPostPage(ctx: HandlerContext) {
-  const meta = ctx.use(Meta);
-  meta({ title: "My Blog Post" });
-  meta({ name: "description", content: "A great blog post" });
-  meta({ property: "og:title", content: "My Blog Post" });
+```ts
+// router.tsx
+const router = createRouter<AppBindings>({}).routes(urlpatterns);
 
-  return <article>...</article>;
+declare global {
+  namespace Rango {
+    interface Env extends AppEnv {}
+    interface RegisteredRoutes extends typeof router.routeMap {}
+  }
 }
 ```
 
-Render collected tags in the document with `<MetaTags />` from `@rangojs/router/client`.
+See the [`/typesafety` skill](./skills/typesafety/SKILL.md) for the full
+surface breakdown.
 
-## CLI: `rango generate`
+### CLI
 
-Route types are generated automatically by the Vite plugin. The CLI is a manual fallback for generating types outside the dev server (e.g. in CI or for IDE support before first `pnpm dev`):
+Route types are generated by the Vite plugin; the CLI is the manual fallback
+for CI or pre-first-run IDE support:
 
 ```bash
-npx rango generate src/router.tsx
-npx rango generate src/                # recursive scan
-npx rango generate src/urls.tsx src/api/  # mix files and directories
+npx rango generate src/router.tsx   # global named-route map
+npx rango generate src/             # recursive scan
 ```
 
-Auto-detects file type:
-- Files with `createRouter` → `*.named-routes.gen.ts` with global route map
-- Files with `urls()` → `*.gen.ts` with per-module route names, params, and search types
-
-## Type Safety
-
-The Vite plugin automatically generates a `router.named-routes.gen.ts` file that globally registers all route names, patterns, and search schemas. Type-safe `reverse()`, `Handler<"name">`, `href()`, and `RouteParams<"name">` work out of the box — no manual type registration needed. The gen file is updated on dev server startup, HMR, and production builds.
-
-## Subpath Exports
-
-| Export | Description |
-|--------|-------------|
-| `@rangojs/router` | Core: `createRouter`, `urls`, `createLoader`, `Handler`, `Prerender`, `Meta` |
-| `@rangojs/router/client` | Client: `Link`, `Outlet`, `href`, `useNavigation`, `useLoader`, `MetaTags` |
-| `@rangojs/router/cache` | Cache: `CFCacheStore`, `MemorySegmentCacheStore`, `createDocumentCacheMiddleware` |
-| `@rangojs/router/theme` | Theme: `useTheme`, `ThemeProvider`, `ThemeScript` |
-| `@rangojs/router/host` | Host routing: `createHostRouter`, `defineHosts` |
-| `@rangojs/router/vite` | Vite plugin: `rango()` |
-| `@rangojs/router/server` | Server utilities |
-| `@rangojs/router/build` | Build utilities |
+### Examples
 
-## Examples
+- [`e2e/mini`](https://github.com/ivogt/vite-rsc/tree/main/packages/rangojs-router/e2e/mini) — single-file demo app
+- [`cloudflare-basic`](https://github.com/ivogt/vite-rsc/tree/main/tests/cloudflare-basic) — Cloudflare Workers with caching, loaders, theme, and pre-rendering
+- [`cloudflare-multi-router`](https://github.com/ivogt/vite-rsc/tree/main/examples/cloudflare-multi-router) — multi-app host routing
+- [`vercel-basic`](https://github.com/ivogt/vite-rsc/tree/main/examples/vercel-basic) — Vercel deployment with `preset: "vercel"`, `VercelCacheStore`, and OTel tracing
+- [`vercel-multi-router`](https://github.com/ivogt/vite-rsc/tree/main/examples/vercel-multi-router) — multi-app host routing on Vercel (single function, routed by Host header)
 
-See the `examples/` directory for full working applications:
+### Going deeper
 
-- [`cloudflare-basic`](../../examples/cloudflare-basic) — Cloudflare Workers with caching, loaders, theme, and pre-rendering
-- [`cloudflare-multi-router`](../../examples/cloudflare-multi-router) — Multi-app host routing
+- [Why Rango](https://github.com/ivogt/vite-rsc/blob/main/packages/rangojs-router/docs/why-rango.md) — the design rationale, claim by claim
+- [Framework comparison](./skills/comparison/references/framework-comparison.md) — Rango vs Next.js App Router, TanStack Start, and Waku, capability by capability
+- [Docs index](https://github.com/ivogt/vite-rsc/blob/main/packages/rangojs-router/docs/README.md) — architecture, caching, prerender, testing
+- [Execution model](https://github.com/ivogt/vite-rsc/blob/main/packages/rangojs-router/docs/internal/execution-model.md) — the runtime contract
 
 ## License