@rangojs/router 0.0.0-experimental.8 → 0.0.0-experimental.80daa23e

package/skills/route/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: route
-description: Define routes with path() in @rangojs/router
+description: Define routes with path() in @rangojs/router. Use when creating a new page or route, or asking how to define a URL path and its handler.
 argument-hint: [pattern]
 ---
 
@@ -33,6 +33,69 @@ urls(({ path }) => [
 ]);
 ```
 
+### Optional URL params at runtime
+
+Absent optional params are **omitted from `ctx.params`** — `ctx.params.<name>`
+reads as `undefined`, matching the `RouteParams<"name">` type
+(`{ query?: string }`). Use `??` to default and `=== undefined` to check
+absence:
+
+```typescript
+path("/search/:query?", (ctx) => {
+  const query = ctx.params.query ?? ""; // works — undefined coalesces
+  if (ctx.params.query === undefined) return <EmptySearch />;
+  return <Results query={ctx.params.query} />;
+}, { name: "search" });
+```
+
+For the common pattern of an optional locale prefix
+(`include("/:locale?", routes)`) and the wider react-intl integration —
+locale detection, fallback chains, URL generation with absent locale —
+see `/i18n`.
+
+### Named catch-all params (`:name+` / `:name*`)
+
+A catch-all consumes the **rest of the path** and exposes it as a single
+decoded string at `ctx.params.<name>`, with the internal `/` separators kept.
+It must be the **last** segment of the pattern.
+
+- `:name+` — **one-or-more** segments (Next `[...name]`, React-Router splat).
+  `/docs/:slug+` matches `/docs/a` and `/docs/a/b/c`, but **not** the bare
+  `/docs`.
+- `:name*` — **zero-or-more** segments (Next `[[...name]]`). `/docs/:slug*`
+  additionally matches the bare `/docs`, binding `ctx.params.slug` to `""`.
+
+```typescript
+urls(({ path }) => [
+  // /shop/electronics/phones -> ctx.params.path === "electronics/phones"
+  path("/shop/:path+", ShopCatchAll, { name: "shopCatchAll" }),
+
+  // /docs         -> ctx.params.slug === ""
+  // /docs/intro   -> ctx.params.slug === "intro"
+  // /docs/a/b     -> ctx.params.slug === "a/b"
+  path("/docs/:slug*", (ctx) => {
+    const parts = ctx.params.slug === "" ? [] : ctx.params.slug.split("/");
+    return <Docs segments={parts} />;
+  }, { name: "docs" }),
+]);
+```
+
+`ctx.params.<name>` is always a `string` for a catch-all (never `undefined`) —
+`:name*` binds `""` for the empty case, so read it directly. `reverse()` /
+`ctx.reverse()` rebuild the URL with separators preserved:
+`reverse("docs", { slug: "a/b" })` -> `/docs/a/b`.
+
+The value is the URL-decoded remainder. `split("/")` recovers the segments in the
+common case, but note that a segment containing an encoded slash (`%2F`) decodes
+to a literal `/` and is therefore indistinguishable from a separator — the same
+trade-off the bare `*` splat has. If you need to distinguish those, match on the
+raw pathname instead.
+
+The bare unnamed wildcard `path("/files/*", …)` still works and is read at
+`ctx.params["*"]`; prefer a named catch-all when you want a typed param key.
+Combining a modifier with `?`, a literal suffix, or a constraint
+(`:slug*?`, `:slug*.html`, `:slug(a|b)+`) is rejected at build time.
+
 ## Route Handler Patterns
 
 ### Component Function
@@ -74,8 +137,45 @@ path("/product/:slug", async (ctx) => {
 
 ```typescript
 path("/product/:slug", ProductPage, {
-  name: "product",  // Route name for href() and navigation
-})
+  name: "product", // Route name for href() and navigation
+});
+```
+
+### Typed Search Params
+
+Add a `search` schema to get typed `ctx.search`:
+
+```typescript
+path("/search", SearchPage, {
+  name: "search",
+  search: { q: "string", page: "number?", sort: "string?" },
+});
+```
+
+Use `Handler<"name">` for typed search params (resolves from the generated route map automatically):
+
+```typescript
+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} />;
+};
+```
+
+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
@@ -90,17 +190,260 @@ path("/product/:slug", ProductPage, { name: "product" }, () => [
 ])
 ```
 
+## 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.
+
+This pattern is also safe under partial action revalidation: on an action,
+the route entry re-runs as a unit by default — route segment, loaders, and
+`belongsToRoute` children (orphan layouts, entry parallels) all seed
+revalidate-true, with handler-first ordering preserved. Handler-set data
+stays consistent with no configuration. See `/rango` → "Passing data down
+the tree" for the safest-first ladder.
+
+### 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} />;
+    },
+  }),
+])
+```
+
+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
+
+> **Scope: `revalidate()` is a partial-render concern, not a cache concern.**
+> It decides whether this segment re-runs and streams to the client on a
+> navigation or action — never whether a cached value is stale. The cache
+> decides hit/miss/ttl/swr independently and never reads `revalidate()`. See
+> `/cache-guide` → "Two axes" and `/rango` → "The shape of rango".
+
+With no `revalidate()` configured, an entry needs no contract: on an action
+the route handler and its children re-run together by default, so handler
+data stays consistent on its own. Contracts matter in two cases:
+
+1. **You narrow the entry's revalidation** with a predicate that can return a
+   hard `false` (e.g. bare `ctx.isAction(X)`). A hard `false` on one side of a
+   producer/consumer pair desyncs it — the child re-runs by default and reads
+   `undefined`, or vice versa. Put the same named contract on the route and
+   its dependent children so they narrow together.
+2. **The producer is an outer entry** (a standalone `layout()` above this
+   route). Outer entries skip action revalidation by default, so the shared
+   contract is mandatory — see `/layout` → "Revalidation Contracts".
+
+```typescript
+// revalidation-contracts.ts
+import * as CheckoutActions from "./actions/checkout";
+
+// Defer (|| undefined), not ?? false: a hard `false` short-circuits the chain,
+// so when the same segment composes multiple contracts the later ones never run.
+export const revalidateCheckoutData = (ctx) =>
+  ctx.isAction(CheckoutActions) || undefined;
+
+path("/checkout", CheckoutPage, { name: "checkout" }, () => [
+  revalidate(revalidateCheckoutData), // producer (route handler) reruns
+  layout(CheckoutLayout, () => [
+    revalidate(revalidateCheckoutData), // consumer reruns
+    parallel({ "@summary": CheckoutSummary }, () => [
+      revalidate(revalidateCheckoutData),
+    ]),
+  ]),
+]);
+```
+
+If children depend on multiple upstream domains, compose multiple contracts on
+the same segment (`revalidateAuthData`, `revalidateCheckoutData`, and so on).
+
+For cleaner route trees, expose contract helpers and spread them:
+
+```typescript
+import { revalidate } from "@rangojs/router";
+
+export const revalidateCheckout = () => [revalidate(revalidateCheckoutData)];
+
+path("/checkout", CheckoutPage, { name: "checkout" }, () => [
+  revalidateCheckout(),
+  layout(CheckoutLayout, () => [revalidateCheckout()]),
+]);
+```
+
+## Redirects
+
+### Basic redirect
+
+```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" });
+```
+
+> **Redirecting from a route with `loading()`:** an `async` handler that returns
+> a `Response`/`redirect()` on a route that also declares `loading()` is streamed,
+> so the redirect is rendered into the RSC stream instead of becoming an HTTP
+> redirect. For a real HTTP redirect, issue it from `middleware` or a
+> **synchronous** handler return — pre-stream redirect authority belongs there.
+> (A loader `throw redirect()` also navigates the user, but it is ALWAYS a
+> client-side replace on document loads — 200 document, never a 302; see
+> `/loader` → "Loader Authority". Dev logs a warning if this is hit.)
+
+### Redirect with location state
+
+Carry typed state through redirects (e.g. flash messages):
+
+```typescript
+import { redirect, createLocationState } from "@rangojs/router";
+
+export const FlashMessage = createLocationState<{ text: string }>({
+  flash: true,
+});
+
+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" },
+);
+```
+
+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
+import { createLocationState } from "@rangojs/router";
+
+const ServerInfo = createLocationState<{ data: string }>();
+
+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 = Record<string, string>> {
-  params: TParams;           // URL parameters
-  request: Request;          // Original request
-  url: URL;                  // Parsed URL
-  env: TEnv;                 // Environment (bindings + variables)
-  use<T>(handle: Handle<T>): T;  // Access handles
+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
 }
 ```
 
@@ -111,11 +454,11 @@ path("/product/:slug", (ctx) => {
   // Access URL params
   const { slug } = ctx.params;
 
-  // Access query params
-  const tab = ctx.url.searchParams.get("tab");
+  // Access query params (untyped - use search schema for typed access)
+  const tab = ctx.searchParams.get("tab");
 
-  // Access environment
-  const db = ctx.env.Bindings.DB;
+  // Access platform bindings
+  const db = ctx.env.DB;
 
   // Access handles
   const breadcrumbs = ctx.use(Breadcrumbs);
@@ -139,11 +482,52 @@ urls(({ path, layout }) => [
 ])
 ```
 
+For composing whole route MODULES, reach for `include()` — and prefer the
+code-split form `include("/shop", () => import("./shop-patterns"))` for any
+group that is a natural unit: it keeps the group off the cold-start path, and
+measured first-hit cost scales with routes-per-chunk, so many small groups
+beat one giant one. Sizing rules and the numbers behind them:
+[skills/composability](../composability/SKILL.md) → "Sizing async include
+groups (measured)".
+
+`include()` has three name modes: omit `{ name }` for a private local route-name
+scope, pass a non-empty name to namespace children globally, or pass
+`{ name: "" }` to flatten globally unique child names into the parent map. URL
+matching works in all three modes; the option controls name visibility, not
+whether the routes mount.
+
+## View Transitions
+
+A route can configure its own `transition()` — the wrap goes around the route's component itself (routes are leaves; they have no separate default outlet channel). If the route component renders a `<ParallelOutlet />` directly, that slot remains inside the route's VT subtree, so prefer mounting parallel slots in a layout when combining intercept modals with route-level transitions. See [skills/view-transitions](../view-transitions/SKILL.md) for examples and the wrap-location rules across layouts, routes, and slots.
+
+## 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 } from "@rangojs/router";
-import { Breadcrumbs } from "./handles/breadcrumbs";
+import { urls, Breadcrumbs } from "@rangojs/router";
 
 export const urlpatterns = urls(({ path, layout, loader, loading }) => [
   // Simple route