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

package/skills/route/SKILL.md

@@ -1,141 +1,440 @@
 ---
 name: route
-description: Define basic routes and route handlers in rsc-router
-argument-hint: [route-name]
+description: Define routes with path() in @rangojs/router
+argument-hint: [pattern]
 ---
 
-# Basic Route Definition
+# Defining Routes with path()
 
-## Route Definition (routes.ts)
+## Basic Route
 
-Define type-safe routes using the `route()` function:
+```typescript
+import { urls } from "@rangojs/router";
+
+export const urlpatterns = urls(({ path }) => [
+  path("/", HomePage, { name: "home" }),
+  path("/about", AboutPage, { name: "about" }),
+  path("/contact", ContactPage, { name: "contact" }),
+]);
+```
+
+## Route with Parameters
 
 ```typescript
-import { route } from "rsc-router";
+urls(({ path }) => [
+  // Single parameter
+  path("/product/:slug", ProductPage, { name: "product" }),
 
-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)",
+  // Multiple parameters
+  path("/blog/:year/:month/:slug", BlogPostPage, { name: "blogPost" }),
+
+  // Optional parameter (add ? suffix)
+  path("/search/:query?", SearchPage, { name: "search" }),
+]);
+```
+
+## Route Handler Patterns
+
+### Component Function
+
+```typescript
+path("/about", AboutPage, { name: "about" })
+
+// AboutPage receives context
+function AboutPage(ctx: HandlerContext) {
+  return <div>About Us</div>;
+}
+```
+
+### Inline JSX
+
+```typescript
+path("/about", () => <AboutPage />, { name: "about" })
+```
+
+### Handler with Context Access
+
+```typescript
+path("/product/:slug", (ctx) => {
+  const { slug } = ctx.params;
+  return <ProductPage slug={slug} />;
+}, { name: "product" })
+```
+
+### Async Handler (Streaming)
+
+```typescript
+path("/product/:slug", async (ctx) => {
+  const product = await fetchProduct(ctx.params.slug);
+  return <ProductPage product={product} />;
+}, { name: "product" })
+```
+
+## Route Options
+
+```typescript
+path("/product/:slug", ProductPage, {
+  name: "product", // Route name for href() and navigation
 });
 ```
 
-### Parameter Types
+### Typed Search Params
 
-| 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 |
+Add a `search` schema to get typed `ctx.search`:
 
-## Route Handler (handlers/*.tsx)
+```typescript
+path("/search", SearchPage, {
+  name: "search",
+  search: { q: "string", page: "number?", sort: "string?" },
+});
+```
 
-Use the `map()` function to define handlers:
+Use `Handler<"name">` for typed search params (resolves from the generated route map automatically):
 
 ```typescript
-import { map } from "rsc-router/server";
-import type { routes } from "../routes.js";
+import type { Handler } from "@rangojs/router";
+
+export const SearchPage: Handler<"search"> = (ctx) => {
+  // ctx.search is typed: { q: string; page?: number; sort?: string }
+  const { q, page, sort } = ctx.search;
+  // ctx.searchParams is always URLSearchParams
+  return <SearchResults q={q} page={page} sort={sort} />;
+};
+```
 
-export default map<typeof routes>(({ route, loader, loading, revalidate }) => [
-  // Simple route
-  route("index", () => <HomePage />),
+Supported types: `"string"`, `"number"`, `"boolean"`, with `?` suffix for optional.
+Missing params are `undefined` regardless of required/optional. The required/optional
+distinction is a consumer-facing contract (for `href()` and `reverse()` autocomplete).
+
+Use `RouteSearchParams<"name">` and `RouteParams<"name">` to extract types for props:
+
+```typescript
+import type { RouteSearchParams, RouteParams } from "@rangojs/router";
+
+type SP = RouteSearchParams<"search">; // { q: string; page?: number; sort?: string }
+type P = RouteParams<"blogPost">; // { slug: string }
+```
+
+## Route Children
+
+Add loaders, loading states, and other features as children:
+
+```typescript
+path("/product/:slug", ProductPage, { name: "product" }, () => [
+  loader(ProductLoader),
+  loading(<ProductSkeleton />),
+  revalidate(productRevalidation),
+])
+```
+
+## Handler Data Ownership
+
+When a route has children (orphan layouts, parallels), the handler executes
+first. Use `ctx.set(key, value)` to share data with children, who read it
+via `ctx.get(key)`. Caching wraps all segments together, so either all run
+or none do.
 
-  // Route with params
-  route("product", (ctx) => {
-    return <ProductPage id={ctx.params.id} />;
+### Typed context variables with createVar
+
+Use `createVar<T>()` to create a typed token for `ctx.set()`/`ctx.get()`.
+The token is imported by both the handler (producer) and layout (consumer),
+making the data contract explicit and compile-time verified:
+
+```typescript
+import { createVar } from "@rangojs/router";
+import { Outlet, ParallelOutlet } from "@rangojs/router/client";
+
+// Typed token -- shared between handler and layout
+interface DashboardData {
+  title: string;
+  stats: { views: number };
+}
+const Dashboard = createVar<DashboardData>();
+
+path("/dashboard/:id", async (ctx) => {
+  const data = await fetchDashboard(ctx.params.id);
+  ctx.set(Dashboard, data);   // type-checked
+  return <DashboardPage data={data} />;
+}, { name: "dashboard" }, () => [
+  layout((ctx) => {
+    const data = ctx.get(Dashboard);  // typed as DashboardData | undefined
+    return (
+      <div>
+        <h1>{data?.title}</h1>
+        <Outlet />
+        <ParallelOutlet name="@sidebar" />
+      </div>
+    );
+  }),
+  parallel({
+    "@sidebar": (ctx) => {
+      const data = ctx.get(Dashboard);
+      return <Sidebar stats={data?.stats} />;
+    },
   }),
+])
+```
 
-  // Route with loader
-  route("blog.post", async (ctx) => {
-    const post = await ctx.use(PostLoader);
-    return <BlogPost post={post} />;
-  }, () => [
-    loader(PostLoader),
-    loading(<PostSkeleton />),
+String keys still work (`ctx.set("key", value)` / `ctx.get("key")`), but
+`createVar<T>()` is preferred for type safety.
+
+Only route handlers and middleware can call `ctx.set()`. Layouts, parallels,
+and intercepts can only read via `ctx.get()`.
+
+#### Non-cacheable context variables
+
+Mark a var as non-cacheable when it holds inherently request-specific data
+(sessions, auth tokens, per-request IDs). There are two ways:
+
+```typescript
+// Var-level: every value written to this var is non-cacheable
+const Session = createVar<SessionData>({ cache: false });
+
+// Write-level: escalate a normally-cacheable var for this specific write
+const Theme = createVar<string>();
+ctx.set(Theme, userTheme, { cache: false });
+```
+
+"Least cacheable wins" — if either the var definition or the write site says
+`cache: false`, the value is non-cacheable.
+
+Reading a non-cacheable var inside `cache()` or `"use cache"` throws at
+runtime. This prevents request-specific data from leaking into cached output:
+
+```typescript
+// This throws — Session is non-cacheable
+async function CachedWidget(ctx) {
+  "use cache";
+  const session = ctx.get(Session); // Error: non-cacheable var read inside cache scope
+  return <Widget />;
+}
+```
+
+Cacheable vars (the default) can be read freely inside cache scopes.
+
+### Revalidation Contracts for Handler Data
+
+Handler-first guarantees apply within a single full render pass. For partial
+action revalidation, define named revalidation contracts and reuse them on both
+the producer route and the consumer child segments.
+
+```typescript
+// revalidation-contracts.ts
+export const revalidateCheckoutData = ({ actionId }) =>
+  actionId?.includes("src/actions/checkout.ts#") ?? false;
+
+path("/checkout", CheckoutPage, { name: "checkout" }, () => [
+  revalidate(revalidateCheckoutData), // producer (route handler) reruns
+  layout(CheckoutLayout, () => [
+    revalidate(revalidateCheckoutData), // consumer reruns
+    parallel({ "@summary": CheckoutSummary }, () => [
+      revalidate(revalidateCheckoutData),
+    ]),
   ]),
 ]);
 ```
 
-## Handler Context
+If children depend on multiple upstream domains, compose multiple contracts on
+the same segment (`revalidateAuthData`, `revalidateCheckoutData`, and so on).
 
-The `ctx` object provides:
+For cleaner route trees, expose contract helpers and spread them:
 
 ```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
+import { revalidate } from "@rangojs/router";
+
+export const revalidateCheckout = () => [revalidate(revalidateCheckoutData)];
+
+path("/checkout", CheckoutPage, { name: "checkout" }, () => [
+  revalidateCheckout(),
+  layout(CheckoutLayout, () => [revalidateCheckout()]),
+]);
+```
 
-  // Data fetching
-  const data = await ctx.use(MyLoader);
+For scope/revalidation guarantees and non-guarantees, see:
+[docs/execution-model.md](../../docs/internal/execution-model.md)
 
-  // Handle accumulation
-  const push = ctx.use(BreadcrumbHandle);
-  push({ label: "Product", href: ctx.pathname });
+## Redirects
 
-  // Context variables (set by middleware)
-  const user = ctx.get("user");
+### Basic redirect
 
-  return <ProductPage />;
-});
+```typescript
+import { redirect } from "@rangojs/router";
+
+path("/old-page", () => redirect("/new-page"), { name: "oldPage" });
+```
+
+### Redirect with custom status
+
+```typescript
+path("/moved", () => redirect("/new-location", 301), { name: "moved" });
 ```
 
-## Router Registration (router.tsx)
+### Redirect with location state
 
-Register routes with the router:
+Carry typed state through redirects (e.g. flash messages):
 
 ```typescript
-import { createRSCRouter } from "rsc-router/server";
-import { routes } from "./routes.js";
+import { redirect, createLocationState } from "@rangojs/router";
 
-const router = createRSCRouter<AppEnv>({
-  document: RootLayout,
-})
-  .routes("/", routes)
-  .map(() => import("./handlers/main.js"));
+export const FlashMessage = createLocationState<{ text: string }>({
+  flash: true,
+});
 
-export default router;
+path(
+  "/save",
+  (ctx) => {
+    // ... save logic
+    return redirect("/dashboard", {
+      state: [FlashMessage({ text: "Item saved!" })],
+    });
+  },
+  { name: "save" },
+);
+
+// With custom status + state
+path(
+  "/action",
+  (ctx) => {
+    return redirect("/target", {
+      status: 303,
+      state: [FlashMessage({ text: "Action complete" })],
+    });
+  },
+  { name: "action" },
+);
 ```
 
-## Type-Safe Links
+Read the state on the target page with `useLocationState(FlashMessage)`. The
+`{ flash: true }` option makes it auto-clear. Without `{ flash: true }`,
+state persists on back/forward. See `/hooks` for details.
+
+### ctx.setLocationState()
+
+Attach location state to any server response (not just redirects):
+
+```typescript
+path("/dashboard", (ctx) => {
+  ctx.setLocationState(ServerInfo({ data: "welcome" }));
+  return <Dashboard />;
+}, { name: "dashboard" })
+```
+
+State flows to the browser via the RSC payload and is merged into
+`history.pushState()`. Only works for SPA (partial) navigations.
+
+## Handler Context
+
+Every handler receives a context object:
+
+```typescript
+interface HandlerContext<TParams = {}, TEnv = DefaultEnv, TSearch = {}> {
+  params: TParams; // URL parameters
+  request: Request; // Original request
+  searchParams: URLSearchParams; // Query params (always URLSearchParams)
+  search: {} | ResolveSearchSchema<TSearch>; // Typed search params (from search schema)
+  url: URL; // Parsed URL
+  env: TEnv; // Environment (bindings + variables)
+  set(key: string, value: any): void; // Set context variable (untyped string key)
+  set<T>(contextVar: ContextVar<T>, value: T): void; // Set typed context variable
+  get(key: string): any; // Read context variable (untyped string key)
+  get<T>(contextVar: ContextVar<T>): T | undefined; // Read typed context variable
+  use<T>(handle: Handle<T>): T; // Access handles
+  reverse(
+    name: string,
+    params?: Record<string, string>,
+    search?: Record<string, unknown>,
+  ): string; // URL generation
+  setLocationState(entries: LocationStateEntry[]): void; // Attach state to response
+}
+```
 
-Use the generated `href` function:
+### Using Context
 
 ```typescript
-import { href } from "./router.js";
+path("/product/:slug", (ctx) => {
+  // Access URL params
+  const { slug } = ctx.params;
+
+  // Access query params (untyped - use search schema for typed access)
+  const tab = ctx.searchParams.get("tab");
 
-// Type-safe href generation
-<Link href={href("product", { id: "123" })} />
-<Link href={href("blog.post", { slug: "hello-world" })} />
+  // Access platform bindings
+  const db = ctx.env.DB;
 
-// With query params
-<Link href={href("search", { query: "test" }, { page: "2" })} />
+  // Access handles
+  const breadcrumbs = ctx.use(Breadcrumbs);
+  breadcrumbs.push({ label: "Product", href: `/product/${slug}` });
+
+  return <ProductPage slug={slug} tab={tab} />;
+}, { name: "product" })
 ```
 
-## Route Configuration Options
+## Nested Routes
+
+Use layouts to nest routes:
 
 ```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
+urls(({ path, layout }) => [
+  layout(<ShopLayout />, () => [
+    path("/shop", ShopIndex, { name: "shop.index" }),
+    path("/shop/cart", CartPage, { name: "shop.cart" }),
+    path("/shop/product/:slug", ProductPage, { name: "shop.product" }),
+  ]),
 ])
 ```
+
+## Handler-attached `.use`
+
+Page handlers can carry their own loader, middleware, error boundaries, parallels, and other defaults via a `.use` callback — so the page is self-contained and reusable across mount sites without re-wiring the same items.
+
+```typescript
+const ProductPage: Handler<"/product/:slug"> = async (ctx) => {
+  const product = await ctx.use(ProductLoader);
+  return <ProductView product={product} />;
+};
+ProductPage.use = () => [
+  loader(ProductLoader),
+  loading(<ProductSkeleton />),
+  middleware(async (ctx, next) => {
+    await next();
+    ctx.header("Cache-Control", "private, max-age=60");
+  }),
+];
+
+// Mount site has no per-page wiring — defaults travel with the handler.
+path("/product/:slug", ProductPage, { name: "product" });
+```
+
+Explicit `use()` at the mount site merges with `handler.use` (handler defaults first, explicit second). See [skills/handler-use](../handler-use/SKILL.md) for the merge order, allowed item types per mount site, and override semantics.
+
+## Complete Example
+
+```typescript
+import { urls, Breadcrumbs } from "@rangojs/router";
+
+export const urlpatterns = urls(({ path, layout, loader, loading }) => [
+  // Simple route
+  path("/", HomePage, { name: "home" }),
+
+  // Route with loader
+  path("/about", AboutPage, { name: "about" }, () => [
+    loader(TeamLoader),
+  ]),
+
+  // Dynamic route with handler
+  path("/product/:slug", (ctx) => {
+    const push = ctx.use(Breadcrumbs);
+    push({ label: ctx.params.slug, href: `/product/${ctx.params.slug}` });
+    return <ProductPage slug={ctx.params.slug} />;
+  }, { name: "product" }, () => [
+    loader(ProductLoader),
+    loading(<ProductSkeleton />, { ssr: true }),
+  ]),
+
+  // Nested routes in layout
+  layout(<BlogLayout />, () => [
+    path("/blog", BlogIndex, { name: "blog.index" }),
+    path("/blog/:slug", BlogPost, { name: "blog.post" }),
+  ]),
+]);
+```