@rangojs/router 0.0.0-experimental.259 → 0.0.0-experimental.25dbaac3

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

@@ -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
@@ -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:
@@ -166,6 +241,10 @@ Runtime behavior:
 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
@@ -232,3 +311,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
@@ -145,6 +148,13 @@ 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";
 
@@ -175,8 +185,10 @@ urls(({ path, layout, parallel }) => [
 ])
 ```
 
-Orphan layouts cannot call `ctx.set()` -- only the route handler and
-middleware can write context variables.
+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
 
@@ -198,6 +210,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
@@ -248,3 +308,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.

package/skills/links/SKILL.md

@@ -1,16 +1,20 @@
 ---
 name: links
-description: URL generation with ctx.reverse (server), href (client), useHref (mounted), useMount, and scopedReverse
-argument-hint: [href|useHref|useMount|scopedReverse]
+description: URL generation with ctx.reverse (server default), href (client), useHref (mounted), useMount, and scopedReverse
+argument-hint: [ctx.reverse|href|useHref|useMount|scopedReverse]
 ---
 
 # Links & URL Generation
 
 @rangojs/router provides different href APIs for server and client contexts.
 
+**Default server API: `ctx.reverse()`.** Generate URLs from the handler context — it's typed, auto-fills mount params, and resolves local (`.name`) and absolute (`name.sub`) names.
+
+**`reverse()` is server-only.** It depends on the route manifest and handler context, neither of which are available in the browser. Client components receive URLs as props, loader data, or server-action return values — they never call `reverse` directly.
+
 ## Server: ctx.reverse()
 
-Available in route handlers via HandlerContext. Resolves named routes using the full route map.
+Available in route handlers via HandlerContext. Resolves named routes using the full route map. This is the default way to generate URLs on the server.
 
 ```typescript
 import { urls, scopedReverse } from "@rangojs/router";
@@ -103,7 +107,7 @@ path("/search", (ctx) => {
 
 ### scopedReverse() - type-safe ctx.reverse
 
-Wraps `ctx.reverse` with local route type information for autocomplete and validation:
+Wraps `ctx.reverse` with local route type information for autocomplete and validation. Runtime behavior is identical to `ctx.reverse` — `scopedReverse` is a type-only cast. The same dot-prefix rule applies: local names use `.name`, global names use `name.sub`.
 
 ```typescript
 import { scopedReverse } from "@rangojs/router";
@@ -111,18 +115,85 @@ 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
+  reverse(".cart");                        // Local name (dot-prefixed) — resolves in include scope
+  reverse(".product", { slug: "widget" }); // Local name with params
+  reverse("blog.post", { slug: "hi" });    // Global name (dotted) — full route map
 
   return <ProductPage slug={ctx.params.slug} />;
 }, { name: "product" })
 ```
 
+`reverse()` does not accept raw path strings (`"/about"`). For static paths in client components, use `href("/about")`; on the server, look up the route by name.
+
+## Client components: receive URLs as props
+
+`reverse()` is not available inside `"use client"` modules — there is no handler context and no route manifest in the browser bundle. Generate the URL on the server and hand it to the client component.
+
+Three patterns, in order of preference:
+
+1. Pass as a prop from a server component:
+
+```tsx
+// server
+function BlogPostPage(ctx: HandlerContext) {
+  return <ShareButton url={ctx.reverse(".post", { slug: ctx.params.slug })} />;
+}
+```
+
+```tsx
+"use client";
+
+export function ShareButton({ url }: { url: string }) {
+  return (
+    <button onClick={() => navigator.clipboard.writeText(url)}>Share</button>
+  );
+}
+```
+
+2. Return from a loader (attached to the route via the DSL):
+
+```tsx
+// server — loaders/nav.ts
+export const NavLoader = createLoader((ctx) => ({
+  home: ctx.reverse("home"),
+  blog: ctx.reverse("blog.index"),
+}));
+
+// server — urls.tsx: attach the loader so useLoader has data in context
+const urlpatterns = urls(({ path, loader }) => [
+  path("/", HomePage, { name: "home" }, () => [loader(NavLoader)]),
+]);
+```
+
+```tsx
+"use client";
+
+function Nav() {
+  const { data } = useLoader(NavLoader);
+  return <Link to={data.home}>Home</Link>;
+}
+```
+
+`useLoader()` requires the loader to be attached to an active route. If you need on-demand fetching instead, use `useFetchLoader()`.
+
+3. Return from a server action:
+
+```tsx
+"use server";
+
+export async function getProductUrl(slug: string) {
+  const ctx = getRequestContext();
+  return ctx.reverse("product", { slug });
+}
+```
+
+See `/server-actions` for the full action surface (`getRequestContext()` is the same context middleware and handlers use).
+
+For static path strings (not named routes), client components can use `href()` — see below.
+
 ## Client: href()
 
-Plain function for absolute path-based URLs. No hook needed - works anywhere.
+Plain function for absolute path-based URLs. No hook needed - works anywhere in client components. `href()` validates paths at compile time, but does **not** resolve named routes — for named routes, use one of the patterns above.
 
 ```typescript
 "use client";
@@ -139,7 +210,9 @@ function GlobalNav() {
 }
 ```
 
-`href()` is an identity function at runtime but provides compile-time validation via `ValidPaths` type. Paths are validated against registered route patterns using `PatternToPath`.
+`href()` provides compile-time validation via `ValidPaths` type. Paths are validated against registered route patterns using `PatternToPath`.
+
+`href()` is a raw path helper — it is **not** basename-aware. It returns the path as-is (or with the include mount prefix via `useHref()`). For basename-aware navigation, use `Link`, `useRouter().push()`, or `reverse()`, which auto-prefix root-relative paths with the router's basename.
 
 ## Client: useHref()
 
@@ -185,13 +258,16 @@ function MountInfo() {
 
 ## 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            |
+| Context          | API                                                | Resolves                        | Use for                                                          |
+| ---------------- | -------------------------------------------------- | ------------------------------- | ---------------------------------------------------------------- |
+| Server handler   | `ctx.reverse("name")`                              | Named routes (local + absolute) | **Default** server-side URL generation                           |
+| Server handler   | `scopedReverse<T>(ctx.reverse)`                    | Same, with type safety          | Type-safe server URLs                                            |
+| Client component | (URL passed as prop / loader data / action return) | Named routes                    | Any URL derived from a named route — generate on server, pass in |
+| Client component | `href("/path")`                                    | Absolute paths (static strings) | Static navigation where no named-route lookup is needed          |
+| Client component | `useHref()`                                        | Mount-prefixed paths            | Local navigation inside `include()`                              |
+| Client component | `useMount()`                                       | Raw mount path                  | Custom mount-aware logic                                         |
+
+> `reverse()` is server-only. Client components never import or call it — they receive the already-resolved string.
 
 ## Complete example: mounted module