@rangojs/router 0.0.0-experimental.2 → 0.0.0-experimental.20dbba0c

package/skills/router-setup/SKILL.md

@@ -1,403 +1,524 @@
 ---
 name: router-setup
-description: Create and configure the RSC router with createRSCRouter
+description: Create and configure the RSC router with createRouter
 argument-hint: [option]
 ---
 
-# Router Setup with createRSCRouter
+# Router Setup with createRouter
 
 ## Basic Router Creation
 
 ```typescript
-import { createRSCRouter } from "rsc-router/server";
+// src/router.tsx
+import { createRouter } from "@rangojs/router";
 import { Document } from "./document";
+import { urlpatterns } from "./urls";
 
-const router = createRSCRouter({
+const router = createRouter({
   document: Document,
+  urls: urlpatterns,
 });
 
 export default router;
 ```
 
+## URL Patterns (Django-style)
+
+```typescript
+// src/urls.tsx
+import { urls } from "@rangojs/router";
+import { HomePage } from "./pages/home";
+import { AboutPage } from "./pages/about";
+import { ProductPage } from "./pages/product";
+import { RootLayout } from "./layouts/RootLayout";
+
+export const urlpatterns = urls(({ path, layout, loader, loading }) => [
+  path("/", HomePage, { name: "home" }),
+  path("/about", AboutPage, { name: "about" }),
+
+  layout(<RootLayout />, () => [
+    path("/product/:slug", ProductPage, { name: "product" }, () => [
+      loader(ProductLoader),
+      loading(<ProductSkeleton />),
+    ]),
+  ]),
+]);
+```
+
+## The urls() DSL
+
+The `urls()` function provides a callback with all available DSL functions:
+
+```typescript
+urls(
+  ({
+    path, // Define a route
+    layout, // Wrap routes in a layout
+    parallel, // Define parallel routes (slots)
+    loader, // Add data loader
+    loading, // Add loading skeleton
+    cache, // Configure caching
+    middleware, // Add middleware
+    revalidate, // Control revalidation
+    intercept, // Intercept routes for modals
+    when, // Conditional rendering
+  }) => [
+    // Route definitions here
+  ],
+);
+```
+
 ## Router Options
 
 ```typescript
 interface RSCRouterOptions<TEnv> {
+  // URL patterns from urls() function
+  urls: UrlPatterns;
+
   // Document component wrapping entire app
   document?: ComponentType<{ children: ReactNode }>;
 
-  // Enable performance metrics (console + Server-Timing header)
+  // URL prefix for sub-path deployments (e.g. "/admin")
+  // All routes, reverse(), href(), Link, redirect(), and router.use()
+  // patterns are automatically prefixed. Route names stay unprefixed.
+  basename?: string;
+
+  // Enable per-request performance timeline (console waterfall + Server-Timing header)
   debugPerformance?: boolean;
 
-  // Default error boundary fallback
+  // Default error boundary
   defaultErrorBoundary?: ReactNode | ErrorBoundaryHandler;
 
-  // Default not-found boundary (for notFound() calls)
+  // Default not-found boundary for notFound() thrown in handlers/loaders
   defaultNotFoundBoundary?: ReactNode | NotFoundBoundaryHandler;
 
-  // Component for routes with no match (404)
+  // Component for 404 (no route match, or notFound() without a boundary)
   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 });
+  // Global cache configuration
+  cache?: CacheConfig<TEnv>;
+
+  // Theme configuration
+  theme?: ThemeConfig | true;
+
+  // SSR options (streaming policy)
+  ssr?: SSROptions<TEnv>;
+
+  // Telemetry sink for structured lifecycle events
+  telemetry?: TelemetrySink;
+
+  // Connection warmup (default: true)
+  warmup?: boolean;
+
+  // Prefetch cache TTL in seconds (default: 300)
+  // Controls in-memory cache duration and Cache-Control max-age for prefetch responses.
+  // Set to false to disable prefetch caching.
+  prefetchCacheTTL?: number | false;
+
+  // CSP nonce provider (for router.fetch)
+  nonce?: (
+    request: Request,
+    env: TEnv,
+  ) => string | true | Promise<string | true>;
+
+  // RSC version string (for router.fetch)
+  version?: string;
 }
 ```
 
-## Full Configuration Example
+## Basename (Sub-Path Deployment)
+
+When your app is served under a sub-path (e.g. `/admin` or `/v2`), set `basename`:
 
 ```typescript
-import { createRSCRouter } from "rsc-router/server";
-import { createMemorySegmentStore } from "rsc-router/cache";
-import { Document } from "./document";
+const router = createRouter({
+  basename: "/admin",
+  document: Document,
+}).routes(({ path, include }) => [
+  path("/", Dashboard, { name: "home" }), // matches /admin
+  path("/users", Users, { name: "users" }), // matches /admin/users
+  include("/api", apiPatterns, { name: "api" }), // matches /admin/api/*
+]);
 
-const cacheStore = createMemorySegmentStore();
+router.reverse("home"); // "/admin"
+router.reverse("users"); // "/admin/users"
+```
 
-const router = createRSCRouter<AppEnv>({
-  document: Document,
-  debugPerformance: process.env.NODE_ENV === "development",
+Router-owned APIs are basename-aware:
 
-  cache: {
-    store: cacheStore,
-    enabled: true,
-  },
+- `reverse()` returns prefixed paths
+- `<Link to="/users">` renders `<a href="/admin/users">`
+- `redirect("/login")` redirects to `"/admin/login"`
+- `router.use("/users/*", mw)` matches `/admin/users/*`
+- `useRouter().push("/users")` navigates to `/admin/users`
+- Route names stay unprefixed (`"home"`, not `"admin.home"`)
 
-  defaultErrorBoundary: ({ error, reset }) => (
-    <div className="error">
-      <h2>Something went wrong</h2>
-      <p>{error.message}</p>
-      <button onClick={reset}>Try again</button>
-    </div>
-  ),
+Note: `href()` is a raw path helper and does **not** auto-prefix with basename.
+Use `reverse()` or `<Link>` for basename-aware URLs.
 
-  defaultNotFoundBoundary: ({ notFound }) => (
-    <div className="not-found">
-      <h2>Not Found</h2>
-      <p>{notFound.message}</p>
-    </div>
-  ),
+## Using the Request Handler
 
-  notFound: ({ pathname }) => (
-    <div className="404">
-      <h1>404</h1>
-      <p>Page not found: {pathname}</p>
-    </div>
-  ),
+The router provides a `fetch` method to handle RSC requests:
 
-  onError: (error, ctx) => {
-    console.error("Router error:", error);
-    // Send to error tracking service
-  },
+```typescript
+// src/router.tsx
+import { createRouter } from "@rangojs/router";
+import { Document } from "./document";
+import { urlpatterns } from "./urls";
+
+export const router = createRouter({
+  document: Document,
+  urls: urlpatterns,
+  nonce: () => true, // Auto-generate nonce for CSP
 });
-```
 
-## Environment Types
+// src/worker.tsx (Cloudflare Workers)
+import { router } from "./router";
 
-Define your app's environment type:
+export default { fetch: router.fetch };
+```
+
+## Document Component
 
 ```typescript
-import type { RouterEnv } from "rsc-router/server";
+// src/document.tsx
+import type { ReactNode } from "react";
 
-interface AppBindings {
-  DB: D1Database;
-  KV: KVNamespace;
-  RATE_LIMITER: RateLimiter;
+export function Document({ children }: { children: 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>
+        <div id="root">{children}</div>
+      </body>
+    </html>
+  );
 }
+```
 
-interface AppVariables {
-  user?: { id: string; name: string };
-  permissions?: string[];
-}
+## Using with Cloudflare Workers
 
-type AppEnv = RouterEnv<AppBindings, AppVariables>;
+```typescript
+// src/router.tsx
+import { createRouter } from "@rangojs/router";
+import { Document } from "./document";
+import { urlpatterns } from "./urls";
 
-const router = createRSCRouter<AppEnv>({
+export const router = createRouter<AppBindings>({
   document: Document,
+  urls: urlpatterns,
 });
+
+// src/worker.tsx
+import { router } from "./router";
+
+export default {
+  async fetch(request: Request, env: Env, ctx: ExecutionContext) {
+    return router.fetch(request, { env, ctx });
+  },
+};
 ```
 
-## Registering Routes
+### With Dynamic Cache Configuration
 
-### routes() - Register route definitions
+For per-request cache configuration (e.g., Cloudflare Workers with ExecutionContext):
 
 ```typescript
-import { homeRoutes } from "./routes/home";
-import { shopRoutes } from "./routes/shop";
-import { adminRoutes } from "./routes/admin";
+// src/router.tsx
+import { createRouter } from "@rangojs/router";
+import { CFCacheStore } from "@rangojs/router/cache";
 
-const router = createRSCRouter<AppEnv>({ document: Document })
-  // Without prefix
-  .routes(homeRoutes)
-  .map(() => import("./handlers/home"))
+export const router = createRouter<AppBindings>({
+  document: Document,
+  urls: urlpatterns,
+  // Cache config receives (env, ctx) separately
+  cache: (_env, ctx) => ({
+    store: new CFCacheStore({ ctx: ctx!, defaults: { ttl: 60 } }),
+  }),
+});
 
-  // With prefix
-  .routes("/shop", shopRoutes)
-  .map(() => import("./handlers/shop"))
+// src/worker.tsx
+import { router } from "./router";
 
-  .routes("/admin", adminRoutes)
-  .map(() => import("./handlers/admin"));
+export default {
+  async fetch(request: Request, env: Env, ctx: ExecutionContext) {
+    return router.fetch(request, { env, ctx });
+  },
+};
 ```
 
-### map() - Register handlers
+## Complete Example
 
 ```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),
+// src/urls.tsx
+import { urls } from "@rangojs/router";
+import { Outlet } from "@rangojs/router/client";
+
+// Pages
+import { HomePage } from "./pages/home";
+import { AboutPage } from "./pages/about";
+import { BlogIndexPage, BlogPostPage } from "./pages/blog";
+
+// Layouts
+import { RootLayout } from "./layouts/RootLayout";
+import { BlogLayout } from "./layouts/BlogLayout";
+
+// Loaders
+import { BlogPostLoader, BlogSidebarLoader } from "./loaders/blog";
+
+export const urlpatterns = urls(({ path, layout, parallel, loader, loading, cache }) => [
+  // Simple routes
+  path("/", HomePage, { name: "home" }),
+  path("/about", AboutPage, { name: "about" }),
+
+  // Blog with layout and loaders
+  layout(<BlogLayout />, () => [
+    // Sidebar as parallel route
+    parallel({ "@sidebar": () => <BlogSidebar /> }, () => [
+      loader(BlogSidebarLoader),
+    ]),
+
+    // Cached blog routes
+    cache({ ttl: 60 }, () => [
+      path("/blog", BlogIndexPage, { name: "blog" }),
+      path("/blog/:slug", BlogPostPage, { name: "blogPost" }, () => [
+        loader(BlogPostLoader),
+        loading(<BlogPostSkeleton />),
+      ]),
+    ]),
   ]),
 ]);
 ```
 
-## Global Middleware
+```typescript
+// src/router.tsx
+import { createRouter } from "@rangojs/router";
+import { Document } from "./document";
+import { urlpatterns } from "./urls";
 
-### use() - Add middleware
+const router = createRouter({
+  document: Document,
+  urls: urlpatterns,
 
-```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"));
-```
+  defaultErrorBoundary: ({ error, reset }) => (
+    <div>
+      <h1>Something went wrong</h1>
+      <button onClick={reset}>Try again</button>
+    </div>
+  ),
 
-### Middleware patterns
+  notFound: ({ pathname }) => (
+    <div>
+      <h1>404</h1>
+      <p>Page not found: {pathname}</p>
+    </div>
+  ),
+});
 
-```typescript
-"/admin/*"           // All paths under /admin
-"/api/*/protected"   // Wildcard in middle
-"/checkout.*"        // Routes starting with /checkout
+export default router;
 ```
 
-## Type-Safe Links with href()
+## Not Found Handling
+
+Two distinct 404 scenarios:
+
+**1. No route matches the URL** — the router renders the `notFound` component from `createRouter()` config. This is automatic.
+
+**2. A handler/loader calls `notFound()`** — signals that the route matched but the data doesn't exist (e.g., invalid product ID).
 
 ```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",
-});
+import { notFound } from "@rangojs/router";
 
-// 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>
+// In a handler or loader
+path("/product/:slug", async (ctx) => {
+  const product = await db.getProduct(ctx.params.slug);
+  if (!product) notFound("Product not found");
+  return <ProductPage product={product} />;
+});
 ```
 
-**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.
+### Fallback chain for `notFound()`
 
-## Route Type Registration
+When `notFound()` is thrown, the router looks for a fallback in this order:
 
-For global type inference:
+1. **`notFoundBoundary()`** — nearest boundary in the route tree (route-level)
+2. **`defaultNotFoundBoundary`** — from `createRouter()` config (app-level)
+3. **`notFound`** — from `createRouter()` config (same component used for no-route-match)
+4. **Default `<h1>Not Found</h1>`** — built-in fallback
 
-```typescript
-// router.ts
-const _router = createRSCRouter<AppEnv>({ document: Document })
-  .routes(homeRoutes)
-  .map(() => import("./handlers/home"))
-  .routes("/shop", shopRoutes)
-  .map(() => import("./handlers/shop"));
+All cases set HTTP 404 status.
 
-// Extract route types
-type AppRoutes = typeof _router.routeMap;
+### notFoundBoundary
 
-// Augment global types
-declare global {
-  namespace RSCRouter {
-    interface RegisteredRoutes extends AppRoutes {}
-    interface Env extends AppEnv {}
-  }
-}
+Wrap routes with `notFoundBoundary()` for route-specific not-found UI:
 
-export default _router;
-export const href = _router.href;
+```typescript
+urls(({ path, layout }) => [
+  layout(ShopLayout, () => [
+    notFoundBoundary(({ notFound: info }) => (
+      <div>
+        <h1>Not Found</h1>
+        <p>{info.message}</p>
+      </div>
+    )),
+    path("/product/:slug", ProductPage),
+  ]),
+]);
 ```
 
-Now handlers have type-safe context without imports.
-
-## Cache Configuration
+`notFoundBoundary` receives `{ notFound: NotFoundInfo }` where `NotFoundInfo` contains `message`, `segmentId`, `segmentType`, and `pathname`.
 
-### Static cache
+## Including Sub-patterns
 
 ```typescript
-import { createMemorySegmentStore } from "rsc-router/cache";
+// src/urls/shop.tsx
+import { urls } from "@rangojs/router";
 
-const cacheStore = createMemorySegmentStore();
+export const shopPatterns = urls(({ path, layout }) => [
+  path("/", ShopIndex, { name: "index" }),
+  path("/product/:slug", ProductPage, { name: "product" }),
+]);
 
-const router = createRSCRouter<AppEnv>({
-  document: Document,
-  cache: {
-    store: cacheStore,
-    enabled: true,
-  },
-});
+// src/urls.tsx
+import { urls } from "@rangojs/router";
+import { shopPatterns } from "./urls/shop";
+
+export const urlpatterns = urls(({ path, include }) => [
+  path("/", HomePage, { name: "home" }),
+  include("/shop", shopPatterns, { name: "shop" }),
+]);
 ```
 
-### Dynamic cache (per-environment)
+## Environment Types
 
 ```typescript
-const router = createRSCRouter<AppEnv>({
+// Bindings passed as TEnv to createRouter<TEnv>()
+interface AppBindings {
+  DB: D1Database;
+  KV: KVNamespace;
+}
+
+// Variables declared via module augmentation
+interface AppVariables {
+  user?: { id: string; name: string };
+}
+
+const router = createRouter<AppBindings>({
   document: Document,
-  cache: (env) => ({
-    store: env.Bindings.CACHE_KV,
-    enabled: env.Bindings.CACHE_ENABLED === "true",
-  }),
+  urls: urlpatterns,
 });
+
+// Register types globally for implicit typing
+declare global {
+  namespace RSCRouter {
+    interface Env extends AppBindings {}
+    interface Vars extends AppVariables {}
+  }
+}
 ```
 
-### Cloudflare KV cache
+## Connection Warmup
+
+Enabled by default. Keeps TCP+TLS connections alive so navigations after idle periods
+don't pay handshake costs.
+
+After 60s of no user interaction, the connection is marked cold. When the user returns
+(tab becomes visible or first mouse/touch), a `HEAD ?_rsc_warmup` request re-establishes
+the TLS connection before the next navigation. The server responds with 204 No Content
+before any middleware or routing runs.
 
 ```typescript
-import { createCFKVSegmentStore } from "rsc-router/cache/cf";
+// Enabled by default
+const router = createRouter({
+  document: Document,
+  urls: urlpatterns,
+});
 
-const router = createRSCRouter<AppEnv>({
+// Disable warmup
+const router = createRouter({
   document: Document,
-  cache: (env) => ({
-    store: createCFKVSegmentStore(env.Bindings.CACHE_KV),
-    enabled: true,
-  }),
+  urls: urlpatterns,
+  warmup: false,
 });
 ```
 
-## Document Component
+The warmup request is relative to the current page path, so it works correctly
+with subpath deployments (reverse proxy, base path).
 
-The document wraps the entire app and persists during errors:
+## Telemetry
+
+The router emits structured lifecycle events through a pluggable telemetry sink.
+Zero overhead when not configured.
 
 ```typescript
-// document.tsx
-"use client";
+// Console sink for development
+import { createRouter, createConsoleSink } from "@rangojs/router";
 
-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>
-  );
-}
+const router = createRouter({
+  document: Document,
+  urls: urlpatterns,
+  telemetry: createConsoleSink(),
+});
 ```
 
-## Router Methods
-
-### match() - Full render
-
 ```typescript
-const result = await router.match(request, env);
-// Returns full render tree with segments, loaders, metadata
-```
+// OpenTelemetry for production
+import { createRouter, createOTelSink } from "@rangojs/router";
+import { trace } from "@opentelemetry/api";
 
-### matchPartial() - Partial navigation
+const router = createRouter({
+  document: Document,
+  urls: urlpatterns,
+  telemetry: createOTelSink(trace.getTracer("my-app")),
+});
+```
 
 ```typescript
-const result = await router.matchPartial(request, env, {
-  actionId: "addToCart",
-  actionResult: { success: true },
+// Custom sink
+const router = createRouter({
+  telemetry: {
+    emit(event) {
+      // Send to any observability backend
+      myTracer.record(event);
+    },
+  },
 });
-// Only re-renders changed segments
 ```
 
-### matchError() - Error handling
+Events emitted: `request.start/end/error`, `loader.start/end/error`,
+`handler.error`, `cache.decision`, `revalidation.decision`.
 
-```typescript
-const result = await router.matchError(request, env, error);
-// Finds nearest error boundary
-```
+## SSR Streaming Policy
 
-### previewMatch() - Middleware validation
+Control whether HTML SSR responses stream progressively or wait for all content:
 
 ```typescript
-const result = await router.previewMatch(request, env);
-// Executes middleware without full segment resolution
+import { createRouter, type SSRStreamMode } from "@rangojs/router";
+
+const router = createRouter({
+  ssr: {
+    resolveStreaming: ({ request }) => {
+      const ua = request.headers.get("user-agent") ?? "";
+      // Bots that can't process streamed HTML get a fully resolved page
+      if (/Googlebot|bingbot/i.test(ua)) return "allReady";
+      return "stream";
+    },
+  },
+});
 ```
 
-## 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";
+`SSRStreamMode` is `"stream" | "allReady"`:
 
-const cacheStore = createMemorySegmentStore();
+- `"stream"` (default) — flush HTML as React renders. Suspense fallbacks appear first, then resolved content streams in. Best for real users (fastest TTFB).
+- `"allReady"` — await `stream.allReady` before flushing. The full page arrives in one shot. Use for bots that cannot execute JavaScript or process chunked HTML.
 
-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"));
+The resolver receives `{ request, env, url }` and may be sync or async. It only runs on HTML SSR paths — RSC partials, `__rsc` requests, and response routes are unaffected.
 
-export default router;
-export const href = router.href;
-```
+When `resolveStreaming` is not configured, the default is `"stream"`.