@rangojs/router 0.16.0 → 0.18.0

package/skills/layout/SKILL.md

@@ -6,7 +6,15 @@ argument-hint: [component]
 
 # Layouts with layout()
 
-Layouts wrap child routes and persist during navigation within their scope.
+`layout(handler, use?)` wraps its child routes in shared UI (nav, sidebar,
+shell). The child content renders where the layout places `<Outlet />`, and the
+layout stays mounted while you navigate between the routes it wraps. This skill
+covers layout forms, outlets, orphan layouts (a layout inside a `path()`), and
+layout revalidation.
+
+Related skills: `/parallel` (named slots rendered by a layout), `/intercept`
+(modal slots), `/route` (the routes a layout wraps), `/router-setup` (the
+`document` shell that renders `<html>`).
 
 ## Basic Layout
 
@@ -50,7 +58,12 @@ layout(ShopLayout, () => [path("/shop", ShopIndex, { name: "shop" })]);
 
 ### Handler with Context
 
+A function layout receives the same handler context as a route (`ctx.params`,
+`ctx.get()`, `ctx.set()`, `ctx.use()`):
+
 ```typescript
+import { Breadcrumbs } from "@rangojs/router";
+
 layout((ctx) => {
   const push = ctx.use(Breadcrumbs);
   push({ label: "Shop", href: "/shop" });
@@ -97,7 +110,8 @@ layout(<ShopLayout />, () => [
 
 ## The Outlet Component
 
-`<Outlet />` renders child content. Import from `@rangojs/router/client`:
+`<Outlet />` renders child content. Import from `@rangojs/router/client`
+(it works in server and client components):
 
 ```typescript
 import { Outlet } from "@rangojs/router/client";
@@ -119,7 +133,9 @@ A layout's `transition()` config wraps the content that flows through `<Outlet /
 
 ## Named Outlets
 
-For parallel routes, use named outlets:
+For parallel routes, use named outlets (`<Outlet name="@sidebar" />` is
+equivalent to `<ParallelOutlet name="@sidebar" />`). Slot content is defined
+with `parallel()` — see `/parallel`.
 
 ```typescript
 import { Outlet, ParallelOutlet } from "@rangojs/router/client";
@@ -143,40 +159,40 @@ function DashboardLayout() {
 
 ## Orphan Layout (inside route)
 
-A layout as a child of `path()` wraps the route content and can read
-data set by the route handler via `ctx.get()`. The handler always
-executes before its children.
-
-This is the recommended way to pass handler data downward, and it is
-safe under partial action revalidation with zero configuration: orphan
-layouts (and their parallels) belong to the route entry, and on an
-action the whole entry re-runs together by default — route segment,
-loaders, and `belongsToRoute` children all seed revalidate-true, with
-handler-first ordering preserved. Producer and consumer cannot desync
-unless you narrow one side with a predicate that returns a hard `false`
-(then put the same contract on both — see "Revalidation Contracts").
-
-Data from an **outer** handler or layout entry is the opposite case:
-outer entries do not revalidate on actions by default (parent-chain
-skip). If an orphan layout depends on data established above its own
-route entry, that outer segment must share a revalidation contract, or
-the orphan must guard/reload the data independently. See `/rango` →
+A layout declared inside a `path()` (an "orphan" layout) wraps that route's
+content and can read what the route handler stored with `ctx.set()`. The
+handler always executes before its orphan layouts and their parallels.
+
+This is the recommended way to pass handler data downward. It needs no
+revalidation setup: orphan layouts and their parallels belong to the route
+entry, so on an action the route segment, its loaders, and these children all
+re-run together, handler first. They can only desync if you narrow one side
+with a predicate that returns a hard `false` — then put the same contract on
+both (see "Revalidation Contracts").
+
+Data from an **outer** handler or layout entry is the opposite case: outer
+entries are skipped on actions by default. If an orphan layout depends on data
+set above its own route entry, give that outer segment a shared revalidation
+contract, or have the orphan load/guard the data itself. See `/rango` →
 "Passing data down the tree" for the full safest-first ladder.
 
 ```typescript
+import { createVar } from "@rangojs/router";
 import { Outlet, ParallelOutlet } from "@rangojs/router/client";
 
+const CurrentProduct = createVar<Product>();
+
 urls(({ path, layout, parallel }) => [
-  path("/product/:slug", (ctx) => {
+  path("/product/:slug", async (ctx) => {
     const product = await fetchProduct(ctx.params.slug);
-    ctx.set("product", product);
+    ctx.set(CurrentProduct, product);
     return <ProductPage product={product} />;
   }, { name: "product" }, () => [
     layout((ctx) => {
-      const product = ctx.get("product");
+      const product = ctx.get(CurrentProduct); // Product | undefined
       return (
         <div>
-          <Breadcrumb name={product?.name} />
+          <ProductHeader name={product?.name} />
           <Outlet />
           <ParallelOutlet name="@related" />
         </div>
@@ -184,7 +200,7 @@ urls(({ path, layout, parallel }) => [
     }, () => [
       parallel({
         "@related": (ctx) => {
-          const product = ctx.get("product");
+          const product = ctx.get(CurrentProduct);
           return <RelatedProducts category={product?.category} />;
         },
       }),
@@ -193,36 +209,65 @@ urls(({ path, layout, parallel }) => [
 ])
 ```
 
-Orphan layouts can call `ctx.get()` to read data set by their parent
-handler. They can also call `ctx.set()`, though the primary pattern is
-for route handlers and middleware to write context variables and for
-orphan layouts to read them.
+Orphan layouts can also call `ctx.set()` for their own children, but the usual
+split is: middleware and route handlers write, orphan layouts and parallels
+read.
+
+Keep orphan layouts flat. A layout with no routes cannot contain another
+`layout()`, directly or inside a `middleware(fn, () => [...])` wrapper;
+`router.routes()` throws. Sibling layouts nest in declaration order, and a
+sibling `middleware(fn)` runs for the whole route either way:
+
+```typescript
+path("/account", AccountPage, { name: "account" }, () => [
+  middleware(requireAuth),
+  layout(<AccountShell />), // wraps AccountNav
+  layout(<AccountNav />), // wraps AccountPage
+]);
+```
+
+A `cache()` inside an orphan layout caches the whole path, like a `cache()`
+among the path's children (`/caching`).
 
 ## Layout Revalidation
 
-Standalone `layout()` entries don't revalidate by default — on an action,
-parent-chain segments are skipped unless a `revalidate()` opts them in.
-(Orphan layouts inside a `path()` are the opposite: they ride along with
-the route entry by default.) Control with `revalidate()`:
+A standalone `layout()` renders when it is first mounted and is then kept as-is:
 
-```typescript
-layout(<ShopLayout />, () => [
-  // Never revalidate (default behavior)
-  revalidate(() => false),
+- **Navigation** between routes it already wraps does not re-render it — even
+  when the URL params change.
+- **Actions** skip it too (the revalidation trace calls this
+  `action:parent-chain-skip`).
 
-  path("/shop", ShopIndex, { name: "shop" }),
-])
+Orphan layouts inside a `path()` are the opposite: they belong to the route
+entry and re-render with it (on param/search changes and on every action).
+
+Opt a standalone layout in with `revalidate()`. Return `true` to re-render,
+or `undefined` to defer to the default:
 
-// Or revalidate based on conditions
+```typescript
 import * as CartActions from "./actions/cart";
 
+// Re-render after any cart action
 layout(<CartLayout />, () => [
   revalidate((ctx) => ctx.isAction(CartActions) || undefined),
 
   path("/cart", CartPage, { name: "cart" }),
 ])
+
+// Re-render when a param the layout displays changes
+layout(LocaleLayout, () => [
+  revalidate(({ currentParams, nextParams }) =>
+    currentParams.locale !== nextParams.locale || undefined,
+  ),
+
+  path("/:locale/shop", ShopIndex, { name: "shop" }),
+])
 ```
 
+`revalidate(() => false)` on a standalone layout only restates the default.
+The return shapes (hard boolean, soft `{ defaultShouldRevalidate }`, or defer)
+are covered in `/loader` → "`revalidate()` return shapes".
+
 If child segments read data that was established by this layout or by a
 route handler above them, revalidate the outer segment too. Partial
 revalidation does not re-run non-revalidated ancestors just to rebuild
@@ -240,9 +285,11 @@ consumer segments:
 
 ```typescript
 // revalidation-contracts.ts
+import type { Revalidate } from "@rangojs/router";
 import { addToCart } from "./actions/cart";
 
-export const revalidateCartData = (ctx) => ctx.isAction(addToCart) || undefined;
+export const revalidateCartData: Revalidate = (ctx) =>
+  ctx.isAction(addToCart) || undefined;
 ```
 
 ```typescript
@@ -254,6 +301,10 @@ layout(<CartLayout />, () => [
 ]);
 ```
 
+On the layout the contract adds the re-render the default skips after an
+action. The route segment already re-runs after every action, so there it
+changes nothing by default; the shared name documents the dependency.
+
 If a segment depends on multiple upstream domains, compose multiple
 contracts (`revalidateAuthData`, `revalidateCartData`, and so on).
 
@@ -261,10 +312,10 @@ You can also package them as importable handoff helpers:
 
 ```typescript
 // revalidation-contracts.ts
-import { revalidate } from "@rangojs/router";
+import { revalidate, type Revalidate } from "@rangojs/router";
 import * as AuthActions from "./actions/auth";
 
-export const revalidateAuthData = (ctx) =>
+export const revalidateAuthData: Revalidate = (ctx) =>
   ctx.isAction(AuthActions) || undefined;
 export const revalidateAuth = () => [revalidate(revalidateAuthData)];
 ```
@@ -281,8 +332,8 @@ layout(<ShellLayout />, () => [
 ## Complete Example
 
 ```typescript
-import { urls } from "@rangojs/router";
-import { Outlet, ParallelOutlet } from "@rangojs/router/client";
+import { urls, Breadcrumbs } from "@rangojs/router";
+import { Link, Outlet, ParallelOutlet } from "@rangojs/router/client";
 import * as CartActions from "./actions/cart";
 
 function ShopLayout() {
@@ -290,8 +341,8 @@ function ShopLayout() {
     <div className="shop">
       <ParallelOutlet name="@promoBanner" />
       <nav>
-        <a href="/shop">Home</a>
-        <a href="/shop/cart">Cart</a>
+        <Link to="/shop">Home</Link>
+        <Link to="/shop/cart">Cart</Link>
       </nav>
       <div className="content">
         <aside>
@@ -311,9 +362,12 @@ export const shopPatterns = urls(({ path, layout, parallel, loader, revalidate }
     push({ label: "Shop", href: "/shop" });
     return <ShopLayout />;
   }, () => [
-    // Layout loaders
+    // Layout loaders: after an action, re-run only for cart actions;
+    // on navigation, undefined keeps the default
     loader(CartLoader, () => [
-      revalidate((ctx) => ctx.isAction(CartActions) || undefined),
+      revalidate((ctx) =>
+        ctx.isAction() ? ctx.isAction(CartActions) : undefined,
+      ),
     ]),
 
     // Parallel routes
@@ -335,6 +389,8 @@ export const shopPatterns = urls(({ path, layout, parallel, loader, revalidate }
 Layout handlers can carry their own middleware, default parallels, and includes via `.use` so a layout becomes a self-contained unit reusable across mount sites.
 
 ```typescript
+import { middleware, parallel, type Handler } from "@rangojs/router";
+
 const AdminLayout: Handler = (ctx) => {
   const user = ctx.get(CurrentUser);
   return <Admin user={user} />;

package/skills/links/SKILL.md

@@ -6,9 +6,12 @@ argument-hint: [ctx.reverse|href|useHref|useMount|useReverse|scopedReverse]
 
 # Links & URL Generation
 
-@rangojs/router provides different href APIs for server and client contexts.
+Use this skill to generate URLs to your own routes by name (server) or by
+typed path (client), and to keep links correct when a module is mounted under
+a different `include()` prefix. For route typing setup see `/typesafety`; for
+links to JSON/text endpoints see `/response-routes`.
 
-**Default server API: `ctx.reverse()`.** Generate URLs from the handler context — it's typed, auto-fills mount params, and resolves local (`.name`) and absolute (`name.sub`) names.
+**Default server API: `ctx.reverse()`.** Generate URLs from the handler context — it's typed, auto-fills params from the current request, and resolves local (`.name`) and global (`name`) names. In middleware and response routes it takes global names only (see below).
 
 **On the client, two patterns:**
 
@@ -19,10 +22,19 @@ argument-hint: [ctx.reverse|href|useHref|useMount|useReverse|scopedReverse]
 
 ## Server: ctx.reverse()
 
-Available in route handlers via HandlerContext. Resolves named routes using the full route map. This is the default way to generate URLs on the server.
+Available on the handler context (route handlers, layouts, parallels), on
+middleware and loader contexts, and on `getRequestContext()` inside server
+actions. Resolves named routes using the full route map. This is the default
+way to generate URLs on the server. Patterns in the map already include the
+router `basename`, so results are basename-prefixed.
+
+Middleware and response routes (`path.json()`, `path.text()`, …) get a
+global-only `ctx.reverse` (`GlobalReverseFunction`): no `include()` scope and no
+param auto-fill, so pass the fully qualified name and every param. A dot-local
+`.name` is a type error there. See `/middleware` and `/response-routes`.
 
 ```typescript
-import { urls, scopedReverse } from "@rangojs/router";
+import { urls } from "@rangojs/router";
 
 export const shopPatterns = urls(({ path, layout }) => [
   layout(<ShopLayout />, () => [
@@ -63,7 +75,7 @@ path("/product/:slug", (ctx) => {
 
 ### Local names (dot-prefixed)
 
-Prefix a name with `.` to resolve it within the current `include()` scope. The route is looked up using the include's mount namespace.
+Prefix a name with `.` to resolve it within the current `include()` scope. The route is looked up using the include's mount namespace. If the name is not found there, lookup walks up the enclosing include scopes (`shop.admin.x`, then `shop.x`). It falls back to a bare root-level name only for root-scoped routes (top-level routes and routes under `{ name: "" }` mounts); inside a named mount, a dot-local name never leaks into unrelated global names.
 
 ```typescript
 // urls/magazine.tsx — mounted at include("/magazine", magazinePatterns, { name: "magazine" })
@@ -97,7 +109,7 @@ export const tenantPatterns = urls(({ path }) => [
 ]);
 ```
 
-Auto-fill uses `{ ...ctx.params, ...hrefParams }` — current request params are defaults, explicit params win. Params not needed by the target route are silently ignored.
+Auto-fill uses `{ ...ctx.params, ...hrefParams }` — current request params are defaults, explicit params win. Params not needed by the target route are silently ignored. Because every current param is a default, drop an optional one explicitly with `undefined` or `""` — under `include("/:locale?", ...)` on `/en/...`, a bare `ctx.reverse("menu.index")` keeps `/en`, while `ctx.reverse("menu.index", { locale: undefined })` returns `/` (see `/i18n`). A missing required param throws `Missing param "slug" for route "…"`; an unknown name throws `Unknown route: "…"`.
 
 ### Global names (unprefixed)
 
@@ -112,7 +124,7 @@ Unprefixed names resolve against the full named-routes map (the generated `route
 
 ### reverse with search params
 
-When a route has a `search` schema, pass a typed search object as the third argument:
+When a route has a `search` schema, pass a typed search object as the third argument. `undefined`/`null` values are skipped; keys keep insertion order:
 
 ```typescript
 path("/search", (ctx) => {
@@ -124,7 +136,7 @@ path("/search", (ctx) => {
 
 ### scopedReverse() - type-safe ctx.reverse
 
-Wraps `ctx.reverse` with local route type information for autocomplete and validation. Runtime behavior is identical to `ctx.reverse` — `scopedReverse` is a type-only cast. The same dot-prefix rule applies: local names use `.name`, global names use `name.sub`.
+Wraps `ctx.reverse` with the module's local route types for autocomplete and validation. Runtime behavior is identical to `ctx.reverse` — `scopedReverse` is a type-only cast, and it also works on loader contexts. Don't use it on middleware or response-route contexts: their `ctx.reverse` has no `include()` scope, so the local names it types would throw `Unknown route`. Always call local names with the dot: the returned function is typed only against the module's local map, so an unprefixed local name (`reverse("cart")`) type-checks but is resolved as a global name at runtime — it throws `Unknown route` unless a global route of that exact name happens to exist.
 
 ```typescript
 import { scopedReverse } from "@rangojs/router";
@@ -134,12 +146,15 @@ path("/product/:slug", (ctx) => {
 
   reverse(".cart");                        // Local name (dot-prefixed) — resolves in include scope
   reverse(".product", { slug: "widget" }); // Local name with params
-  reverse("blog.post", { slug: "hi" });    // Global name (dotted) — full route map
+
+  ctx.reverse("blog.post", { slug: "hi" }); // Global names: call ctx.reverse directly
 
   return <ProductPage slug={ctx.params.slug} />;
 }, { name: "product" })
 ```
 
+To type local and global names on one function, type the handler with the module's generated map instead: `Handler<"shop.product", routes>` (see `/typesafety`).
+
 `reverse()` does not accept raw path strings (`"/about"`). For static paths in client components, use `href("/about")`; on the server, look up the route by name.
 
 ## Client components: receive URLs as props
@@ -150,9 +165,12 @@ path("/product/:slug", (ctx) => {
 
 ```tsx
 // server
-function BlogPostPage(ctx: HandlerContext) {
+import type { Handler } from "@rangojs/router";
+import { ShareButton } from "./share-button";
+
+export const BlogPostPage: Handler<{ slug: string }> = (ctx) => {
   return <ShareButton url={ctx.reverse(".post", { slug: ctx.params.slug })} />;
-}
+};
 ```
 
 ```tsx
@@ -169,6 +187,8 @@ export function ShareButton({ url }: { url: string }) {
 
 ```tsx
 // server — loaders/nav.ts
+import { createLoader } from "@rangojs/router";
+
 export const NavLoader = createLoader((ctx) => ({
   home: ctx.reverse("home"),
   blog: ctx.reverse("blog.index"),
@@ -182,6 +202,8 @@ const urlpatterns = urls(({ path, loader }) => [
 
 ```tsx
 "use client";
+import { Link, useLoader } from "@rangojs/router/client";
+import { NavLoader } from "../loaders/nav";
 
 function Nav() {
   const { data } = useLoader(NavLoader);
@@ -195,6 +217,7 @@ function Nav() {
 
 ```tsx
 "use server";
+import { getRequestContext } from "@rangojs/router";
 
 export async function getProductUrl(slug: string) {
   const ctx = getRequestContext();
@@ -237,7 +260,9 @@ import { href } from "@rangojs/router/client";
 export const appHref = (path: Rango.Path): string => href(path);
 ```
 
-`href()` is a raw path helper — it is **not** basename-aware. It returns the path as-is (or with the include mount prefix via `useHref()`). For basename-aware navigation, use `Link`, `useRouter().push()`, or `reverse()`, which auto-prefix root-relative paths with the router's basename.
+`href()` is a raw path helper — it is **not** basename-aware. It returns the path as-is (or with the include mount prefix via `useHref()`). `<Link to={href("/about")}>` still lands on the basename-prefixed URL because `Link` and `useRouter().push()` prefix root-relative paths with the router's basename; a plain `<a href>`, `fetch()`, or `window.location` gets the raw path. On the server, `ctx.reverse()` output is already basename-prefixed.
+
+`href.json()`, `href.text()`, `href.html()`, `href.xml()`, `href.md()`, `href.image()`, `href.stream()` and `href.any()` return `{ to, "data-external": "" }` props for linking to response routes with a hard navigation — see `/response-routes`.
 
 ## Client: useHref()
 
@@ -263,6 +288,8 @@ function ShopNav() {
 
 Use `useHref()` for local navigation within a mounted module. Use the bare `href()` function for absolute paths outside the current mount.
 
+`useHref()` concatenates the mount **pattern** as-is and does not substitute params, and its argument is not checked against your routes. Under a parameterized mount (`include("/tenant/:tenantId", ...)`) it would produce `/tenant/:tenantId/cart` — use `useReverse(routes)` there, which substitutes mount params from `useParams()`.
+
 ## Client: useMount()
 
 Returns the current `include()` mount path. Useful for building custom logic based on mount location.
@@ -279,7 +306,7 @@ function MountInfo() {
 }
 ```
 
-`useMount()` reads from `MountContext`, which is automatically set by `include()` in the segment tree.
+`useMount()` reads from `MountContext`, which is automatically set by `include()` in the segment tree. Nested includes return the nearest mount's full URL prefix (e.g. `/shop/admin`), and a parameterized include returns its pattern (`/tenant/:tenantId`), not the matched URL. `href(path, mount)` is the non-hook equivalent of `useHref()`.
 
 ## Client: useReverse(routes)
 
@@ -309,7 +336,9 @@ export function BlogNav() {
 1. Strips an optional leading `.` and looks up the name in the imported `routes` map.
 2. Joins the local pattern with the surrounding `useMount()` value — the include's URL pattern.
 3. Substitutes params: explicit params from the call, then auto-filled from `useParams()` for anything still unresolved (mount params like `:tenantId` flow in this way).
-4. Appends a query string if a search object is passed and the route has a `search` schema.
+4. Appends a query string when a search object is passed (typed from the route's `search` schema; `undefined`/`null` values are skipped).
+
+The returned function is memoized on the routes map, mount, and current params, so it is safe to pass to memoized children.
 
 ### Mount-relativity
 
@@ -337,13 +366,16 @@ The `/` pattern under a non-root mount collapses cleanly: under `/news`, `revers
 When the include itself carries `:params`, those are auto-filled from `useParams()` so the caller doesn't have to thread them through:
 
 ```typescript
+// urls/tenant.tsx: index "/" and post "/posts/:postId"
 // urls.tsx
-include("/tenant/:tenantId", clientReversePatterns, { name: "tenant" });
+include("/tenant/:tenantId", tenantPatterns, { name: "tenant" });
 ```
 
 ```tsx
+import { routes as tenantRoutes } from "../urls/tenant.gen.js";
+
 // At /tenant/acme/posts/p1, useParams() = { tenantId: "acme", postId: "p1" }
-const reverse = useReverse(clientReverseRoutes);
+const reverse = useReverse(tenantRoutes);
 
 reverse(".index"); // "/tenant/acme"
 reverse(".post", { postId: "p2" }); // "/tenant/acme/posts/p2"   (tenantId auto-filled)
@@ -411,7 +443,7 @@ pnpm exec rango generate src/urls --static
 
 Don't edit the file by hand — re-run codegen when patterns change.
 
-**Today the Vite plugin only regenerates the router-level `*.named-routes.gen.ts`.** Per-module `urls/*.gen.ts` files are emitted only by the CLI (or `writePerModuleRouteTypesForFile` programmatically). Commit the generated files and re-run `rango generate` whenever a `urls()` module's `path()`/`include()` shape changes. A common workflow is to wire it into a `predev` script:
+**The Vite plugin only regenerates the router-level `*.named-routes.gen.ts`.** Per-module `urls/*.gen.ts` files are emitted only by the `rango generate` CLI. Commit the generated files and re-run `rango generate` whenever a `urls()` module's `path()`/`include()` shape changes. `clientUrls()` modules get a `.gen.ts` the same way. A common workflow is to wire it into a `predev` script:
 
 ```jsonc
 // package.json
@@ -452,7 +484,7 @@ queued or in flight; removing it re-arms both Link types.
 | Context          | API                                                | Resolves                                  | Use for                                                          |
 | ---------------- | -------------------------------------------------- | ----------------------------------------- | ---------------------------------------------------------------- |
 | Server handler   | `ctx.reverse("name")`                              | Named routes (local + absolute)           | **Default** server-side URL generation                           |
-| Server handler   | `scopedReverse<T>(ctx.reverse)`                    | Same, with type safety                    | Type-safe server URLs                                            |
+| Server handler   | `scopedReverse<T>(ctx.reverse)`                    | Local `.name` routes, typed from `T`      | Type-safe in-module server URLs                                  |
 | Client component | `useReverse(routes)`                               | Local names from an imported `routes` map | Typed in-module URL generation without round-tripping the server |
 | Client component | (URL passed as prop / loader data / action return) | Named routes                              | Cross-module URLs or one-off names you don't want to import      |
 | Client component | `href("/path")`                                    | Absolute paths (static strings)           | Static navigation where no named-route lookup is needed          |
@@ -470,7 +502,7 @@ import { urls, scopedReverse } from "@rangojs/router";
 export const shopPatterns = urls(({ path, layout }) => [
   layout((ctx) => {
     const reverse = scopedReverse<typeof shopPatterns>(ctx.reverse);
-    return <ShopLayout cartUrl={reverse("cart")} />;
+    return <ShopLayout cartUrl={reverse(".cart")} />;
   }, () => [
     path("/", ShopIndex, { name: "index" }),
     path("/cart", CartPage, { name: "cart" }),