@rangojs/router 0.0.0-experimental.0b82333f

package/skills/host-router/SKILL.md

@@ -0,0 +1,218 @@
+---
+name: host-router
+description: Multi-app host routing with domain/subdomain patterns
+argument-hint:
+---
+
+# Host Router
+
+Route requests to different apps based on domain, subdomain, or path prefix patterns. Supports middleware, lazy loading, cookie-based host override for dev, and a fallback handler.
+
+## Import
+
+```typescript
+import { createHostRouter, defineHosts } from "@rangojs/router/host";
+```
+
+## Basic Setup
+
+```typescript
+// host-router.ts
+import { createHostRouter } from "@rangojs/router/host";
+
+const router = createHostRouter();
+
+router.host(["."]).map(() => import("./apps/main"));
+router.host(["admin.*"]).map(() => import("./apps/admin"));
+router.host(["api.*"]).map(() => import("./apps/api"));
+
+export default {
+  fetch(request: Request, env: Env, ctx: ExecutionContext) {
+    return router.match(request, { env, ctx });
+  },
+};
+```
+
+Each `.map()` receives either a direct handler `(request, input) => Response` or a lazy import `() => import(...)`. Lazy imports resolve a module with a `default` export that is either a handler function or another `HostRouter` (for nesting).
+
+## Pattern Syntax
+
+| Pattern           | Matches                                        |
+| ----------------- | ---------------------------------------------- |
+| `.` or `*`        | Any apex domain (`example.com`)                |
+| `**`              | Any domain (apex + all subdomains)             |
+| `*.`              | Any single-level subdomain (`www.example.com`) |
+| `**. `            | Any multi-level subdomain (`a.b.example.com`)  |
+| `example.com`     | Exact domain                                   |
+| `*.com`           | Any apex `.com` domain                         |
+| `*.example.com`   | Single subdomain of `example.com`              |
+| `**.example.com`  | Any depth subdomain of `example.com`           |
+| `admin.*`         | `admin` subdomain of any apex domain           |
+| `admin.**`        | `admin` subdomain of any domain                |
+| `admin.`          | `admin` subdomain of any apex (no wildcard)    |
+| `example.com/api` | Domain + path prefix (prefix match)            |
+
+Patterns are tested in registration order. First match wins.
+
+## `defineHosts` for Type Safety
+
+```typescript
+import { defineHosts } from "@rangojs/router/host";
+
+const hosts = defineHosts({
+  admin: "admin.*",
+  api: "api.*",
+  app: [".", "www.*"],
+});
+
+router.host(hosts.admin).map(() => import("./apps/admin"));
+router.host(hosts.app).map(() => import("./apps/main"));
+```
+
+Returns a frozen object — keys are autocompleted by TypeScript.
+
+## Middleware
+
+Global middleware runs for every matched route. Per-route middleware runs only for that host pattern.
+
+```typescript
+const router = createHostRouter();
+
+// Global — runs for all routes
+router.use(async (request, input, next) => {
+  console.log(`[${new Date().toISOString()}] ${request.url}`);
+  return next();
+});
+
+// Per-route
+router
+  .host(["admin.*"])
+  .use(requireAuth)
+  .map(() => import("./apps/admin"));
+```
+
+Middleware signature: `(request: Request, input: RouterRequestInput, next: () => Promise<Response>) => Promise<Response>`
+
+Calling `next()` more than once throws.
+
+## Fallback Handler
+
+Handles cookie-override errors when `hostOverride` is configured (e.g., override from a disallowed host, invalid cookie hostname). The fallback does **not** catch unmatched hosts — those throw `NoRouteMatchError`. Catch that at the worker level if you need a 404.
+
+```typescript
+const router = createHostRouter({
+  hostOverride: { cookieName: "x-dev-host", allowedHosts: ["localhost"] },
+});
+
+// Called when cookie override fails (not for general unmatched hosts)
+router.fallback().map((request) => {
+  return new Response("Invalid host override", { status: 400 });
+});
+```
+
+For unmatched hosts without `hostOverride`, catch `NoRouteMatchError` in your worker fetch:
+
+```typescript
+import { NoRouteMatchError } from "@rangojs/router/host";
+
+export default {
+  async fetch(request: Request, env: Env, ctx: ExecutionContext) {
+    try {
+      return await router.match(request, { env, ctx });
+    } catch (err) {
+      if (err instanceof NoRouteMatchError) {
+        return new Response("Not Found", { status: 404 });
+      }
+      throw err;
+    }
+  },
+};
+```
+
+## Cookie-Based Host Override
+
+For development: route requests to a different app based on a cookie value, allowing developers to test different host routes from a single domain.
+
+```typescript
+const router = createHostRouter({
+  hostOverride: {
+    cookieName: "x-dev-host",
+    allowedHosts: ["localhost", "**.dev.example.com"],
+    validate: (request, cookieValue, input) => {
+      // Optional custom validation — return the effective hostname
+      return cookieValue;
+    },
+  },
+});
+```
+
+When a request arrives:
+
+1. If no cookie → use actual hostname
+2. If cookie present and host is in `allowedHosts` → use cookie value as hostname
+3. If cookie present but host not allowed → throw `HostOverrideNotAllowedError`
+
+Without a custom `validate`, the cookie value is validated as a hostname via `new URL()`.
+
+## Debug Mode
+
+```typescript
+const router = createHostRouter({ debug: true });
+```
+
+Logs pattern matching, route registration, and cookie override decisions to console.
+
+## Testing
+
+```typescript
+import { createTestRequest, testPattern } from "@rangojs/router/host/testing";
+
+// Test pattern matching
+testPattern("admin.*", "admin.example.com"); // true
+testPattern([".", "www.*"], "example.com"); // true
+
+// Create requests for integration tests
+const request = createTestRequest({
+  host: "admin.example.com",
+  path: "/dashboard",
+  cookies: { "x-dev-host": "api.example.com" },
+});
+
+// Test which route would match (without executing)
+router.test("admin.example.com"); // { pattern, handler } | null
+```
+
+## Error Types
+
+All errors extend `HostRouterError`:
+
+| Error                         | When                                        |
+| ----------------------------- | ------------------------------------------- |
+| `InvalidPatternError`         | Pattern is empty, non-string, or has spaces |
+| `HostOverrideNotAllowedError` | Cookie override from disallowed host        |
+| `InvalidHostnameError`        | Cookie value isn't a valid hostname         |
+| `HostValidationError`         | Custom `validate` function threw            |
+| `NoRouteMatchError`           | No host pattern matched the request         |
+| `InvalidHandlerError`         | Handler is not a function                   |
+
+See the fallback section above for a `NoRouteMatchError` catch example.
+
+## Nesting Host Routers
+
+A lazy handler can resolve to another `HostRouter`:
+
+```typescript
+// apps/regional.ts
+import { createHostRouter } from "@rangojs/router/host";
+
+const regional = createHostRouter();
+regional.host(["us.*"]).map(() => import("./regions/us"));
+regional.host(["eu.*"]).map(() => import("./regions/eu"));
+
+export default regional;
+```
+
+```typescript
+// host-router.ts
+router.host(["**.regional.example.com"]).map(() => import("./apps/regional"));
+```

package/skills/intercept/SKILL.md

@@ -0,0 +1,313 @@
+---
+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.
+
+Canonical semantics reference:
+[docs/execution-model.md](../../docs/internal/execution-model.md)
+
+## 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 />),
+  ]
+)
+```
+
+## 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:
+
+```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 { 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>
+  );
+}
+```
+
+## 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
+// 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 />),
+    ]),
+  ]),
+]);
+```