@rangojs/router 0.0.0-experimental.2

package/skills/route/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: route
+description: Define basic routes and route handlers in rsc-router
+argument-hint: [route-name]
+---
+
+# Basic Route Definition
+
+## Route Definition (routes.ts)
+
+Define type-safe routes using the `route()` function:
+
+```typescript
+import { route } from "rsc-router";
+
+export const routes = route({
+  index: "/",
+  about: "/about",
+  // Dynamic params
+  product: "/products/:id",
+  // Nested routes
+  blog: {
+    index: "/blog",
+    post: "/blog/:slug",
+    category: "/blog/category/:category",
+  },
+  // Optional params
+  search: "/search/:query?",
+  // Constrained params
+  locale: "/:locale(en|de|fr)",
+});
+```
+
+### Parameter Types
+
+| Pattern | Example | Description |
+|---------|---------|-------------|
+| `:id` | `/products/:id` | Required parameter |
+| `:page?` | `/list/:page?` | Optional parameter |
+| `:locale(en\|de)` | `/:locale(en\|de)` | Constrained values |
+| `:lang(en\|de)?` | `/:lang(en\|de)?` | Optional + constrained |
+
+## Route Handler (handlers/*.tsx)
+
+Use the `map()` function to define handlers:
+
+```typescript
+import { map } from "rsc-router/server";
+import type { routes } from "../routes.js";
+
+export default map<typeof routes>(({ route, loader, loading, revalidate }) => [
+  // Simple route
+  route("index", () => <HomePage />),
+
+  // Route with params
+  route("product", (ctx) => {
+    return <ProductPage id={ctx.params.id} />;
+  }),
+
+  // Route with loader
+  route("blog.post", async (ctx) => {
+    const post = await ctx.use(PostLoader);
+    return <BlogPost post={post} />;
+  }, () => [
+    loader(PostLoader),
+    loading(<PostSkeleton />),
+  ]),
+]);
+```
+
+## Handler Context
+
+The `ctx` object provides:
+
+```typescript
+route("product", (ctx) => {
+  ctx.params        // Type-safe route parameters { id: string }
+  ctx.query         // Query string parameters
+  ctx.url           // Full URL object
+  ctx.pathname      // Current pathname
+  ctx.method        // HTTP method (GET, POST, etc.)
+  ctx.request       // Raw Request object
+
+  // Data fetching
+  const data = await ctx.use(MyLoader);
+
+  // Handle accumulation
+  const push = ctx.use(BreadcrumbHandle);
+  push({ label: "Product", href: ctx.pathname });
+
+  // Context variables (set by middleware)
+  const user = ctx.get("user");
+
+  return <ProductPage />;
+});
+```
+
+## Router Registration (router.tsx)
+
+Register routes with the router:
+
+```typescript
+import { createRSCRouter } from "rsc-router/server";
+import { routes } from "./routes.js";
+
+const router = createRSCRouter<AppEnv>({
+  document: RootLayout,
+})
+  .routes("/", routes)
+  .map(() => import("./handlers/main.js"));
+
+export default router;
+```
+
+## Type-Safe Links
+
+Use the generated `href` function:
+
+```typescript
+import { href } from "./router.js";
+
+// Type-safe href generation
+<Link href={href("product", { id: "123" })} />
+<Link href={href("blog.post", { slug: "hello-world" })} />
+
+// With query params
+<Link href={href("search", { query: "test" }, { page: "2" })} />
+```
+
+## Route Configuration Options
+
+```typescript
+route("product", ProductHandler, () => [
+  loader(ProductLoader),           // Attach data loader
+  loading(<Skeleton />),           // Loading UI
+  revalidate(revalidateFn),        // Cache control
+  errorBoundary(<ErrorFallback />), // Error handling
+  notFoundBoundary(<NotFound />),   // 404 handling
+  parallel({ "@sidebar": Sidebar }), // Parallel slots
+])
+```

package/skills/router-setup/SKILL.md

@@ -0,0 +1,403 @@
+---
+name: router-setup
+description: Create and configure the RSC router with createRSCRouter
+argument-hint: [option]
+---
+
+# Router Setup with createRSCRouter
+
+## Basic Router Creation
+
+```typescript
+import { createRSCRouter } from "rsc-router/server";
+import { Document } from "./document";
+
+const router = createRSCRouter({
+  document: Document,
+});
+
+export default router;
+```
+
+## Router Options
+
+```typescript
+interface RSCRouterOptions<TEnv> {
+  // Document component wrapping entire app
+  document?: ComponentType<{ children: ReactNode }>;
+
+  // Enable performance metrics (console + Server-Timing header)
+  debugPerformance?: boolean;
+
+  // Default error boundary fallback
+  defaultErrorBoundary?: ReactNode | ErrorBoundaryHandler;
+
+  // Default not-found boundary (for notFound() calls)
+  defaultNotFoundBoundary?: ReactNode | NotFoundBoundaryHandler;
+
+  // Component for routes with no match (404)
+  notFound?: ReactNode | ((props: { pathname: string }) => ReactNode);
+
+  // Error logging callback
+  onError?: OnErrorCallback<TEnv>;
+
+  // Cache configuration
+  cache?:
+    | { store: SegmentCacheStore; enabled?: boolean }
+    | ((env: TEnv) => { store: SegmentCacheStore; enabled?: boolean });
+}
+```
+
+## Full Configuration Example
+
+```typescript
+import { createRSCRouter } from "rsc-router/server";
+import { createMemorySegmentStore } from "rsc-router/cache";
+import { Document } from "./document";
+
+const cacheStore = createMemorySegmentStore();
+
+const router = createRSCRouter<AppEnv>({
+  document: Document,
+  debugPerformance: process.env.NODE_ENV === "development",
+
+  cache: {
+    store: cacheStore,
+    enabled: true,
+  },
+
+  defaultErrorBoundary: ({ error, reset }) => (
+    <div className="error">
+      <h2>Something went wrong</h2>
+      <p>{error.message}</p>
+      <button onClick={reset}>Try again</button>
+    </div>
+  ),
+
+  defaultNotFoundBoundary: ({ notFound }) => (
+    <div className="not-found">
+      <h2>Not Found</h2>
+      <p>{notFound.message}</p>
+    </div>
+  ),
+
+  notFound: ({ pathname }) => (
+    <div className="404">
+      <h1>404</h1>
+      <p>Page not found: {pathname}</p>
+    </div>
+  ),
+
+  onError: (error, ctx) => {
+    console.error("Router error:", error);
+    // Send to error tracking service
+  },
+});
+```
+
+## Environment Types
+
+Define your app's environment type:
+
+```typescript
+import type { RouterEnv } from "rsc-router/server";
+
+interface AppBindings {
+  DB: D1Database;
+  KV: KVNamespace;
+  RATE_LIMITER: RateLimiter;
+}
+
+interface AppVariables {
+  user?: { id: string; name: string };
+  permissions?: string[];
+}
+
+type AppEnv = RouterEnv<AppBindings, AppVariables>;
+
+const router = createRSCRouter<AppEnv>({
+  document: Document,
+});
+```
+
+## Registering Routes
+
+### routes() - Register route definitions
+
+```typescript
+import { homeRoutes } from "./routes/home";
+import { shopRoutes } from "./routes/shop";
+import { adminRoutes } from "./routes/admin";
+
+const router = createRSCRouter<AppEnv>({ document: Document })
+  // Without prefix
+  .routes(homeRoutes)
+  .map(() => import("./handlers/home"))
+
+  // With prefix
+  .routes("/shop", shopRoutes)
+  .map(() => import("./handlers/shop"))
+
+  .routes("/admin", adminRoutes)
+  .map(() => import("./handlers/admin"));
+```
+
+### map() - Register handlers
+
+```typescript
+// Async import (code splitting)
+.routes(shopRoutes)
+.map(() => import("./handlers/shop"))
+
+// Inline definition (no separate handler file)
+.routes({ index: "/", about: "/about" })
+.map(({ route }) => [
+  route("index", () => <HomePage />),
+  route("about", () => <AboutPage />),
+])
+
+// With the map helper function
+import { map } from "rsc-router/server";
+
+// handlers/shop.ts
+export default map<typeof shopRoutes>(({ route, layout, loader }) => [
+  layout(<ShopLayout />, () => [
+    route("index", ShopIndex),
+    route("products", ProductList),
+  ]),
+]);
+```
+
+## Global Middleware
+
+### use() - Add middleware
+
+```typescript
+const router = createRSCRouter<AppEnv>({ document: Document })
+  // Global middleware (all routes)
+  .use(loggerMiddleware)
+  .use(corsMiddleware)
+
+  // Pattern-based middleware
+  .use("/api/*", rateLimiter)
+  .use("/admin/*", adminAuthMiddleware)
+
+  // Routes with scoped middleware
+  .routes("/shop", shopRoutes)
+  .use(shopMiddleware)  // Only applies to shop routes
+  .map(() => import("./handlers/shop"));
+```
+
+### Middleware patterns
+
+```typescript
+"/admin/*"           // All paths under /admin
+"/api/*/protected"   // Wildcard in middle
+"/checkout.*"        // Routes starting with /checkout
+```
+
+## Type-Safe Links with href()
+
+```typescript
+// routes/shop.ts - use dot notation for namespaced keys
+export const shopRoutes = route({
+  "shop.index": "/",
+  "shop.products": "/products",
+  "shop.product": "/products/:slug",
+  "shop.cart": "/cart",
+});
+
+// router.tsx
+const router = createRSCRouter<AppEnv>({ document: Document })
+  .routes(homeRoutes)
+  .map(() => import("./handlers/home"))
+  .routes("/shop", shopRoutes)  // Keys stay unchanged, only URLs get prefixed
+  .map(() => import("./handlers/shop"));
+
+// Export for use in components
+export const href = router.href;
+
+// Usage with full autocomplete
+href("index");                                 // "/"
+href("about");                                 // "/about"
+href("shop.products");                         // "/shop/products"
+href("shop.product", { slug: "widget" });      // "/shop/products/widget"
+
+// In components
+import { href } from "./router";
+<Link to={href("shop.cart")}>Cart</Link>
+```
+
+**Note**: Route keys stay unchanged when mounted with a prefix. Only URL patterns get the prefix applied. Use dot notation (e.g., `shop.products`) for namespaced keys.
+
+## Route Type Registration
+
+For global type inference:
+
+```typescript
+// router.ts
+const _router = createRSCRouter<AppEnv>({ document: Document })
+  .routes(homeRoutes)
+  .map(() => import("./handlers/home"))
+  .routes("/shop", shopRoutes)
+  .map(() => import("./handlers/shop"));
+
+// Extract route types
+type AppRoutes = typeof _router.routeMap;
+
+// Augment global types
+declare global {
+  namespace RSCRouter {
+    interface RegisteredRoutes extends AppRoutes {}
+    interface Env extends AppEnv {}
+  }
+}
+
+export default _router;
+export const href = _router.href;
+```
+
+Now handlers have type-safe context without imports.
+
+## Cache Configuration
+
+### Static cache
+
+```typescript
+import { createMemorySegmentStore } from "rsc-router/cache";
+
+const cacheStore = createMemorySegmentStore();
+
+const router = createRSCRouter<AppEnv>({
+  document: Document,
+  cache: {
+    store: cacheStore,
+    enabled: true,
+  },
+});
+```
+
+### Dynamic cache (per-environment)
+
+```typescript
+const router = createRSCRouter<AppEnv>({
+  document: Document,
+  cache: (env) => ({
+    store: env.Bindings.CACHE_KV,
+    enabled: env.Bindings.CACHE_ENABLED === "true",
+  }),
+});
+```
+
+### Cloudflare KV cache
+
+```typescript
+import { createCFKVSegmentStore } from "rsc-router/cache/cf";
+
+const router = createRSCRouter<AppEnv>({
+  document: Document,
+  cache: (env) => ({
+    store: createCFKVSegmentStore(env.Bindings.CACHE_KV),
+    enabled: true,
+  }),
+});
+```
+
+## Document Component
+
+The document wraps the entire app and persists during errors:
+
+```typescript
+// document.tsx
+"use client";
+
+export function Document({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <head>
+        <meta charSet="utf-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1" />
+        <title>My App</title>
+      </head>
+      <body>
+        {children}
+      </body>
+    </html>
+  );
+}
+```
+
+## Router Methods
+
+### match() - Full render
+
+```typescript
+const result = await router.match(request, env);
+// Returns full render tree with segments, loaders, metadata
+```
+
+### matchPartial() - Partial navigation
+
+```typescript
+const result = await router.matchPartial(request, env, {
+  actionId: "addToCart",
+  actionResult: { success: true },
+});
+// Only re-renders changed segments
+```
+
+### matchError() - Error handling
+
+```typescript
+const result = await router.matchError(request, env, error);
+// Finds nearest error boundary
+```
+
+### previewMatch() - Middleware validation
+
+```typescript
+const result = await router.previewMatch(request, env);
+// Executes middleware without full segment resolution
+```
+
+## Complete Router Example
+
+```typescript
+// router.ts
+import { createRSCRouter } from "rsc-router/server";
+import { createMemorySegmentStore } from "rsc-router/cache";
+import { Document } from "./document";
+import { homeRoutes } from "./routes/home";
+import { shopRoutes } from "./routes/shop";
+import { adminRoutes } from "./routes/admin";
+import { loggerMiddleware, authMiddleware, adminMiddleware } from "./middleware";
+
+const cacheStore = createMemorySegmentStore();
+
+const router = createRSCRouter<AppEnv>({
+  document: Document,
+  debugPerformance: true,
+  cache: { store: cacheStore, enabled: true },
+  defaultErrorBoundary: <DefaultError />,
+  notFound: ({ pathname }) => <NotFoundPage pathname={pathname} />,
+})
+  // Global middleware
+  .use(loggerMiddleware)
+
+  // Public routes
+  .routes(homeRoutes)
+  .map(() => import("./handlers/home"))
+
+  // Shop routes (with auth)
+  .routes("/shop", shopRoutes)
+  .use(authMiddleware)
+  .map(() => import("./handlers/shop"))
+
+  // Admin routes (with admin auth)
+  .routes("/admin", adminRoutes)
+  .use(adminMiddleware)
+  .map(() => import("./handlers/admin"));
+
+export default router;
+export const href = router.href;
+```

package/skills/theme/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: theme
+description: Opt-in theme system with FOUC prevention for light/dark mode
+argument-hint: [setup]
+---
+
+# Theme Support
+
+Opt-in theme system with FOUC prevention.
+
+## Enable
+
+```typescript
+// Simple - all defaults
+const router = createRSCRouter<Env>({ theme: true });
+
+// Custom config
+const router = createRSCRouter<Env>({
+  theme: {
+    defaultTheme: "system",      // "light" | "dark" | "system"
+    themes: ["light", "dark"],
+    attribute: "class",          // or "data-theme"
+    storageKey: "theme",
+  }
+});
+```
+
+## Server (route handlers)
+
+```typescript
+route("settings", (ctx) => {
+  const current = ctx.theme;    // read from cookie
+  ctx.setTheme("dark");         // set cookie
+  return <Settings />;
+});
+```
+
+## Client
+
+```tsx
+"use client";
+import { useTheme } from "@rangojs/router/theme";
+
+function ThemeToggle() {
+  const { theme, setTheme, resolvedTheme, systemTheme, themes } = useTheme();
+  return <button onClick={() => setTheme("dark")}>Dark</button>;
+}
+```
+
+## Notes
+
+- `<MetaTags />` auto-renders inline script for FOUC prevention
+- Add `suppressHydrationWarning` to `<html>`
+- Theme persists in localStorage + cookie (for SSR)