@rangojs/router 0.0.0-experimental.10

package/skills/intercept/SKILL.md

@@ -0,0 +1,190 @@
+---
+name: intercept
+description: Define intercept routes for modals, slide-overs, and soft navigation patterns in @rangojs/router
+argument-hint: [@slot-name] [route-to-intercept]
+---
+
+# Intercept Routes
+
+Intercept routes render a different component during soft navigation (client-side) while preserving the background route. Hard navigation (direct URL) shows the full page.
+
+## Basic Intercept
+
+```typescript
+import { urls } from "@rangojs/router";
+import { Outlet, ParallelOutlet } from "@rangojs/router/client";
+
+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 />),
+      ]
+    ),
+
+    // Normal routes
+    path("/shop", ShopIndex, { name: "index" }),
+    path("/shop/product/:slug", ProductPage, { name: "product" }),
+  ]),
+]);
+```
+
+## Navigation Behavior
+
+| 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 Layout
+
+Wrap intercept content in a modal layout:
+
+```typescript
+intercept(
+  "@modal",
+  "product",
+  <ProductModalContent />,
+  () => [
+    layout(<ModalWrapper />),  // Wraps the modal content
+    loader(ProductLoader),
+    loading(<ProductModalSkeleton />),
+  ]
+)
+```
+
+## Conditional Intercept with when()
+
+Only intercept based on navigation context:
+
+```typescript
+intercept(
+  "@modal",
+  "product",
+  <ProductModal />,
+  () => [
+    // Only intercept when coming from a different section
+    when(({ from }) => !from.pathname.startsWith("/shop/product/")),
+    loader(ProductLoader),
+  ]
+)
+```
+
+## Multiple Loaders in Intercept
+
+```typescript
+intercept(
+  "@modal",
+  "product",
+  <ProductModal />,
+  () => [
+    loader(ProductLoader, () => [cache()]),
+    loader(ProductCartLoader, () => [revalidate(() => true)]),
+    loader(RecommendationsLoader),
+  ]
+)
+```
+
+## Closing the Modal
+
+Use navigation to close:
+
+```typescript
+"use client";
+import { useNavigation } from "@rangojs/router/client";
+
+function ModalWrapper({ children }) {
+  const { goBack } = useNavigation();
+
+  return (
+    <div className="modal-overlay" onClick={goBack}>
+      <div className="modal" onClick={(e) => e.stopPropagation()}>
+        <button onClick={goBack}>Close</button>
+        {children}
+      </div>
+    </div>
+  );
+}
+```
+
+## Complete Example
+
+```typescript
+// components/ProductModal.tsx
+import { Outlet, ParallelOutlet } from "@rangojs/router/client";
+
+function ShopLayout() {
+  return (
+    <div className="shop">
+      <ParallelOutlet name="@promoBanner" />
+      <main>
+        <Outlet />
+      </main>
+      <ParallelOutlet name="@modal" />
+    </div>
+  );
+}
+
+function ModalWrapper({ children }) {
+  return (
+    <div className="modal-overlay">
+      <div className="modal">{children}</div>
+    </div>
+  );
+}
+
+// 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),
+      ]
+    ),
+
+    // Normal routes
+    path("/", ShopIndex, { name: "index" }),
+    path("/product/:slug", ProductPage, { name: "product" }, () => [
+      loader(ProductLoader),
+      loading(<ProductPageSkeleton />),
+    ]),
+  ]),
+]);
+```

package/skills/layout/SKILL.md

@@ -0,0 +1,213 @@
+---
+name: layout
+description: Define layout routes that wrap child routes in @rangojs/router
+argument-hint: [component]
+---
+
+# Layouts with layout()
+
+Layouts wrap child routes and persist during navigation within their scope.
+
+## Basic Layout
+
+```typescript
+import { urls } from "@rangojs/router";
+import { Outlet } from "@rangojs/router/client";
+
+function ShopLayout() {
+  return (
+    <div className="shop">
+      <nav>Shop Navigation</nav>
+      <Outlet />  {/* Child routes render here */}
+    </div>
+  );
+}
+
+export const urlpatterns = urls(({ path, layout }) => [
+  layout(<ShopLayout />, () => [
+    path("/shop", ShopIndex, { name: "shop.index" }),
+    path("/shop/cart", CartPage, { name: "shop.cart" }),
+    path("/shop/product/:slug", ProductPage, { name: "shop.product" }),
+  ]),
+]);
+```
+
+## Layout Patterns
+
+### JSX Element
+
+```typescript
+layout(<ShopLayout />, () => [
+  path("/shop", ShopIndex, { name: "shop" }),
+])
+```
+
+### Component Function
+
+```typescript
+layout(ShopLayout, () => [
+  path("/shop", ShopIndex, { name: "shop" }),
+])
+```
+
+### Handler with Context
+
+```typescript
+layout((ctx) => {
+  const push = ctx.use(Breadcrumbs);
+  push({ label: "Shop", href: "/shop" });
+  return <ShopLayout />;
+}, () => [
+  path("/shop", ShopIndex, { name: "shop" }),
+])
+```
+
+## Nested Layouts
+
+Layouts compose by wrapping order (first layout wraps outer):
+
+```typescript
+urls(({ path, layout }) => [
+  layout(<RootLayout />, () => [           // Outer
+    layout(<ShopLayout />, () => [         // Inner
+      path("/shop", ShopIndex, { name: "shop" }),
+    ]),
+  ]),
+])
+
+// Result: RootLayout > ShopLayout > ShopIndex
+```
+
+## Layout with Children DSL
+
+Add loaders, parallel routes, or revalidation to layouts:
+
+```typescript
+layout(<ShopLayout />, () => [
+  // Loaders for layout
+  loader(CartLoader),
+  loader(UserLoader),
+
+  // Revalidation rules for layout
+  revalidate(shopRevalidation),
+
+  // Child routes
+  path("/shop", ShopIndex, { name: "shop" }),
+  path("/shop/cart", CartPage, { name: "cart" }),
+])
+```
+
+## The Outlet Component
+
+`<Outlet />` renders child content. Import from `@rangojs/router/client`:
+
+```typescript
+import { Outlet } from "@rangojs/router/client";
+
+function ShopLayout() {
+  return (
+    <div className="shop-layout">
+      <header>Shop Header</header>
+      <main>
+        <Outlet />  {/* Child routes render here */}
+      </main>
+      <footer>Shop Footer</footer>
+    </div>
+  );
+}
+```
+
+## Named Outlets
+
+For parallel routes, use named outlets:
+
+```typescript
+import { Outlet, ParallelOutlet } from "@rangojs/router/client";
+
+function DashboardLayout() {
+  return (
+    <div className="dashboard">
+      <aside>
+        <ParallelOutlet name="@sidebar" />
+      </aside>
+      <main>
+        <Outlet />  {/* Main content */}
+      </main>
+      <aside>
+        <ParallelOutlet name="@notifications" />
+      </aside>
+    </div>
+  );
+}
+```
+
+## Layout Revalidation
+
+Layouts don't revalidate by default. Control with `revalidate()`:
+
+```typescript
+layout(<ShopLayout />, () => [
+  // Never revalidate (default behavior)
+  revalidate(() => false),
+
+  path("/shop", ShopIndex, { name: "shop" }),
+])
+
+// Or revalidate based on conditions
+layout(<CartLayout />, () => [
+  revalidate(({ actionId }) => actionId?.includes("Cart") ?? false),
+
+  path("/cart", CartPage, { name: "cart" }),
+])
+```
+
+## Complete Example
+
+```typescript
+import { urls } from "@rangojs/router";
+import { Outlet, ParallelOutlet } from "@rangojs/router/client";
+
+function ShopLayout() {
+  return (
+    <div className="shop">
+      <ParallelOutlet name="@promoBanner" />
+      <nav>
+        <a href="/shop">Home</a>
+        <a href="/shop/cart">Cart</a>
+      </nav>
+      <div className="content">
+        <aside>
+          <ParallelOutlet name="@sidebar" />
+        </aside>
+        <main>
+          <Outlet />
+        </main>
+      </div>
+    </div>
+  );
+}
+
+export const shopPatterns = urls(({ path, layout, parallel, loader, revalidate }) => [
+  layout((ctx) => {
+    const push = ctx.use(Breadcrumbs);
+    push({ label: "Shop", href: "/shop" });
+    return <ShopLayout />;
+  }, () => [
+    // Layout loaders
+    loader(CartLoader, () => [
+      revalidate(({ actionId }) => actionId?.includes("Cart") ?? false),
+    ]),
+
+    // Parallel routes
+    parallel({
+      "@promoBanner": () => <PromoBanner />,
+      "@sidebar": () => <CategorySidebar />,
+    }),
+
+    // Child routes
+    path("/shop", ShopIndex, { name: "index" }),
+    path("/shop/cart", CartPage, { name: "cart" }),
+    path("/shop/product/:slug", ProductPage, { name: "product" }),
+  ]),
+]);
+```

package/skills/links/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: links
+description: URL generation with ctx.reverse (server), href (client), useHref (mounted), useMount, and scopedReverse
+argument-hint: [href|useHref|useMount|scopedReverse]
+---
+
+# Links & URL Generation
+
+@rangojs/router provides different href APIs for server and client contexts.
+
+## Server: ctx.reverse()
+
+Available in route handlers via HandlerContext. Resolves named routes using the full route map.
+
+```typescript
+import { urls, scopedReverse } from "@rangojs/router";
+
+export const shopPatterns = urls(({ path, layout }) => [
+  layout(<ShopLayout />, () => [
+    path("/", ShopIndex, { name: "index" }),
+    path("/cart", CartPage, { name: "cart" }),
+    path("/product/:slug", ProductPage, { name: "product" }),
+  ]),
+]);
+```
+
+### Resolution priority
+
+1. **Path-based** (`/...`) - returned as-is
+2. **Absolute name** (contains dot: `blog.post`) - global lookup
+3. **Local name** (`cart`) - resolved relative to current route's namespace
+
+```typescript
+// Inside a handler within shopPatterns (mounted at /shop)
+path("/product/:slug", (ctx) => {
+  ctx.reverse("cart");                        // "/shop/cart" (local)
+  ctx.reverse("product", { slug: "widget" }); // "/shop/product/widget" (local + params)
+  ctx.reverse("blog.post", { slug: "hi" });   // "/blog/hi" (absolute)
+  ctx.reverse("/about");                      // "/about" (path-based)
+
+  return <ProductPage slug={ctx.params.slug} />;
+}, { name: "product" })
+```
+
+### scopedReverse() - type-safe ctx.reverse
+
+Wraps `ctx.reverse` with local route type information for autocomplete and validation:
+
+```typescript
+import { scopedReverse } from "@rangojs/router";
+
+path("/product/:slug", (ctx) => {
+  const reverse = scopedReverse<typeof shopPatterns>(ctx.reverse);
+
+  reverse("cart");                        // Type-safe local name
+  reverse("product", { slug: "widget" }); // Type-safe with params
+  reverse("blog.post");                   // Absolute names (dot notation) always allowed
+  reverse("/about");                      // Path-based always allowed
+
+  return <ProductPage slug={ctx.params.slug} />;
+}, { name: "product" })
+```
+
+## Client: href()
+
+Plain function for absolute path-based URLs. No hook needed - works anywhere.
+
+```typescript
+"use client";
+import { href, Link } from "@rangojs/router/client";
+
+function GlobalNav() {
+  return (
+    <nav>
+      <Link to={href("/")}>Home</Link>
+      <Link to={href("/about")}>About</Link>
+      <Link to={href("/blog/hello")}>Post</Link>
+    </nav>
+  );
+}
+```
+
+`href()` is an identity function at runtime but provides compile-time validation via `ValidPaths` type. Paths are validated against registered route patterns using `PatternToPath`.
+
+## Client: useHref()
+
+Hook that returns a mount-aware href function. Automatically prepends the `include()` mount prefix.
+
+```typescript
+"use client";
+import { useHref, href, Link } from "@rangojs/router/client";
+
+// Inside include("/shop", shopPatterns)
+function ShopNav() {
+  const href = useHref();
+
+  return (
+    <nav>
+      <Link to={href("/")}>Shop Home</Link>        {/* "/shop/" */}
+      <Link to={href("/cart")}>Cart</Link>          {/* "/shop/cart" */}
+      <Link to={href("/product/widget")}>W</Link>   {/* "/shop/product/widget" */}
+    </nav>
+  );
+}
+```
+
+Use `useHref()` for local navigation within a mounted module. Use the bare `href()` function for absolute paths outside the current mount.
+
+## Client: useMount()
+
+Returns the current `include()` mount path. Useful for building custom logic based on mount location.
+
+```typescript
+"use client";
+import { useMount } from "@rangojs/router/client";
+
+function MountInfo() {
+  const mount = useMount(); // "/shop" inside include("/shop", ...)
+                            // "/" at root level
+
+  return <span>Mounted at: {mount}</span>;
+}
+```
+
+`useMount()` reads from `MountContext`, which is automatically set by `include()` in the segment tree.
+
+## When to use what
+
+| Context | API | Resolves | Use for |
+|---------|-----|----------|---------|
+| Server handler | `ctx.reverse("name")` | Named routes (local + absolute) | Server-side URL generation |
+| Server handler | `scopedReverse<T>(ctx.reverse)` | Same, with type safety | Type-safe server URLs |
+| Client component | `href("/path")` | Absolute paths | Global navigation |
+| Client component | `useHref()` | Mount-prefixed paths | Local navigation inside `include()` |
+| Client component | `useMount()` | Raw mount path | Custom mount-aware logic |
+
+## Complete example: mounted module
+
+```typescript
+// urls/shop.tsx (server)
+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")} />;
+  }, () => [
+    path("/", ShopIndex, { name: "index" }),
+    path("/cart", CartPage, { name: "cart" }),
+    path("/product/:slug", ProductPage, { name: "product" }),
+  ]),
+]);
+
+// urls.tsx (server)
+export const urlpatterns = urls(({ path, include }) => [
+  path("/", HomePage, { name: "home" }),
+  include("/shop", shopPatterns),
+]);
+```
+
+```tsx
+// components/ShopNav.tsx (client)
+"use client";
+import { useHref, href, Link } from "@rangojs/router/client";
+
+export function ShopNav() {
+  const localHref = useHref();
+
+  return (
+    <nav>
+      {/* Local paths - auto-prefixed with /shop */}
+      <Link to={localHref("/cart")}>Cart</Link>
+      <Link to={localHref("/product/widget")}>Widget</Link>
+
+      {/* Absolute path - no prefix */}
+      <Link to={href("/")}>Home</Link>
+    </nav>
+  );
+}
+```