@rangojs/router 0.0.0-experimental.2 → 0.0.0-experimental.21

package/skills/intercept/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: intercept
-description: Define intercept routes for modals, slide-overs, and soft navigation patterns in rsc-router
+description: Define intercept routes for modals, slide-overs, and soft navigation patterns in @rangojs/router
 argument-hint: [@slot-name] [route-to-intercept]
 ---
 
@@ -8,285 +8,306 @@ 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
-import { map } from "rsc-router/server";
-import { ParallelOutlet } from "rsc-router";
+import { urls } from "@rangojs/router";
+import { Outlet, ParallelOutlet } from "@rangojs/router/client";
 
-export default map<typeof routes>(({ route, layout, parallel, intercept, loader }) => [
-  layout(
-    () => (
-      <ShopLayout>
-        <Outlet />
-        <ParallelOutlet name="@modal" />
-      </ShopLayout>
+function ShopLayout() {
+  return (
+    <div className="shop">
+      <Outlet />
+      <ParallelOutlet name="@modal" />
+    </div>
+  );
+}
+
+export const urlpatterns = urls(({ path, layout, intercept, loader }) => [
+  layout(<ShopLayout />, () => [
+    // Intercept product detail - shows modal during soft navigation
+    intercept(
+      "@modal",              // Slot name
+      "product",             // Route name to intercept
+      <ProductModal />,      // Modal component
+      () => [
+        loader(ProductLoader),
+        loading(<ProductModalSkeleton />),
+      ]
     ),
-    () => [
-      // Define empty modal slot
-      parallel({
-        "@modal": () => null,
-      }),
-
-      // Intercept product detail into modal
-      intercept(
-        "@modal",                              // Slot name
-        "products.detail",                     // Route to intercept
-        (ctx) => <ProductModal id={ctx.params.id} />, // Modal component
-      ),
-
-      route("products.index", ProductList),
-      route("products.detail", ProductDetail), // Full page version
-    ]
-  ),
+
+    // Normal routes
+    path("/shop", ShopIndex, { name: "index" }),
+    path("/shop/product/:slug", ProductPage, { name: "product" }),
+  ]),
 ]);
 ```
 
 ## Navigation Behavior
 
-| Navigation Type | What Renders |
-|-----------------|--------------|
-| Click link `/product/abc` | `<ProductModal />` in `@modal`, background preserved |
-| Direct URL `/product/abc` | Full `<ProductDetail />` page |
-| Back button from modal | Modal closes, background restored |
-| Refresh in modal | Full page loads |
+| 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                  |
 
-## Intercept with Configuration
+## Intercept with Layout
+
+Wrap intercept content in a modal layout:
 
 ```typescript
 intercept(
   "@modal",
-  "products.detail",
-  async (ctx) => {
-    const product = await ctx.use(ProductLoader);
-    return <ProductModal product={product} />;
-  },
+  "product",
+  <ProductModalContent />,
   () => [
+    layout(<ModalWrapper />),  // Wraps the modal content
     loader(ProductLoader),
     loading(<ProductModalSkeleton />),
-    revalidate(({ actionId }) => actionId?.includes("cart") ?? false),
-    errorBoundary(<ModalErrorFallback />),
   ]
 )
 ```
 
-## Conditional Intercept with `when()`
+## Intercept Middleware
+
+Intercepts support their own middleware chain via the use callback. The full chain for an intercept request is:
 
-Only intercept under certain conditions:
+```
+global mw (router.use) -> route mw (urls middleware()) -> intercept mw -> intercept handler -> intercept loaders
+```
 
 ```typescript
 intercept(
   "@modal",
-  "products.detail",
-  (ctx) => <ProductModal id={ctx.params.id} />,
+  "product",
+  <ProductModal />,
   () => [
-    // Only intercept when NOT coming from product pages
-    when(({ from }) => !from.pathname.startsWith("/products/")),
+    middleware(async (ctx, next) => {
+      // Runs only for this intercept, after global and route middleware
+      ctx.set("interceptSource", "modal");
+      await next();
+    }),
+    loader(ProductLoader),
   ]
 )
 ```
 
-The `when()` callback receives:
+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
-when(({ from, to }) => {
-  from.pathname  // Where user is coming from
-  from.params    // Params of source route
-  to.pathname    // Where user is going
-  to.params      // Params of target route
-
-  return true;   // true = intercept, false = full navigation
-})
+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),
+  ]),
+]);
 ```
 
-## Multiple Intercepts
+Compose multiple contracts if the intercept depends on multiple upstream
+domains.
+
+Helper handoff style keeps intercept trees terse:
 
 ```typescript
-layout(<ShopLayout />, () => [
-  parallel({
-    "@modal": () => null,
-    "@slideOver": () => null,
-  }),
-
-  // Product detail opens as modal
-  intercept(
-    "@modal",
-    "products.detail",
-    (ctx) => <ProductModal id={ctx.params.id} />,
-  ),
-
-  // Quick view opens as slide-over
-  intercept(
-    "@slideOver",
-    "products.quickView",
-    (ctx) => <QuickViewPanel id={ctx.params.id} />,
-  ),
-
-  // Cart opens as slide-over
-  intercept(
-    "@slideOver",
-    "cart",
-    () => <CartSlideOver />,
-  ),
-
-  route("products.index", ProductList),
-  route("products.detail", ProductDetail),
-  route("products.quickView", ProductQuickView),
-  route("cart", CartPage),
-])
+import { revalidate } from "@rangojs/router";
+
+export const revalidateProduct = () => [
+  revalidate(revalidateProductShell),
+];
+
+layout(ProductLayout, () => [
+  revalidateProduct(),
+  intercept("@modal", "product", <ProductModal />, () => [
+    revalidateProduct(),
+    loader(ProductLoader),
+  ]),
+]);
 ```
 
-## Intercept with Layout
+## Conditional Intercept with when()
 
-Wrap the intercepted content:
+Only intercept based on navigation context:
 
 ```typescript
 intercept(
   "@modal",
-  "products.detail",
-  (ctx) => <ProductModalContent id={ctx.params.id} />,
+  "product",
+  <ProductModal />,
   () => [
-    layout(<ModalWrapper />, () => [
-      // Configuration applies to modal
-      loader(ProductLoader),
-      loading(<ProductModalSkeleton />),
-    ]),
+    // Only intercept when coming from a different section
+    when(({ from }) => !from.pathname.startsWith("/shop/product/")),
+    loader(ProductLoader),
   ]
 )
-
-// ModalWrapper provides chrome around content
-function ModalWrapper({ children }: { children: React.ReactNode }) {
-  return (
-    <div className="modal-backdrop">
-      <div className="modal-container">
-        <CloseButton />
-        {children}
-      </div>
-    </div>
-  );
-}
 ```
 
-## Intercept with Middleware
+## Multiple Loaders in Intercept
 
 ```typescript
 intercept(
   "@modal",
-  "account.settings",
-  (ctx) => <SettingsModal user={ctx.get("user")} />,
+  "product",
+  <ProductModal />,
   () => [
-    middleware(async (ctx, next) => {
-      // Verify user is logged in for modal
-      const user = ctx.get("user");
-      if (!user) {
-        throw redirect("/login");
-      }
-      await next();
-    }),
+    loader(ProductLoader, () => [cache()]),
+    loader(ProductCartLoader, () => [revalidate(() => true)]),
+    loader(RecommendationsLoader),
   ]
 )
 ```
 
-## Photo Gallery Example
+## Closing the Modal
+
+Use navigation to close:
 
 ```typescript
-// Instagram-style photo gallery with modal
-export default map<typeof routes>(({ route, layout, parallel, intercept }) => [
-  layout(
-    () => (
-      <GalleryLayout>
-        <Outlet />
-        <ParallelOutlet name="@lightbox" />
-      </GalleryLayout>
-    ),
-    () => [
-      parallel({
-        "@lightbox": () => null,
-      }),
-
-      // Photo opens in lightbox on soft nav
-      intercept(
-        "@lightbox",
-        "photos.detail",
-        (ctx) => (
-          <Lightbox>
-            <PhotoViewer id={ctx.params.id} />
-          </Lightbox>
-        ),
-        () => [
-          loader(PhotoLoader),
-          loading(<PhotoSkeleton />),
-          // Only intercept from gallery pages
-          when(({ from }) => from.pathname.startsWith("/gallery")),
-        ]
-      ),
-
-      route("photos.index", PhotoGrid),
-      route("photos.detail", PhotoPage), // Full page with comments, etc.
-    ]
-  ),
-]);
+"use client";
+import { useRouter } from "@rangojs/router/client";
+
+function ModalWrapper({ children }) {
+  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}
+      </div>
+    </div>
+  );
+}
 ```
 
-## Form Modal Example
+## 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
-// Edit form in modal, full page fallback
-intercept(
-  "@modal",
-  "posts.edit",
-  async (ctx) => {
-    const post = await ctx.use(PostLoader);
-    return (
-      <EditModal>
-        <PostForm post={post} />
-      </EditModal>
-    );
-  },
-  () => [
-    loader(PostLoader),
-    middleware(authMiddleware),
-    // Revalidate after save action
-    revalidate(({ actionId }) => actionId === "savePost"),
-  ]
-)
+// 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),
+  ]),
+])
 ```
 
-## Closing the Modal
+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.
 
-From within the modal, use navigation:
+During action-driven partial revalidation, this same partial rule applies:
+refreshing the intercept does not implicitly rebuild non-revalidated outer
+segments.
+
+## Complete Example
 
 ```typescript
-"use client";
+// components/ProductModal.tsx
+import { Outlet, ParallelOutlet } from "@rangojs/router/client";
 
-// Go back (closes modal, restores background)
-function CloseButton() {
+function ShopLayout() {
   return (
-    <button onClick={() => window.history.back()}>
-      Close
-    </button>
+    <div className="shop">
+      <ParallelOutlet name="@promoBanner" />
+      <main>
+        <Outlet />
+      </main>
+      <ParallelOutlet name="@modal" />
+    </div>
   );
 }
 
-// Or navigate to a specific route
-import { useNavigation } from "rsc-router";
-
-function CloseButton() {
-  const { navigate } = useNavigation();
-
+function ModalWrapper({ children }) {
   return (
-    <button onClick={() => navigate("/products")}>
-      Close
-    </button>
+    <div className="modal-overlay">
+      <div className="modal">{children}</div>
+    </div>
   );
 }
-```
 
-## Key Points
+// urls/shop.tsx
+import { urls } from "@rangojs/router";
+
+export const shopPatterns = urls(({
+  path,
+  layout,
+  parallel,
+  intercept,
+  loader,
+  loading,
+  when,
+}) => [
+  layout(<ShopLayout />, () => [
+    parallel({
+      "@promoBanner": () => <PromoBanner />,
+    }),
+
+    // Intercept product detail into modal
+    intercept(
+      "@modal",
+      "product",  // Route name (without prefix)
+      <ProductModalContent />,
+      () => [
+        when(({ from }) => !from.pathname.startsWith("/shop/product/")),
+        layout(<ModalWrapper />),
+        loading(<ProductModalSkeleton />),
+        loader(ProductLoader, () => [cache()]),
+        loader(RecommendationsLoader),
+      ]
+    ),
 
-1. **Intercept requires a parallel slot** - Define with `parallel({ "@modal": () => null })`
-2. **Soft nav only** - Only works for client-side navigation, not direct URLs
-3. **Preserves background** - The route behind the modal stays rendered
-4. **Full page fallback** - Direct URL always shows the full route handler
-5. **Back button works** - Browser back closes modal naturally
-6. **SEO friendly** - Search engines see the full page, users get the modal UX
+    // Normal routes
+    path("/", ShopIndex, { name: "index" }),
+    path("/product/:slug", ProductPage, { name: "product" }, () => [
+      loader(ProductLoader),
+      loading(<ProductPageSkeleton />),
+    ]),
+  ]),
+]);
+```