@rangojs/router 0.0.0-experimental.10 → 0.0.0-experimental.101

package/skills/intercept/SKILL.md

@@ -8,6 +8,9 @@ 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.
 
+Canonical semantics reference:
+[docs/execution-model.md](../../docs/internal/execution-model.md)
+
 ## Basic Intercept
 
 ```typescript
@@ -45,11 +48,11 @@ export const urlpatterns = urls(({ path, layout, intercept, loader }) => [
 
 ## Navigation Behavior
 
-| Navigation Type | What Renders |
-|-----------------|--------------|
+| Navigation Type                | What Renders                                         |
+| ------------------------------ | ---------------------------------------------------- |
 | Click link `/shop/product/abc` | `<ProductModal />` in `@modal`, background preserved |
-| Direct URL `/shop/product/abc` | Full `<ProductPage />` page |
-| Browser back | Close modal, restore previous state |
+| Direct URL `/shop/product/abc` | Full `<ProductPage />` page                          |
+| Browser back                   | Close modal, restore previous state                  |
 
 ## Intercept with Layout
 
@@ -68,6 +71,78 @@ intercept(
 )
 ```
 
+## 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
+```
+
+```typescript
+intercept(
+  "@modal",
+  "product",
+  <ProductModal />,
+  () => [
+    middleware(async (ctx, next) => {
+      // Runs only for this intercept, after global and route middleware
+      ctx.set("interceptSource", "modal");
+      await next();
+    }),
+    loader(ProductLoader),
+  ]
+)
+```
+
+The intercept handler can read context variables set by all upstream middleware layers (global, route, and intercept-specific).
+
+Handler/layout `ctx.set()` data follows the same rule as elsewhere:
+intercepts see data produced in the current render pass, but partial
+action revalidation only recomputes segments that actually revalidate.
+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.
+
+### Revalidation Contracts for Intercept Dependencies
+
+Use named revalidation contracts on both the outer producer and the intercept
+consumer when they share `ctx.set()` data:
+
+```typescript
+export const revalidateProductShell = ({ actionId }) =>
+  actionId?.includes("src/actions/product.ts#") ?? false;
+
+layout(ProductLayout, () => [
+  revalidate(revalidateProductShell), // producer reruns
+  intercept("@modal", "product", <ProductModal />, () => [
+    revalidate(revalidateProductShell), // consumer reruns
+    loader(ProductLoader),
+  ]),
+]);
+```
+
+Compose multiple contracts if the intercept depends on multiple upstream
+domains.
+
+Helper handoff style keeps intercept trees terse:
+
+```typescript
+import { revalidate } from "@rangojs/router";
+
+export const revalidateProduct = () => [
+  revalidate(revalidateProductShell),
+];
+
+layout(ProductLayout, () => [
+  revalidateProduct(),
+  intercept("@modal", "product", <ProductModal />, () => [
+    revalidateProduct(),
+    loader(ProductLoader),
+  ]),
+]);
+```
+
 ## Conditional Intercept with when()
 
 Only intercept based on navigation context:
@@ -106,15 +181,15 @@ Use navigation to close:
 
 ```typescript
 "use client";
-import { useNavigation } from "@rangojs/router/client";
+import { useRouter } from "@rangojs/router/client";
 
 function ModalWrapper({ children }) {
-  const { goBack } = useNavigation();
+  const router = useRouter();
 
   return (
-    <div className="modal-overlay" onClick={goBack}>
+    <div className="modal-overlay" onClick={() => router.back()}>
       <div className="modal" onClick={(e) => e.stopPropagation()}>
-        <button onClick={goBack}>Close</button>
+        <button onClick={() => router.back()}>Close</button>
         {children}
       </div>
     </div>
@@ -122,6 +197,79 @@ function ModalWrapper({ children }) {
 }
 ```
 
+## Interaction with View Transitions
+
+A layout that owns the `@modal` slot can also configure `transition()` for page
+fades — opening a modal does **not** fire the layout's view transition. Rango
+narrows the layout's `<ViewTransition>` wrap to the layout's default outlet
+content, so `<ParallelOutlet />` (the slot where the modal mounts) is a sibling
+of the wrap, not inside its subtree. Form actions submitted from inside an open
+modal also commit without firing the underlying layout's transition, and the
+modal subtree identity is preserved across revalidation (no remount,
+`useActionState` survives). Closing the modal restores the page without a
+stray transition.
+
+For a modal-only morph (e.g. when intercepted URLs change while the modal
+stays open), use an element-level React `<ViewTransition>` inside the modal
+component — `transition()` accepted on `intercept()` via the DSL is not
+applied to slot rendering today.
+
+Caveat: route-level `transition()` wraps the route component itself, so a
+`<ParallelOutlet />` rendered directly inside that route component would still
+be inside the route's VT subtree. Mount the slot in a layout instead when you
+combine intercept modals with route-level transitions.
+
+See [skills/view-transitions](../view-transitions/SKILL.md) for the full
+contract and direction-aware examples.
+
+## Interaction with Prerender
+
+When the target route of an intercept uses `Prerender`, the intercept handler is
+also resolved at build time and stored alongside the main pre-rendered segments.
+This means intercept navigations to pre-rendered routes are served from the
+prerender store without executing handler code at runtime.
+
+```typescript
+// The detail route is pre-rendered
+export const ProductDetail = Prerender(
+  async () => [{ slug: "shoes" }, { slug: "jacket" }],
+  async (ctx) => <ProductPage slug={ctx.params.slug} />,
+);
+
+// urls.tsx
+layout(ShopLayout, () => [
+  path("/:slug", ProductDetail, { name: "detail" }, () => [
+    loader(ProductLoader),
+  ]),
+
+  // This intercept is also pre-rendered at build time
+  intercept("@modal", ".detail", <ProductModal />, () => [
+    when(({ from }) => from.pathname.startsWith("/shop")),
+    loader(ProductLoader),
+  ]),
+])
+```
+
+Build-time behavior:
+
+- The intercept handler (`<ProductModal />`) is resolved with BuildContext
+- Result is stored under the key `"detail/paramHash/i"` (intercept variant)
+- `when()` conditions are skipped at build time (all intercepts pre-rendered unconditionally)
+- `when()` is still evaluated at runtime by the intercept-resolution middleware
+
+Runtime behavior:
+
+- Intercept navigation: prerender store serves the `/i` variant (frozen handler + fresh loaders)
+- Direct navigation: prerender store serves the main variant (full page)
+- If no intercept prerender entry exists, falls through to live intercept resolution
+
+Loaders inside the intercept always run fresh at request time, same as regular
+pre-rendered routes.
+
+During action-driven partial revalidation, this same partial rule applies:
+refreshing the intercept does not implicitly rebuild non-revalidated outer
+segments.
+
 ## Complete Example
 
 ```typescript
@@ -188,3 +336,23 @@ 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`/`when` defaults via `.use` — useful for self-contained modal components that travel with their own data and chrome.
+
+```typescript
+const QuickViewModal: Handler = async (ctx) => {
+  const product = await ctx.use(ProductLoader);
+  return <QuickView product={product} />;
+};
+QuickViewModal.use = () => [
+  loader(ProductLoader),
+  loading(<QuickViewSkeleton />),
+  layout(<ModalChrome />),
+];
+
+intercept("@modal", "product", QuickViewModal);
+```
+
+Explicit `use()` at the mount site merges with `handler.use` (handler defaults first, explicit second). See [skills/handler-use](../handler-use/SKILL.md) for merge order and the per-mount-site allowed-types table.

package/skills/layout/SKILL.md

@@ -8,6 +8,9 @@ argument-hint: [component]
 
 Layouts wrap child routes and persist during navigation within their scope.
 
+Canonical semantics reference:
+[docs/execution-model.md](../../docs/internal/execution-model.md)
+
 ## Basic Layout
 
 ```typescript
@@ -45,9 +48,7 @@ layout(<ShopLayout />, () => [
 ### Component Function
 
 ```typescript
-layout(ShopLayout, () => [
-  path("/shop", ShopIndex, { name: "shop" }),
-])
+layout(ShopLayout, () => [path("/shop", ShopIndex, { name: "shop" })]);
 ```
 
 ### Handler with Context
@@ -117,6 +118,8 @@ function ShopLayout() {
 }
 ```
 
+A layout's `transition()` config wraps the content that flows through `<Outlet />` — not the layout chrome itself, and not sibling `<ParallelOutlet />` slots. Stacking transitions across nested layouts collapses around the deepest default outlet content. See [skills/view-transitions](../view-transitions/SKILL.md) for the full wrap rules and intercept-modal interaction.
+
 ## Named Outlets
 
 For parallel routes, use named outlets:
@@ -141,6 +144,54 @@ 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 handler-first guarantee applies to a single full render pass
+(initial render, prerender, or full HTML re-render). During partial
+action revalidation, only the segments that revalidate are recomputed.
+If an orphan layout depends on data established by an outer handler or
+layout, that outer segment must also revalidate, or the orphan must
+guard/reload the data independently.
+
+```typescript
+import { Outlet, ParallelOutlet } from "@rangojs/router/client";
+
+urls(({ path, layout, parallel }) => [
+  path("/product/:slug", (ctx) => {
+    const product = await fetchProduct(ctx.params.slug);
+    ctx.set("product", product);
+    return <ProductPage product={product} />;
+  }, { name: "product" }, () => [
+    layout((ctx) => {
+      const product = ctx.get("product");
+      return (
+        <div>
+          <Breadcrumb name={product?.name} />
+          <Outlet />
+          <ParallelOutlet name="@related" />
+        </div>
+      );
+    }, () => [
+      parallel({
+        "@related": (ctx) => {
+          const product = ctx.get("product");
+          return <RelatedProducts category={product?.category} />;
+        },
+      }),
+    ]),
+  ]),
+])
+```
+
+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.
+
 ## Layout Revalidation
 
 Layouts don't revalidate by default. Control with `revalidate()`:
@@ -161,6 +212,54 @@ layout(<CartLayout />, () => [
 ])
 ```
 
+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
+their `ctx.set()` state.
+
+### Revalidation Contracts
+
+For shared upstream data, define named revalidation functions and reuse
+them on both producer and consumer segments:
+
+```typescript
+// revalidation-contracts.ts
+export const revalidateCartData = ({ actionId }) =>
+  actionId?.includes("src/actions/cart.ts#addToCart") ?? false;
+```
+
+```typescript
+layout(<CartLayout />, () => [
+  revalidate(revalidateCartData), // producer
+  path("/cart", CartPage, { name: "cart" }, () => [
+    revalidate(revalidateCartData), // consumer
+  ]),
+]);
+```
+
+If a segment depends on multiple upstream domains, compose multiple
+contracts (`revalidateAuthData`, `revalidateCartData`, and so on).
+
+You can also package them as importable handoff helpers:
+
+```typescript
+// revalidation-contracts.ts
+import { revalidate } from "@rangojs/router";
+
+export const revalidateAuthData = ({ actionId }) =>
+  actionId?.includes("src/actions/auth.ts#") ?? false;
+export const revalidateAuth = () => [revalidate(revalidateAuthData)];
+```
+
+```typescript
+layout(<ShellLayout />, () => [
+  revalidateAuth(),
+  path("/account", AccountPage, { name: "account" }, () => [
+    revalidateAuth(),
+  ]),
+]);
+```
+
 ## Complete Example
 
 ```typescript
@@ -211,3 +310,25 @@ export const shopPatterns = urls(({ path, layout, parallel, loader, revalidate }
   ]),
 ]);
 ```
+
+## Handler-attached `.use`
+
+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
+const AdminLayout: Handler = (ctx) => {
+  const user = ctx.get(CurrentUser);
+  return <Admin user={user} />;
+};
+AdminLayout.use = () => [
+  middleware(requireAdmin),
+  parallel({ "@adminNotifs": AdminNotifsSlot }),
+];
+
+// Mount site declares structure only; defaults travel with the layout.
+layout(AdminLayout, () => [
+  path("/admin", AdminIndex, { name: "admin.index" }),
+]);
+```
+
+Allowed item types in a layout's `.use` mirror the layout `use()` callback (the broadest set). Explicit `use()` at the mount site merges with `handler.use` (handler defaults first, explicit second). See [skills/handler-use](../handler-use/SKILL.md) for merge order and per-mount-site allowed types.