@rangojs/router 0.0.0-experimental.2

package/skills/hooks/SKILL.md

@@ -0,0 +1,359 @@
+---
+name: hooks
+description: Client-side React hooks for navigation, loaders, and state in rsc-router
+argument-hint: [hook-name]
+---
+
+# Client-Side React Hooks
+
+All hooks are imported from `rsc-router` or `rsc-router/client`.
+
+## Navigation Hooks
+
+### useNavigation()
+
+Track navigation state and control navigation:
+
+```tsx
+"use client";
+import { useNavigation } from "rsc-router";
+
+function NavIndicator() {
+  const nav = useNavigation();
+
+  // Full state
+  nav.state;        // 'idle' | 'loading' | 'streaming'
+  nav.isStreaming;  // boolean
+  nav.location;     // Current URL
+  nav.pendingUrl;   // Target URL during navigation (or null)
+
+  // Methods
+  nav.navigate("/products");           // Navigate programmatically
+  nav.navigate("/products", { replace: true }); // Replace history
+  nav.refresh();                       // Refresh current route
+
+  return nav.state === 'loading' ? <Spinner /> : null;
+}
+
+// With selector for performance
+function IsLoading() {
+  const isLoading = useNavigation(nav => nav.state === 'loading');
+  return isLoading ? <Spinner /> : null;
+}
+```
+
+### useSegments()
+
+Access current URL path and matched route segments:
+
+```tsx
+"use client";
+import { useSegments } from "rsc-router";
+
+function Breadcrumbs() {
+  const { path, segmentIds, location } = useSegments();
+
+  // path: ["/shop", "products", "123"]
+  // segmentIds: ["shop-layout", "products-route"]
+  // location: URL object
+
+  return <nav>{path.join(" > ")}</nav>;
+}
+
+// With selector
+const isShopRoute = useSegments(s => s.path[0] === "shop");
+```
+
+### useLinkStatus()
+
+Track pending state inside a Link component:
+
+```tsx
+"use client";
+import { Link, useLinkStatus } from "rsc-router/client";
+
+function LoadingIndicator() {
+  const { pending } = useLinkStatus();
+  return pending ? <Spinner /> : null;
+}
+
+// Must be inside Link
+<Link to="/dashboard">
+  Dashboard
+  <LoadingIndicator />
+</Link>
+```
+
+## Data Hooks
+
+### useLoader()
+
+Access loader data (strict - data guaranteed):
+
+```tsx
+"use client";
+import { useLoader } from "rsc-router";
+import { ProductLoader } from "../loaders/product";
+
+function ProductPrice() {
+  const { data, isLoading, error } = useLoader(ProductLoader);
+
+  // data: T (guaranteed - throws if not in context)
+  // isLoading: boolean
+  // error: Error | null
+
+  return <span>${data.price}</span>;
+}
+```
+
+**Precondition**: Loader must be registered on route via `loader()` helper.
+
+### useFetchLoader()
+
+Access loader with on-demand fetching (flexible):
+
+```tsx
+"use client";
+import { useFetchLoader } from "rsc-router";
+import { SearchLoader } from "../loaders/search";
+
+function SearchResults() {
+  const { data, load, isLoading, error } = useFetchLoader(SearchLoader);
+
+  // data: T | undefined (may be undefined if not fetched)
+  // load: (options?) => Promise<T>
+  // refetch: alias for load
+
+  const handleSearch = async (query: string) => {
+    await load({ params: { query } });
+  };
+
+  return (
+    <div>
+      <input onChange={(e) => handleSearch(e.target.value)} />
+      {isLoading && <Spinner />}
+      {data?.results.map(r => <Result key={r.id} {...r} />)}
+    </div>
+  );
+}
+```
+
+**Load options**:
+```tsx
+await load({
+  method: 'POST',              // GET, POST, PUT, PATCH, DELETE
+  params: { query: 'test' },   // Query string (GET) or body (others)
+  body: { data: 'value' },     // For POST/PUT/PATCH/DELETE
+});
+```
+
+### useLoaderData()
+
+Get all loader data in current context:
+
+```tsx
+"use client";
+import { useLoaderData } from "rsc-router";
+
+function DebugPanel() {
+  const allData = useLoaderData();
+  // Record<string, any> - Map of loader ID to data
+
+  return <pre>{JSON.stringify(allData, null, 2)}</pre>;
+}
+```
+
+## Handle Hooks
+
+### useHandle()
+
+Access accumulated handle data from route segments:
+
+```tsx
+"use client";
+import { useHandle } from "rsc-router";
+import { Breadcrumbs } from "../handles/breadcrumbs";
+
+function BreadcrumbNav() {
+  const crumbs = useHandle(Breadcrumbs);
+  // Array of { label, href } accumulated from layouts/routes
+
+  return (
+    <nav>
+      {crumbs.map((c, i) => (
+        <span key={i}>
+          <a href={c.href}>{c.label}</a>
+          {i < crumbs.length - 1 && " > "}
+        </span>
+      ))}
+    </nav>
+  );
+}
+
+// With selector
+const lastCrumb = useHandle(Breadcrumbs, data => data.at(-1));
+```
+
+## Action Hooks
+
+### useAction()
+
+Track state of server action invocations:
+
+```tsx
+"use client";
+import { useAction } from "rsc-router";
+import { addToCart } from "../actions/cart";
+
+function AddToCartButton({ productId }: { productId: string }) {
+  const { state, error, result } = useAction(addToCart);
+
+  // state: 'idle' | 'loading' | 'streaming'
+  // actionId: string | null
+  // payload: unknown | null (input data)
+  // error: Error | null
+  // result: unknown | null (return value)
+
+  return (
+    <form action={addToCart}>
+      <input type="hidden" name="productId" value={productId} />
+      <button disabled={state === 'loading'}>
+        {state === 'loading' ? 'Adding...' : 'Add to Cart'}
+      </button>
+      {error && <p className="error">{error.message}</p>}
+    </form>
+  );
+}
+
+// Match by string suffix (convenient but may be ambiguous)
+const isLoading = useAction('addToCart', s => s.state === 'loading');
+```
+
+## State Hooks
+
+### useLocationState()
+
+Read type-safe state from history:
+
+```tsx
+"use client";
+import { useLocationState, createLocationState } from "rsc-router";
+
+// Define typed state
+export const ProductState = createLocationState<{
+  name: string;
+  price: number;
+}>();
+
+function ProductHeader() {
+  const state = useLocationState(ProductState);
+  // { name: string; price: number } | undefined
+
+  if (state) {
+    return <h1>{state.name} - ${state.price}</h1>;
+  }
+  return <h1>Loading...</h1>;
+}
+```
+
+Pass state through Link:
+
+```tsx
+import { Link } from "rsc-router/client";
+import { ProductState } from "./state";
+
+<Link
+  to="/product/123"
+  state={[ProductState({ name: "Widget", price: 99 })]}
+>
+  View Product
+</Link>
+```
+
+## Cache Hooks
+
+### useClientCache()
+
+Manually control client-side navigation cache:
+
+```tsx
+"use client";
+import { useClientCache } from "rsc-router";
+
+function SaveButton() {
+  const { clear } = useClientCache();
+
+  const handleSave = async () => {
+    await fetch('/api/data', {
+      method: 'POST',
+      body: JSON.stringify(data)
+    });
+
+    // Invalidate cache after mutation
+    clear();
+  };
+
+  return <button onClick={handleSave}>Save</button>;
+}
+```
+
+**Use cases**: REST API mutations, WebSocket updates, non-RSC data changes.
+
+## Outlet Components
+
+### Outlet / ParallelOutlet
+
+Render child content in layouts:
+
+```tsx
+import { Outlet, ParallelOutlet } from "rsc-router";
+
+function DashboardLayout({ children }: { children?: React.ReactNode }) {
+  return (
+    <div className="dashboard">
+      <aside>
+        <ParallelOutlet name="@sidebar" />
+      </aside>
+      <main>
+        {children ?? <Outlet />}
+      </main>
+      <ParallelOutlet name="@notifications" />
+    </div>
+  );
+}
+```
+
+### useOutlet()
+
+Access outlet content programmatically:
+
+```tsx
+"use client";
+import { useOutlet } from "rsc-router";
+
+function ConditionalLayout() {
+  const outlet = useOutlet();
+  // ReactNode | null
+
+  return outlet ? (
+    <div className="with-content">{outlet}</div>
+  ) : (
+    <div className="empty">No content</div>
+  );
+}
+```
+
+## Hook Summary
+
+| Hook | Purpose | Returns |
+|------|---------|---------|
+| `useNavigation()` | Navigation state & control | state, navigate, refresh |
+| `useSegments()` | URL path & segment IDs | path, segmentIds, location |
+| `useLinkStatus()` | Link pending state | { pending } |
+| `useLoader()` | Loader data (strict) | data, isLoading, error |
+| `useFetchLoader()` | Loader with on-demand fetch | data, load, isLoading |
+| `useLoaderData()` | All loader data | Record<string, any> |
+| `useHandle()` | Accumulated handle data | T (handle type) |
+| `useAction()` | Server action state | state, error, result |
+| `useLocationState()` | History state | T \| undefined |
+| `useClientCache()` | Cache control | { clear } |

package/skills/intercept/SKILL.md

@@ -0,0 +1,292 @@
+---
+name: intercept
+description: Define intercept routes for modals, slide-overs, and soft navigation patterns in rsc-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 { map } from "rsc-router/server";
+import { ParallelOutlet } from "rsc-router";
+
+export default map<typeof routes>(({ route, layout, parallel, intercept, loader }) => [
+  layout(
+    () => (
+      <ShopLayout>
+        <Outlet />
+        <ParallelOutlet name="@modal" />
+      </ShopLayout>
+    ),
+    () => [
+      // 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
+    ]
+  ),
+]);
+```
+
+## 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 |
+
+## Intercept with Configuration
+
+```typescript
+intercept(
+  "@modal",
+  "products.detail",
+  async (ctx) => {
+    const product = await ctx.use(ProductLoader);
+    return <ProductModal product={product} />;
+  },
+  () => [
+    loader(ProductLoader),
+    loading(<ProductModalSkeleton />),
+    revalidate(({ actionId }) => actionId?.includes("cart") ?? false),
+    errorBoundary(<ModalErrorFallback />),
+  ]
+)
+```
+
+## Conditional Intercept with `when()`
+
+Only intercept under certain conditions:
+
+```typescript
+intercept(
+  "@modal",
+  "products.detail",
+  (ctx) => <ProductModal id={ctx.params.id} />,
+  () => [
+    // Only intercept when NOT coming from product pages
+    when(({ from }) => !from.pathname.startsWith("/products/")),
+  ]
+)
+```
+
+The `when()` callback receives:
+
+```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
+})
+```
+
+## Multiple Intercepts
+
+```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),
+])
+```
+
+## Intercept with Layout
+
+Wrap the intercepted content:
+
+```typescript
+intercept(
+  "@modal",
+  "products.detail",
+  (ctx) => <ProductModalContent id={ctx.params.id} />,
+  () => [
+    layout(<ModalWrapper />, () => [
+      // Configuration applies to modal
+      loader(ProductLoader),
+      loading(<ProductModalSkeleton />),
+    ]),
+  ]
+)
+
+// 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
+
+```typescript
+intercept(
+  "@modal",
+  "account.settings",
+  (ctx) => <SettingsModal user={ctx.get("user")} />,
+  () => [
+    middleware(async (ctx, next) => {
+      // Verify user is logged in for modal
+      const user = ctx.get("user");
+      if (!user) {
+        throw redirect("/login");
+      }
+      await next();
+    }),
+  ]
+)
+```
+
+## Photo Gallery Example
+
+```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.
+    ]
+  ),
+]);
+```
+
+## Form Modal Example
+
+```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"),
+  ]
+)
+```
+
+## Closing the Modal
+
+From within the modal, use navigation:
+
+```typescript
+"use client";
+
+// Go back (closes modal, restores background)
+function CloseButton() {
+  return (
+    <button onClick={() => window.history.back()}>
+      Close
+    </button>
+  );
+}
+
+// Or navigate to a specific route
+import { useNavigation } from "rsc-router";
+
+function CloseButton() {
+  const { navigate } = useNavigation();
+
+  return (
+    <button onClick={() => navigate("/products")}>
+      Close
+    </button>
+  );
+}
+```
+
+## Key Points
+
+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