@rangojs/router 0.0.0-experimental.10

package/skills/loader/SKILL.md

@@ -0,0 +1,246 @@
+---
+name: loader
+description: Define data loaders for fetching data in routes with createLoader
+argument-hint: [name]
+---
+
+# Data Loaders with loader()
+
+Loaders fetch data on the server and stream it to the client.
+
+## Creating a Loader
+
+```typescript
+import { createLoader } from "@rangojs/router";
+
+export const ProductLoader = createLoader("product", async (ctx) => {
+  const product = await ctx.env.Bindings.DB
+    .prepare("SELECT * FROM products WHERE slug = ?")
+    .bind(ctx.params.slug)
+    .first();
+
+  return { product };
+});
+```
+
+## Using Loaders in Routes
+
+```typescript
+import { urls } from "@rangojs/router";
+import { ProductLoader } from "./loaders/product";
+
+export const urlpatterns = urls(({ path, loader }) => [
+  path("/product/:slug", ProductPage, { name: "product" }, () => [
+    loader(ProductLoader),
+  ]),
+]);
+```
+
+## Consuming Loader Data
+
+### In Server Components
+
+```typescript
+import { useLoader } from "@rangojs/router";
+import { ProductLoader } from "./loaders/product";
+
+async function ProductPage() {
+  const { product } = await useLoader(ProductLoader);
+  return <h1>{product.name}</h1>;
+}
+```
+
+### In Client Components
+
+```typescript
+"use client";
+import { useLoaderData } from "@rangojs/router/client";
+import { ProductLoader } from "./loaders/product";
+
+function ProductDetails() {
+  const { product } = useLoaderData(ProductLoader);
+  return <div>{product.description}</div>;
+}
+```
+
+## Loader Context
+
+Loaders receive the same context as route handlers:
+
+```typescript
+export const ProductLoader = createLoader("product", async (ctx) => {
+  // URL params
+  const { slug } = ctx.params;
+
+  // Query params
+  const variant = ctx.url.searchParams.get("variant");
+
+  // Environment (DB, KV, etc.)
+  const db = ctx.env.Bindings.DB;
+
+  // Request headers
+  const auth = ctx.request.headers.get("Authorization");
+
+  // Variables set by middleware
+  const user = ctx.env.Variables.user;
+
+  return { product: await fetchProduct(slug) };
+});
+```
+
+## Loader with Children
+
+Add caching or revalidation to specific loaders:
+
+```typescript
+path("/product/:slug", ProductPage, { name: "product" }, () => [
+  // Cached loader
+  loader(ProductLoader, () => [
+    cache({ ttl: 300 }),
+  ]),
+
+  // Loader with revalidation control
+  loader(RelatedProductsLoader, () => [
+    revalidate(() => false),  // Never revalidate
+  ]),
+
+  // Loader that revalidates after cart actions
+  loader(CartLoader, () => [
+    revalidate(({ actionId }) => actionId?.includes("Cart") ?? false),
+  ]),
+])
+```
+
+## Multiple Loaders
+
+Routes can have multiple loaders that run in parallel:
+
+```typescript
+path("/product/:slug", ProductPage, { name: "product" }, () => [
+  loader(ProductLoader),
+  loader(RelatedProductsLoader),
+  loader(ReviewsLoader),
+])
+```
+
+## Layout Loaders
+
+Loaders on layouts are shared by all child routes:
+
+```typescript
+layout(<ShopLayout />, () => [
+  // These loaders are available to all shop routes
+  loader(CartLoader),
+  loader(CategoriesLoader),
+
+  path("/shop", ShopIndex, { name: "index" }),
+  path("/shop/product/:slug", ProductPage, { name: "product" }),
+])
+```
+
+## Passing Loaders as Props
+
+Loaders can be passed as props from server to client components. RSC serialization
+uses `toJSON()` to send only `{ __brand, $$id }` — the loader function is stripped.
+
+```typescript
+// Server component (route handler)
+import { SlowLoader } from "../loaders";
+
+path("/dashboard", () => <DashboardContent loader={SlowLoader} />, { name: "dashboard" }, () => [
+  loader(SlowLoader),
+  loading(<DashboardSkeleton />),
+])
+
+// Client component — use typeof for type-safe props
+"use client";
+import { useLoader } from "@rangojs/router/client";
+import type { SlowLoader } from "../loaders";
+
+function DashboardContent({ loader }: { loader: typeof SlowLoader }) {
+  const { data } = useLoader(loader);
+  return <div>{data.message}</div>;
+}
+```
+
+Use `typeof MyLoader` for the prop type — it infers the full generic automatically.
+
+## Streaming with Suspense
+
+Loaders stream data. Use Suspense for loading states:
+
+```typescript
+// In route definition
+path("/product/:slug", ProductPage, { name: "product" }, () => [
+  loader(ProductLoader),
+  loading(<ProductSkeleton />),  // Shows while loader streams
+])
+
+// Or in component
+function ProductPage() {
+  return (
+    <Suspense fallback={<ProductSkeleton />}>
+      <ProductDetails />
+    </Suspense>
+  );
+}
+```
+
+## Complete Example
+
+```typescript
+// loaders/shop.ts
+import { createLoader } from "@rangojs/router";
+
+export const ProductLoader = createLoader("product", async (ctx) => {
+  const product = await ctx.env.Bindings.DB
+    .prepare("SELECT * FROM products WHERE slug = ?")
+    .bind(ctx.params.slug)
+    .first();
+
+  if (!product) {
+    throw new Response("Product not found", { status: 404 });
+  }
+
+  return { product };
+});
+
+export const CartLoader = createLoader("cart", async (ctx) => {
+  const user = ctx.env.Variables.user;
+  if (!user) return { cart: null };
+
+  const cart = await ctx.env.Bindings.KV.get(`cart:${user.id}`, "json");
+  return { cart };
+});
+
+// urls.tsx
+export const urlpatterns = urls(({ path, layout, loader, loading, cache, revalidate }) => [
+  layout(<ShopLayout />, () => [
+    // Shared cart loader for all shop routes
+    loader(CartLoader, () => [
+      revalidate(({ actionId }) => actionId?.includes("Cart") ?? false),
+    ]),
+
+    path("/shop/product/:slug", ProductPage, { name: "product" }, () => [
+      loader(ProductLoader, () => [cache({ ttl: 60 })]),
+      loading(<ProductSkeleton />),
+    ]),
+  ]),
+]);
+
+// pages/product.tsx
+import { useLoader } from "@rangojs/router";
+import { ProductLoader, CartLoader } from "./loaders/shop";
+
+async function ProductPage() {
+  const { product } = await useLoader(ProductLoader);
+  const { cart } = await useLoader(CartLoader);
+
+  return (
+    <div>
+      <h1>{product.name}</h1>
+      <AddToCartButton productId={product.id} inCart={cart?.items.includes(product.id)} />
+    </div>
+  );
+}
+```

package/skills/middleware/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: middleware
+description: Define middleware for authentication, logging, and request processing in @rangojs/router
+argument-hint: [middleware-name]
+---
+
+# Middleware
+
+Middleware runs before/after route handlers using the onion model.
+
+## Basic Middleware
+
+```typescript
+import { createMiddleware } from "@rangojs/router";
+
+export const authMiddleware = createMiddleware(async (ctx, next) => {
+  const token = ctx.request.headers.get("Authorization");
+
+  if (!token) {
+    throw new Response("Unauthorized", { status: 401 });
+  }
+
+  const user = await verifyToken(token);
+  ctx.env.Variables.user = user;
+
+  await next();
+});
+```
+
+## Using Middleware in Routes
+
+```typescript
+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
+  middleware(loggerMiddleware),
+
+  // Layout with scoped middleware
+  layout(<AdminLayout />, () => [
+    middleware(authMiddleware),  // Only for admin routes
+
+    path("/admin", AdminDashboard, { name: "admin.index" }),
+    path("/admin/users", AdminUsers, { name: "admin.users" }),
+  ]),
+
+  // Public routes (no auth middleware)
+  path("/", HomePage, { name: "home" }),
+  path("/about", AboutPage, { name: "about" }),
+]);
+```
+
+## Middleware with Multiple Handlers
+
+```typescript
+// Spread multiple middleware from a single export
+export const shopMiddleware = [loggerMiddleware, mockAuthMiddleware];
+
+// In routes
+layout(<ShopLayout />, () => [
+  middleware(...shopMiddleware),
+
+  path("/shop", ShopIndex, { name: "shop" }),
+])
+```
+
+## Middleware Context
+
+```typescript
+export const myMiddleware = createMiddleware(async (ctx, next) => {
+  // Access request
+  ctx.request;              // Request object
+  ctx.url;                  // Parsed URL
+  ctx.params;               // Route parameters
+
+  // Access environment
+  ctx.env.Bindings.DB;      // Cloudflare bindings
+  ctx.env.Variables;        // Mutable variables
+
+  // Set variables for downstream handlers
+  ctx.env.Variables.user = { id: "123", name: "John" };
+
+  // Continue to next middleware/handler
+  await next();
+
+  // After handler (response intercepting)
+  console.log("Handler completed");
+});
+```
+
+## Authentication Middleware
+
+```typescript
+export const requireAuthMiddleware = createMiddleware(async (ctx, next) => {
+  const user = ctx.env.Variables.user;
+
+  if (!user) {
+    throw new Response("Unauthorized", { status: 401 });
+  }
+
+  await next();
+});
+
+export const permissionsMiddleware = createMiddleware(async (ctx, next) => {
+  const user = ctx.env.Variables.user;
+  const requiredPermission = "admin";
+
+  if (!user?.permissions?.includes(requiredPermission)) {
+    throw new Response("Forbidden", { status: 403 });
+  }
+
+  await next();
+});
+```
+
+## Logger Middleware
+
+```typescript
+export const loggerMiddleware = createMiddleware(async (ctx, next) => {
+  const start = Date.now();
+
+  console.log(`[${ctx.request.method}] ${ctx.url.pathname}`);
+
+  await next();
+
+  const duration = Date.now() - start;
+  console.log(`[${ctx.request.method}] ${ctx.url.pathname} - ${duration}ms`);
+});
+```
+
+## Rate Limiting Middleware
+
+```typescript
+export const rateLimitMiddleware = createMiddleware(async (ctx, next) => {
+  const ip = ctx.request.headers.get("CF-Connecting-IP") ?? "unknown";
+  const key = `rate-limit:${ip}`;
+
+  const count = await ctx.env.Bindings.KV.get(key);
+  const requests = count ? parseInt(count) : 0;
+
+  if (requests > 100) {
+    throw new Response("Too Many Requests", { status: 429 });
+  }
+
+  await ctx.env.Bindings.KV.put(key, String(requests + 1), {
+    expirationTtl: 60,
+  });
+
+  await next();
+});
+```
+
+## Complete Example
+
+```typescript
+// middleware/index.ts
+import { createMiddleware } from "@rangojs/router";
+
+export const loggerMiddleware = createMiddleware(async (ctx, next) => {
+  console.log(`[${ctx.request.method}] ${ctx.url.pathname}`);
+  await next();
+});
+
+export const mockAuthMiddleware = createMiddleware(async (ctx, next) => {
+  // Mock user for development
+  ctx.env.Variables.user = { id: "1", name: "Demo User" };
+  await next();
+});
+
+export const requireAuthMiddleware = createMiddleware(async (ctx, next) => {
+  if (!ctx.env.Variables.user) {
+    throw new Response("Unauthorized", { status: 401 });
+  }
+  await next();
+});
+
+// urls.tsx
+import { urls } from "@rangojs/router";
+import {
+  loggerMiddleware,
+  mockAuthMiddleware,
+  requireAuthMiddleware,
+} from "./middleware";
+
+export const urlpatterns = urls(({ path, layout, middleware }) => [
+  // Global middleware
+  middleware(loggerMiddleware),
+  middleware(mockAuthMiddleware),
+
+  // Public routes
+  path("/", HomePage, { name: "home" }),
+
+  // Protected routes
+  layout(<AccountLayout />, () => [
+    middleware(requireAuthMiddleware),
+
+    path("/account", AccountPage, { name: "account" }),
+    path("/account/settings", SettingsPage, { name: "settings" }),
+  ]),
+]);
+```

package/skills/mime-routes/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: mime-routes
+description: Content negotiation — serve different response types (RSC, JSON, text, XML) from the same URL based on Accept header
+argument-hint: [negotiate|vary|accept]
+---
+
+# Content Negotiation (MIME Routes)
+
+Content negotiation lets you register multiple response types on the same URL pattern.
+The router inspects the `Accept` header and dispatches to the matching handler.
+All negotiated responses include `Vary: Accept` for correct CDN/cache behavior.
+
+See also: `/response-routes` for the base response route API (path.json, path.text, etc.).
+
+## Defining Negotiated Routes
+
+Declare the same URL pattern with both an RSC route and one or more response-type routes.
+Order within the `urls()` array does not matter — the trie merges them at build time.
+
+```typescript
+import { urls } from "@rangojs/router/server";
+
+export const urlpatterns = urls(({ path, layout, include }) => [
+  // RSC page + JSON API on the same URL
+  path("/products/:id", ProductPage, { name: "product" }),
+  path.json("/products/:id", (ctx) => {
+    return db.getProduct(ctx.params.id);
+  }, { name: "productJson" }),
+]);
+```
+
+When a browser requests `/products/42` (`Accept: text/html`), the RSC page renders.
+When an API client requests the same URL (`Accept: application/json`), the JSON handler runs.
+
+## Negotiation Rules
+
+1. **Q-value priority** — higher `q` wins (`Accept: application/json;q=0.9, text/html;q=1.0` serves RSC)
+2. **Client order tiebreaker** — when q-values are equal, the type listed first in Accept wins (matches Express/Hono behavior)
+3. **Specific MIME match** — the variant whose MIME type appears in Accept wins
+4. **Wildcard / empty Accept** — `*/*` and missing Accept fall back to route definition order (the first-defined variant wins)
+5. **All responses** on a negotiated URL get `Vary: Accept` header, including the RSC side
+
+RSC participates as a `text/html` candidate alongside response-type variants.
+There is no special short-circuit — RSC follows the same negotiation rules as other types.
+
+The MIME mapping used for matching:
+
+| Tag | MIME type |
+|-----|-----------|
+| RSC (plain `path()`) | `text/html` (negotiation) / `text/x-component` (wire format) |
+| `json` | `application/json` |
+| `text` | `text/plain` |
+| `xml` | `application/xml` |
+| `html` | `text/html` |
+| `md` | `text/markdown` |
+
+RSC routes negotiate as `text/html` but respond with `text/x-component` (the RSC wire format).
+The browser's RSC runtime decodes this transparently — clients requesting `text/html` get
+the RSC page rendered normally.
+
+Tags `image`, `stream`, and `any` are pass-through and do not participate in Accept matching.
+
+## Multiple Response Types
+
+A single URL can have an RSC route plus multiple response-type variants:
+
+```typescript
+export const urlpatterns = urls(({ path }) => [
+  path("/data", DataPage, { name: "data" }),
+  path.json("/data", () => ({ format: "json" }), { name: "dataJson" }),
+  path.text("/data", () => "plain text", { name: "dataText" }),
+  path.xml("/data", () => "<root>xml</root>", { name: "dataXml" }),
+]);
+```
+
+- `Accept: text/html` — RSC page
+- `Accept: application/json` — JSON handler
+- `Accept: text/plain` — text handler
+- `Accept: application/xml` — XML handler
+- `Accept: */*` — first variant (JSON, since it was registered first)
+
+## Wildcard Routes
+
+Content negotiation works with wildcard `/*` patterns:
+
+```typescript
+path("/files/*", FileBrowserPage, { name: "files" }),
+path.json("/files/*", (ctx) => {
+  const filePath = ctx.params["*"];
+  return { entries: listDir(filePath) };
+}, { name: "filesJson" }),
+```
+
+## Response-Only Negotiation (No RSC Primary)
+
+Two or more response-type routes can share a URL without an RSC route.
+The last registered route becomes the primary; earlier ones become variants:
+
+```typescript
+path.json("/api/data", () => ({ format: "json" }), { name: "dataJson" }),
+path.text("/api/data", () => "plain text version", { name: "dataText" }),
+```
+
+Without an RSC primary, there is no `text/html` candidate — the Accept header
+picks among the response-type candidates directly.
+
+## How It Works
+
+1. **Build time**: `buildRouteTrie()` calls `mergeLeaves()` when multiple routes share a pattern.
+   RSC routes become the primary trie leaf; response-type routes are stored in the `nv`
+   (negotiate variants) array on the leaf. The `rf` (rsc-first) flag tracks definition order.
+2. **Runtime**: `previewRoute()` reads `negotiateVariants` from the trie match result.
+   It parses the `Accept` header (extracting q-values and order), builds a candidate list
+   (RSC as `text/html` + response-type variants), and calls `pickNegotiateVariant()`.
+3. **Candidate matching**: walks the client's sorted Accept list (by q desc, then order asc),
+   matching each entry against candidates. Wildcards (`*/*`, `text/*`) fall back to definition order.
+4. **Vary header**: both the response-route handler wrapper and the RSC handler wrapper
+   append `Vary: Accept` when the `negotiated` flag is set on the preview result.
+
+## Caching Considerations
+
+`Vary: Accept` is set automatically on all negotiated responses. This tells CDNs and
+HTTP caches to store separate entries per Accept header value. No additional cache
+configuration is needed for negotiated routes — the framework handles it.