@rangojs/router 0.0.0-experimental.20 → 0.0.0-experimental.22

package/skills/hooks/SKILL.md

@@ -6,7 +6,8 @@ argument-hint: [hook-name]
 
 # Client-Side React Hooks
 
-All hooks are imported from `@rangojs/router` or `@rangojs/router/client`.
+Import the hooks and components in this skill from `@rangojs/router/client`.
+The root `@rangojs/router` entrypoint is for server/RSC APIs and shared types.
 
 ## Navigation Hooks
 
@@ -63,7 +64,7 @@ Access current URL path and matched route segments:
 
 ```tsx
 "use client";
-import { useSegments } from "@rangojs/router";
+import { useSegments } from "@rangojs/router/client";
 
 function Breadcrumbs() {
   const { path, segmentIds, location } = useSegments();
@@ -107,7 +108,7 @@ Access loader data (strict - data guaranteed):
 
 ```tsx
 "use client";
-import { useLoader } from "@rangojs/router";
+import { useLoader } from "@rangojs/router/client";
 import { ProductLoader } from "../loaders/product";
 
 function ProductPrice() {
@@ -143,7 +144,7 @@ Access loader with on-demand fetching (flexible):
 
 ```tsx
 "use client";
-import { useFetchLoader } from "@rangojs/router";
+import { useFetchLoader } from "@rangojs/router/client";
 import { SearchLoader } from "../loaders/search";
 
 function SearchResults() {
@@ -197,7 +198,7 @@ server, JSON bodies are available via `ctx.body` and FormData bodies via `ctx.fo
 
 ```tsx
 "use client";
-import { useFetchLoader } from "@rangojs/router";
+import { useFetchLoader } from "@rangojs/router/client";
 import { FileUploadLoader } from "../loaders/upload";
 
 function FileUploader() {
@@ -244,7 +245,7 @@ Get all loader data in current context:
 
 ```tsx
 "use client";
-import { useLoaderData } from "@rangojs/router";
+import { useLoaderData } from "@rangojs/router/client";
 
 function DebugPanel() {
   const allData = useLoaderData();
@@ -262,7 +263,7 @@ Access accumulated handle data from route segments:
 
 ```tsx
 "use client";
-import { useHandle } from "@rangojs/router";
+import { useHandle } from "@rangojs/router/client";
 import { Breadcrumbs } from "../handles/breadcrumbs";
 
 function BreadcrumbNav() {
@@ -324,7 +325,7 @@ Track state of server action invocations:
 
 ```tsx
 "use client";
-import { useAction } from "@rangojs/router";
+import { useAction } from "@rangojs/router/client";
 import { addToCart } from "../actions/cart";
 
 function AddToCartButton({ productId }: { productId: string }) {
@@ -359,7 +360,7 @@ Read type-safe state from history:
 
 ```tsx
 "use client";
-import { useLocationState, createLocationState } from "@rangojs/router";
+import { useLocationState, createLocationState } from "@rangojs/router/client";
 
 // Define typed state (all export patterns supported)
 // Keys are auto-injected by the Vite plugin -- no manual key needed.
@@ -509,7 +510,7 @@ Manually control client-side navigation cache:
 
 ```tsx
 "use client";
-import { useClientCache } from "@rangojs/router";
+import { useClientCache } from "@rangojs/router/client";
 
 function SaveButton() {
   const { clear } = useClientCache();
@@ -537,7 +538,7 @@ function SaveButton() {
 Render child content in layouts:
 
 ```tsx
-import { Outlet, ParallelOutlet } from "@rangojs/router";
+import { Outlet, ParallelOutlet } from "@rangojs/router/client";
 
 function DashboardLayout({ children }: { children?: React.ReactNode }) {
   return (
@@ -558,7 +559,7 @@ Access outlet content programmatically:
 
 ```tsx
 "use client";
-import { useOutlet } from "@rangojs/router";
+import { useOutlet } from "@rangojs/router/client";
 
 function ConditionalLayout() {
   const outlet = useOutlet();

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/loader/SKILL.md

@@ -68,7 +68,7 @@ export const urlpatterns = urls(({ path, loader }) => [
 ### In Server Components
 
 ```typescript
-import { useLoader } from "@rangojs/router";
+import { useLoader } from "@rangojs/router/client";
 import { ProductLoader } from "./loaders/product";
 
 async function ProductPage() {
@@ -539,7 +539,7 @@ export const urlpatterns = urls(({ path, layout, loader, loading, cache, revalid
 ]);
 
 // pages/product.tsx
-import { useLoader } from "@rangojs/router";
+import { useLoader } from "@rangojs/router/client";
 import { ProductLoader, CartLoader } from "./loaders/shop";
 
 async function ProductPage() {

package/skills/prerender/SKILL.md

@@ -521,10 +521,10 @@ export const guidesPatterns = urls(({ path }) => [
 ]);
 
 // urls.tsx
-import { urls, include } from "@rangojs/router";
+import { urls } from "@rangojs/router";
 import { guidesPatterns } from "./pages/guides.js";
 
-export const urlpatterns = urls(({ path }) => [
+export const urlpatterns = urls(({ path, include }) => [
   path("/", HomePage, { name: "home" }),
   include("/guides", guidesPatterns, { name: "guides" }),
 ]);

package/skills/rango/SKILL.md

@@ -32,7 +32,6 @@ Django-inspired RSC router with composable URL patterns, type-safe href, and ser
 | `/response-routes` | JSON/text/HTML/XML/stream endpoints with `path.json()`, `path.text()`      |
 | `/mime-routes`     | Content negotiation — same URL, different response types via Accept header |
 | `/fonts`           | Load web fonts with preload hints                                          |
-| `/testing`         | Unit test route trees with `buildRouteTree()`                              |
 
 ## Quick Start
 

package/skills/router-setup/SKILL.md

@@ -297,10 +297,10 @@ export const shopPatterns = urls(({ path, layout }) => [
 ]);
 
 // src/urls.tsx
-import { urls, include } from "@rangojs/router";
+import { urls } from "@rangojs/router";
 import { shopPatterns } from "./urls/shop";
 
-export const urlpatterns = urls(({ path }) => [
+export const urlpatterns = urls(({ path, include }) => [
   path("/", HomePage, { name: "home" }),
   include("/shop", shopPatterns, { name: "shop" }),
 ]);

package/skills/typesafety/SKILL.md

@@ -334,7 +334,7 @@ export const ProductLoader = createLoader(async (ctx) => {
 });
 
 // In server component - type is inferred
-import { useLoader } from "@rangojs/router";
+import { useLoader } from "@rangojs/router/client";
 
 async function ProductPage() {
   const product = await useLoader(ProductLoader);

package/src/host/index.ts

@@ -25,9 +25,6 @@
 // Core router
 export { createHostRouter } from "./router.js";
 
-// Host router registry for build-time discovery
-export { HostRouterRegistry, type HostRouterRegistryEntry } from "./router.js";
-
 // Utilities
 export { defineHosts } from "./utils.js";
 

package/src/index.ts

@@ -115,25 +115,32 @@ export type {
 // Middleware context types
 export type { MiddlewareContext, CookieOptions } from "./router/middleware.js";
 
+function serverOnlyStubError(name: string): Error {
+  return new Error(
+    `${name}() is only available from "@rangojs/router" in a react-server/RSC environment. ` +
+      `For client hooks and components, import from "@rangojs/router/client".`,
+  );
+}
+
 /**
  * Error-throwing stub for server-only `urls` function.
  */
 export function urls(): never {
-  throw new Error("urls() is server-only and requires RSC context.");
+  throw serverOnlyStubError("urls");
 }
 
 /**
  * Error-throwing stub for server-only `createRouter` function.
  */
 export function createRouter(): never {
-  throw new Error("createRouter() is server-only and requires RSC context.");
+  throw serverOnlyStubError("createRouter");
 }
 
 /**
  * Error-throwing stub for server-only `redirect` function.
  */
 export function redirect(): never {
-  throw new Error("redirect() is server-only and requires RSC context.");
+  throw serverOnlyStubError("redirect");
 }
 
 // Handle API (universal - works on both server and client)
@@ -149,102 +156,94 @@ export { nonce } from "./rsc/nonce.js";
  * Error-throwing stub for server-only `Prerender` function.
  */
 export function Prerender(): never {
-  throw new Error("Prerender() is server-only and requires RSC context.");
+  throw serverOnlyStubError("Prerender");
 }
 
 /**
  * Error-throwing stub for server-only `Static` function.
  */
 export function Static(): never {
-  throw new Error("Static() is server-only and requires RSC context.");
+  throw serverOnlyStubError("Static");
 }
 
 /**
  * Error-throwing stub for server-only `getRequestContext` function.
  */
 export function getRequestContext(): never {
-  throw new Error(
-    "getRequestContext() is server-only and requires RSC context.",
-  );
+  throw serverOnlyStubError("getRequestContext");
 }
 
 /**
  * Error-throwing stub for server-only `cookies` function.
  */
 export function cookies(): never {
-  throw new Error("cookies() is server-only and requires RSC context.");
+  throw serverOnlyStubError("cookies");
 }
 
 /**
  * Error-throwing stub for server-only `headers` function.
  */
 export function headers(): never {
-  throw new Error("headers() is server-only and requires RSC context.");
+  throw serverOnlyStubError("headers");
 }
 
 /**
  * Error-throwing stub for server-only `createReverse` function.
  */
 export function createReverse(): never {
-  throw new Error("createReverse() is server-only and requires RSC context.");
+  throw serverOnlyStubError("createReverse");
 }
 
 /**
  * Error-throwing stub for server-only `enableMatchDebug` function.
  */
 export function enableMatchDebug(): never {
-  throw new Error(
-    "enableMatchDebug() is server-only and requires RSC context.",
-  );
+  throw serverOnlyStubError("enableMatchDebug");
 }
 
 /**
  * Error-throwing stub for server-only `getMatchDebugStats` function.
  */
 export function getMatchDebugStats(): never {
-  throw new Error(
-    "getMatchDebugStats() is server-only and requires RSC context.",
-  );
+  throw serverOnlyStubError("getMatchDebugStats");
 }
 
 // Error-throwing stubs for server-only route helpers
 export function layout(): never {
-  throw new Error("layout() is server-only and requires RSC context.");
+  throw serverOnlyStubError("layout");
 }
 export function cache(): never {
-  throw new Error("cache() is server-only and requires RSC context.");
+  throw serverOnlyStubError("cache");
 }
 export function middleware(): never {
-  throw new Error("middleware() is server-only and requires RSC context.");
+  throw serverOnlyStubError("middleware");
 }
 export function revalidate(): never {
-  throw new Error("revalidate() is server-only and requires RSC context.");
+  throw serverOnlyStubError("revalidate");
 }
 export function loader(): never {
-  throw new Error("loader() is server-only and requires RSC context.");
+  throw serverOnlyStubError("loader");
 }
 export function loading(): never {
-  throw new Error("loading() is server-only and requires RSC context.");
+  throw serverOnlyStubError("loading");
 }
 export function parallel(): never {
-  throw new Error("parallel() is server-only and requires RSC context.");
+  throw serverOnlyStubError("parallel");
 }
 export function intercept(): never {
-  throw new Error("intercept() is server-only and requires RSC context.");
+  throw serverOnlyStubError("intercept");
 }
 export function when(): never {
-  throw new Error("when() is server-only and requires RSC context.");
+  throw serverOnlyStubError("when");
 }
 export function errorBoundary(): never {
-  throw new Error("errorBoundary() is server-only and requires RSC context.");
+  throw serverOnlyStubError("errorBoundary");
 }
 export function notFoundBoundary(): never {
-  throw new Error(
-    "notFoundBoundary() is server-only and requires RSC context.",
-  );
+  throw serverOnlyStubError("notFoundBoundary");
 }
 export function transition(): never {
-  throw new Error("transition() is server-only and requires RSC context.");
+  throw serverOnlyStubError("transition");
 }
 
 // Request context type (safe for client)

package/src/prerender/store.ts

@@ -2,9 +2,10 @@
  * Prerender Store
  *
  * Reads pre-rendered segment data from the worker bundle at build time.
- * The data is stored as globalThis.__PRERENDER_MANIFEST, a map of
- * "<routeName>/<paramHash>" to dynamic import functions that resolve
- * individual prerender entry modules.
+ * The manifest module is lazily loaded via globalThis.__loadPrerenderManifestModule,
+ * a function injected into the RSC entry that returns the manifest module
+ * containing a key-to-specifier map and a `loadPrerenderAsset` function
+ * that anchors import() resolution relative to the manifest file.
  */
 
 import type {
@@ -34,11 +35,20 @@ export interface StaticStore {
   get(handlerId: string): Promise<StaticEntry | null>;
 }
 
+interface PrerenderManifestModule {
+  default: Record<string, string>;
+  loadPrerenderAsset: (
+    specifier: string,
+  ) => Promise<{ default: PrerenderEntry }>;
+}
+
 declare global {
-  // Injected by closeBundle post-processing: map of key -> () => import("./assets/__pr-*.js")
+  // Injected by closeBundle post-processing: lazy loader for the prerender
+  // manifest module. The module exports a key→specifier map and a
+  // loadPrerenderAsset function that anchors import() relative to the manifest.
   // eslint-disable-next-line no-var
-  var __PRERENDER_MANIFEST:
-    | Record<string, () => Promise<{ default: PrerenderEntry }>>
+  var __loadPrerenderManifestModule:
+    | (() => Promise<PrerenderManifestModule>)
     | undefined;
   // Injected by closeBundle post-processing: map of handlerId -> () => import("./assets/__st-*.js")
   // Asset default export is either a string (no handles) or { encoded, handles } object.
@@ -78,17 +88,28 @@ export function createDevPrerenderStore(devUrl: string): PrerenderStore {
 /**
  * Create a prerender store.
  * Dev mode: on-demand fetch from Vite dev server (node:fs works there).
- * Production: backed by globalThis.__PRERENDER_MANIFEST injected at build time.
+ * Production: backed by globalThis.__loadPrerenderManifestModule which lazily
+ * loads the manifest module on first access.
  * Returns null if no prerender data is available.
  */
 export function createPrerenderStore(): PrerenderStore | null {
   if (globalThis.__PRERENDER_DEV_URL) {
     return createDevPrerenderStore(globalThis.__PRERENDER_DEV_URL);
   }
-  const manifest = globalThis.__PRERENDER_MANIFEST;
-  if (!manifest || Object.keys(manifest).length === 0) return null;
+  if (!globalThis.__loadPrerenderManifestModule) return null;
 
   const cache = new Map<string, Promise<PrerenderEntry | null>>();
+  let manifestModulePromise: Promise<PrerenderManifestModule | null> | null =
+    null;
+
+  function loadManifestModule(): Promise<PrerenderManifestModule | null> {
+    if (!manifestModulePromise) {
+      manifestModulePromise = globalThis.__loadPrerenderManifestModule!().catch(
+        () => null,
+      );
+    }
+    return manifestModulePromise;
+  }
 
   return {
     get(routeName: string, paramHash: string): Promise<PrerenderEntry | null> {
@@ -96,18 +117,38 @@ export function createPrerenderStore(): PrerenderStore | null {
       const cached = cache.get(key);
       if (cached) return cached;
 
-      const loader = manifest[key];
-      if (!loader) return Promise.resolve(null);
-
-      const promise = loader()
-        .then((mod) => mod.default)
-        .catch(() => null);
+      const promise = loadManifestModule().then((mod) => {
+        if (!mod) return null;
+        const specifier = mod.default[key];
+        if (!specifier) return null;
+        return mod
+          .loadPrerenderAsset(specifier)
+          .then((asset) => asset.default)
+          .catch(() => null);
+      });
       cache.set(key, promise);
       return promise;
     },
   };
 }
 
+/**
+ * Load the prerender manifest index for test introspection.
+ * Returns the key→specifier map or null if unavailable.
+ */
+export async function loadPrerenderManifestIndex(): Promise<Record<
+  string,
+  string
+> | null> {
+  if (!globalThis.__loadPrerenderManifestModule) return null;
+  try {
+    const mod = await globalThis.__loadPrerenderManifestModule();
+    return mod.default;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Create a static segment store.
  * Production only: backed by globalThis.__STATIC_MANIFEST injected at build time.

package/src/route-definition/index.ts

@@ -1,6 +1,3 @@
-// Route definition
-export { route, type RouteDefinitionResult } from "./route-function.js";
-
 // Type definitions
 export type { RouteHelpers } from "./helpers-types.js";
 export type {