@rangojs/router 0.16.0 → 0.17.0

package/skills/intercept/SKILL.md

@@ -8,6 +8,18 @@ argument-hint: [@slot-name] [route-to-intercept]
 
 Intercept routes render a different component during soft navigation (client-side) while preserving the background route. Hard navigation (direct URL) shows the full page.
 
+`intercept(slot, routeName, handler, config?, use?)`:
+
+- `slot` — the `@name` slot the intercept renders into; the layout places it
+  with `<ParallelOutlet name="@modal" />`.
+- `routeName` — the target route. A dot prefix (`".product"`) resolves inside
+  the current `include()` scope; a bare name (`"product"`) is the global route
+  name. Declare the intercept in a layout that wraps the target route — the
+  router finds intercepts by walking up the target route's own layout chain.
+- `handler` — the component or handler rendered in the slot.
+- `config` — optional `{ when }` (see "Conditional Intercept"); pass the `use`
+  callback as the 4th argument when there is no config.
+
 ## Not this skill if…
 
 - You want a slot that ALWAYS renders alongside the page (sidebar, multi-column
@@ -60,7 +72,8 @@ export const urlpatterns = urls(({ path, layout, intercept, loader, loading }) =
 
 ## Intercept with Layout
 
-Wrap intercept content in a modal layout:
+Wrap intercept content in a modal layout. The layout renders the intercept
+content through `<Outlet />` (not a `children` prop):
 
 ```typescript
 intercept(
@@ -68,21 +81,29 @@ intercept(
   "product",
   <ProductModalContent />,
   () => [
-    layout(<ModalWrapper />),  // Wraps the modal content
+    layout(<ModalWrapper />),  // Wraps the modal content via <Outlet />
     loader(ProductLoader),
     loading(<ProductModalSkeleton />),
   ]
 )
 ```
 
+Only the first `layout()` in an intercept's `use()` is applied. It is modal
+chrome only: a `layout(Chrome, () => [...])` with its own `use()` items throws.
+Attach loaders and the rest to the intercept itself.
+
 ## Intercept Middleware
 
 Intercepts support their own middleware chain via the use callback. The full chain for an intercept request is:
 
 ```
-global mw (router.use) -> route mw (urls middleware()) -> intercept mw -> intercept handler -> intercept loaders
+global mw (router.use) -> route mw (urls middleware()) -> intercept mw -> intercept loaders + handler
 ```
 
+The intercept's loaders are started before its handler is called, so they run
+in parallel with it. If intercept middleware returns a `Response` (e.g. a
+redirect), the intercept stops there.
+
 ```typescript
 intercept(
   "@modal",
@@ -108,22 +129,55 @@ If an intercept depends on data established by an outer layout/handler,
 revalidate that outer segment too or reload/guard the data inside the
 intercept.
 
+### Revalidating an Intercept
+
+An intercept has no segment-level `revalidate()`. Its handler and layout
+re-render every time the intercept resolves live — each intercepted
+navigation, and each action submitted while the modal is open. When the
+segment cache or a prerendered intercept variant serves the modal, the stored
+handler output is reused and only the loaders run. Each loader decides for
+itself through its own `revalidate()`, with the normal loader defaults.
+
+A `revalidate()` placed directly in the intercept's `use()` (or returned from
+its handler's `.use`) throws at definition time. Attach it to the loader:
+
+```typescript
+// Throws: revalidate() is not valid inside intercept("@modal", "product") use()
+intercept("@modal", "product", <ProductModal />, () => [
+  revalidate(() => false),
+  loader(ProductLoader),
+]);
+
+// Correct: the loader owns the decision
+intercept("@modal", "product", <ProductModal />, () => [
+  loader(ProductLoader, () => [revalidate(() => false)]),
+]);
+```
+
 ### Revalidation Contracts for Intercept Dependencies
 
-Use named revalidation contracts on both the outer producer and the intercept
-consumer when they share `ctx.set()` data:
+When an outer layout produces `ctx.set()` data that the intercept reads, the
+producer is the side that needs a contract: outer layouts are skipped during
+partial action revalidation unless they opt in. The intercept side needs none
+by default — its handler re-renders on every action while the modal is open,
+and its loaders re-run after every action. If you narrow an intercept loader
+with its own `revalidate()`, compose the producer's contract into it so the
+two stay in step:
 
 ```typescript
+import type { Revalidate } from "@rangojs/router";
 import * as ProductActions from "./actions/product";
 
-export const revalidateProductShell = (ctx) =>
+export const revalidateProductShell: Revalidate = (ctx) =>
   ctx.isAction(ProductActions) || undefined;
 
 layout(ProductLayout, () => [
   revalidate(revalidateProductShell), // producer reruns
   intercept("@modal", "product", <ProductModal />, () => [
-    revalidate(revalidateProductShell), // consumer reruns
-    loader(ProductLoader),
+    loader(ProductLoader, () => [
+      revalidate(revalidateProductShell), // reruns with the producer
+      revalidate(() => false), // otherwise keep the loaded data
+    ]),
   ]),
 ]);
 ```
@@ -143,17 +197,16 @@ export const revalidateProduct = () => [
 layout(ProductLayout, () => [
   revalidateProduct(),
   intercept("@modal", "product", <ProductModal />, () => [
-    revalidateProduct(),
-    loader(ProductLoader),
+    loader(ProductLoader, () => [revalidateProduct(), revalidate(() => false)]),
   ]),
 ]);
 ```
 
 ## Conditional Intercept with the `when` config
 
-Only intercept based on navigation context. `when` is the 4th argument
-(an `InterceptConfig` object); the other use-items go in the 5th-argument
-callback.
+Only intercept based on navigation context. `when` goes in the config object
+(4th argument); the use-items then move to the 5th-argument callback. The
+config type is not exported — pass an object literal.
 
 ```typescript
 intercept(
@@ -168,9 +221,19 @@ intercept(
 )
 ```
 
-`when` is a match-time selector receiving `{ from, to, params, segments, ... }`.
+`when` is a synchronous match-time selector. It receives `from` / `to` (URLs),
+`fromRouteName` / `toRouteName` (named routes only), `params` (the target's),
+`segments` (the client's current segment path and ids), `request`, and `env`.
 Pass an array of predicates for AND logic (all must return true). Omit `when`
-entirely and the intercept always activates.
+entirely and the intercept always activates. `when` is not re-evaluated during
+action revalidation, so an open modal stays open after an action.
+
+```typescript
+// Intercept only when opened from the shop index
+intercept("@modal", "product", <ProductModal />, {
+  when: ({ fromRouteName }) => fromRouteName === "index",
+})
+```
 
 ```typescript
 intercept(
@@ -204,22 +267,84 @@ intercept(
 )
 ```
 
+## What an Intercept's `use()` Accepts
+
+An intercept's `use()` (and its handler's `.use`) accepts:
+
+- `loader()`, with its own `revalidate()` and `cache()` inside it
+- `middleware()`
+- `loading()`
+- `layout(Chrome)`: the modal chrome, without `use()` items of its own
+- `route`, the item type a `path()` call produces
+- `transition()`
+
+Everything else throws at definition time with a pointer to where it goes:
+`revalidate()` onto the loader, `errorBoundary()` / `notFoundBoundary()` onto
+the enclosing layout (see below), and `cache()` onto the target route.
+
+## Caching an Intercept
+
+To cache a modal, put `cache()` on the target route (or a layout above it).
+An intercept navigation is cached under that scope with its own `intercept:`
+key, so it never collides with the full-page render of the same URL. For
+finer control, use `"use cache"` in the intercept handler, or cache the
+intercept's loader: `loader(ProductLoader, () => [cache()])`.
+
+## Errors in an Intercept
+
+An intercept has no boundary of its own. When the intercept's handler or one
+of its loaders throws, or calls `notFound()`, the modal slot renders the
+`errorBoundary()` / `notFoundBoundary()` of the layout or path that declares the
+intercept, or the nearest ancestor that has one. That holds when the declaring
+layout has no routes of its own, too: the lookup continues at the layout that
+holds it and that layout's ancestors. The intercepted route's own
+boundaries are not consulted: the modal renders in the declaring layout's slot,
+not in the route. On a handler error the modal layout and the background page
+stay mounted, and the status is 500 / 404. A thrown `Response` (`redirect()`)
+still short-circuits the navigation.
+
+With `loading()`, an async handler streams after the response has started, so
+its rejection is not caught on the server. Wrap the modal layout's `<Outlet />`
+in a client error boundary.
+
+An `errorBoundary()` or `notFoundBoundary()` placed directly in the intercept's
+`use()` (or returned from its handler's `.use`) throws at definition time. Put
+it on the enclosing layout:
+
+```typescript
+// Throws: errorBoundary() is not valid inside intercept("@modal", "product") use()
+intercept("@modal", "product", <ProductModal />, () => [
+  loader(ProductLoader),
+  errorBoundary(<ModalError />),
+]);
+
+// Correct: the declaring layout's boundaries handle the intercept's handler and loaders
+layout(<ShopLayout />, () => [
+  errorBoundary(<ShopError />),
+  notFoundBoundary(<ProductNotFound />),
+  intercept("@modal", "product", <ProductModal />, () => [
+    loader(ProductLoader),
+  ]),
+]);
+```
+
 ## Closing the Modal
 
 Use navigation to close:
 
 ```typescript
 "use client";
-import { useRouter } from "@rangojs/router/client";
+import { Outlet, useRouter } from "@rangojs/router/client";
 
-function ModalWrapper({ children }) {
+// Used as the intercept's layout: layout(<ModalWrapper />)
+export function ModalWrapper() {
   const router = useRouter();
 
   return (
     <div className="modal-overlay" onClick={() => router.back()}>
       <div className="modal" onClick={(e) => e.stopPropagation()}>
         <button onClick={() => router.back()}>Close</button>
-        {children}
+        <Outlet />
       </div>
     </div>
   );
@@ -305,10 +430,10 @@ segments.
 ## Complete Example
 
 ```typescript
-// components/ProductModal.tsx
+// components/shop-layout.tsx
 import { Outlet, ParallelOutlet } from "@rangojs/router/client";
 
-function ShopLayout() {
+export function ShopLayout() {
   return (
     <div className="shop">
       <ParallelOutlet name="@promoBanner" />
@@ -320,16 +445,23 @@ function ShopLayout() {
   );
 }
 
-function ModalWrapper({ children }) {
+// components/modal-wrapper.tsx (see "Closing the Modal" for a closable version)
+import { Outlet } from "@rangojs/router/client";
+
+export function ModalWrapper() {
   return (
     <div className="modal-overlay">
-      <div className="modal">{children}</div>
+      <div className="modal">
+        <Outlet />
+      </div>
     </div>
   );
 }
 
-// urls/shop.tsx
+// urls/shop.tsx — mounted with include("/shop", shopPatterns, { name: "shop" })
 import { urls } from "@rangojs/router";
+import { ShopLayout } from "../components/shop-layout";
+import { ModalWrapper } from "../components/modal-wrapper";
 
 export const shopPatterns = urls(({
   path,
@@ -338,6 +470,7 @@ export const shopPatterns = urls(({
   intercept,
   loader,
   loading,
+  cache,
 }) => [
   layout(<ShopLayout />, () => [
     parallel({
@@ -347,7 +480,7 @@ export const shopPatterns = urls(({
     // Intercept product detail into modal
     intercept(
       "@modal",
-      "product",  // Route name (without prefix)
+      ".product", // dot-local: resolves to "shop.product" in this include
       <ProductModalContent />,
       { when: ({ from }) => !from.pathname.startsWith("/shop/product/") },
       () => [
@@ -370,9 +503,11 @@ export const shopPatterns = urls(({
 
 ## Handler-attached `.use`
 
-Intercept handlers can carry their own middleware, loaders, loading state, error/notFound boundaries, and even nested `layout`/`route` defaults via `.use` — useful for self-contained modal components that travel with their own data and chrome. (Conditional activation is set via the `when` config on the mount-site `intercept()` call, not inside `.use`.)
+Intercept handlers can carry their own middleware, loaders, loading state, and even nested `layout`/`route` defaults via `.use` — useful for self-contained modal components that travel with their own data and chrome. (Conditional activation is set via the `when` config on the mount-site `intercept()` call, not inside `.use`; boundaries go on the enclosing layout, see [Errors in an Intercept](#errors-in-an-intercept).)
 
 ```typescript
+import { layout, loader, loading, type Handler } from "@rangojs/router";
+
 const QuickViewModal: Handler = async (ctx) => {
   const product = await ctx.use(ProductLoader);
   return <QuickView product={product} />;
@@ -380,7 +515,7 @@ const QuickViewModal: Handler = async (ctx) => {
 QuickViewModal.use = () => [
   loader(ProductLoader),
   loading(<QuickViewSkeleton />),
-  layout(<ModalChrome />),
+  layout(<ModalChrome />), // ModalChrome renders <Outlet />
 ];
 
 intercept("@modal", "product", QuickViewModal);

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} />;