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

package/README.md

@@ -45,6 +45,30 @@ For Cloudflare Workers:
 npm install @cloudflare/vite-plugin
 ```
 
+## Import Paths
+
+Use these import paths consistently:
+
+- `@rangojs/router` — server/RSC router APIs, route DSL, `createRouter`, `urls`, `redirect`, `Prerender`, `Static`, shared types
+- `@rangojs/router/client` — hooks and components such as `Link`, `Outlet`, `href`, `useNavigation`, `useLoader`, `useAction`, `useLocationState`
+- `@rangojs/router/cache` — public cache APIs such as `CFCacheStore`, `MemorySegmentCacheStore`, `createDocumentCacheMiddleware`
+- `@rangojs/router/host`, `@rangojs/router/theme`, `@rangojs/router/vite` — specialized public subpaths
+- `@rangojs/router/rsc`, `@rangojs/router/ssr` — advanced server-only integration subpaths for custom request/HTML pipelines
+
+Use only subpaths that are explicitly exported from the package. Avoid deep imports such as `@rangojs/router/cache/cf`.
+
+`@rangojs/router` is conditionally resolved. Server-only root APIs such as
+`createRouter()`, `urls()`, `redirect()`, `Prerender()`, and `cookies()` rely on
+the `react-server` export condition and are meant to run in router definitions,
+handlers, and other RSC/server modules. Outside that environment the root entry
+falls back to stub implementations that throw guidance errors.
+
+If you hit a root-entrypoint stub error:
+
+- hooks and components like `Link`, `Outlet`, `useLoader`, `useNavigation`, and `MetaTags` belong in `@rangojs/router/client`
+- cache APIs like `CFCacheStore` and `createDocumentCacheMiddleware` belong in `@rangojs/router/cache`
+- host-router APIs belong in `@rangojs/router/host`
+
 ## Quick Start
 
 ### Vite Config
@@ -62,6 +86,9 @@ export default defineConfig({
 
 ### Router
 
+This file is a server/RSC module and should import router construction APIs from
+`@rangojs/router`.
+
 ```tsx
 // src/router.tsx
 import { createRouter, urls } from "@rangojs/router";
@@ -842,16 +869,22 @@ module, use `scopedReverse<typeof localPatterns>(ctx.reverse)` or
 
 ## Subpath Exports
 
-| Export                   | Description                                                                       |
-| ------------------------ | --------------------------------------------------------------------------------- |
-| `@rangojs/router`        | Core: `createRouter`, `urls`, `createLoader`, `Handler`, `Prerender`, `Meta`      |
-| `@rangojs/router/client` | Client: `Link`, `Outlet`, `href`, `useNavigation`, `useLoader`, `MetaTags`        |
-| `@rangojs/router/cache`  | Cache: `CFCacheStore`, `MemorySegmentCacheStore`, `createDocumentCacheMiddleware` |
-| `@rangojs/router/theme`  | Theme: `useTheme`, `ThemeProvider`, `ThemeScript`                                 |
-| `@rangojs/router/host`   | Host routing: `createHostRouter`, `defineHosts`                                   |
-| `@rangojs/router/vite`   | Vite plugin: `rango()`                                                            |
-| `@rangojs/router/server` | Server utilities                                                                  |
-| `@rangojs/router/build`  | Build utilities                                                                   |
+| Export                   | Description                                                                                              |
+| ------------------------ | -------------------------------------------------------------------------------------------------------- |
+| `@rangojs/router`        | Server/RSC core and shared types: `createRouter`, `urls`, `createLoader`, `Handler`, `Prerender`, `Meta` |
+| `@rangojs/router/client` | Client: `Link`, `Outlet`, `href`, `useNavigation`, `useLoader`, `MetaTags`                               |
+| `@rangojs/router/cache`  | Cache: `CFCacheStore`, `MemorySegmentCacheStore`, `createDocumentCacheMiddleware`                        |
+| `@rangojs/router/theme`  | Theme: `useTheme`, `ThemeProvider`, `ThemeScript`                                                        |
+| `@rangojs/router/host`   | Host routing: `createHostRouter`, `defineHosts`                                                          |
+| `@rangojs/router/vite`   | Vite plugin: `rango()`                                                                                   |
+| `@rangojs/router/rsc`    | Advanced server pipeline APIs: `createRSCHandler`, request-context access                                |
+| `@rangojs/router/ssr`    | Advanced SSR bridge APIs: `createSSRHandler`                                                             |
+| `@rangojs/router/server` | Internal build/runtime utilities for advanced integrations                                               |
+| `@rangojs/router/build`  | Build utilities                                                                                          |
+
+The root entrypoint is not a generic client/runtime barrel. If you need hooks
+or components, import from `@rangojs/router/client`; if you need cache or host
+APIs, use their dedicated subpaths.
 
 ## Examples
 

package/dist/vite/index.js

@@ -1745,7 +1745,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.0.0-experimental.21",
+  version: "0.0.0-experimental.22",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",
@@ -3733,8 +3733,7 @@ async function discoverRouters(state, rscEnv) {
   let registry = serverMod.RouterRegistry;
   if (!registry || registry.size === 0) {
     try {
-      const hostMod = await rscEnv.runner.import("@rangojs/router/host");
-      const hostRegistry = hostMod.HostRouterRegistry;
+      const hostRegistry = serverMod.HostRouterRegistry;
       if (hostRegistry && hostRegistry.size > 0) {
         console.log(
           `[rsc-router] Found ${hostRegistry.size} host router(s), resolving lazy handlers...`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.0.0-experimental.21",
+  "version": "0.0.0-experimental.22",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",

package/skills/caching/SKILL.md

@@ -89,7 +89,7 @@ Configure a cache store in the router:
 
 ```typescript
 import { createRouter } from "@rangojs/router";
-import { MemorySegmentCacheStore } from "@rangojs/router/rsc";
+import { MemorySegmentCacheStore } from "@rangojs/router/cache";
 
 const store = new MemorySegmentCacheStore({
   defaults: { ttl: 60, swr: 300 },
@@ -112,7 +112,7 @@ const router = createRouter({
 For single-instance deployments:
 
 ```typescript
-import { MemorySegmentCacheStore } from "@rangojs/router/rsc";
+import { MemorySegmentCacheStore } from "@rangojs/router/cache";
 
 const store = new MemorySegmentCacheStore({
   defaults: { ttl: 60, swr: 300 },
@@ -125,7 +125,7 @@ const store = new MemorySegmentCacheStore({
 For distributed caching on Cloudflare Workers:
 
 ```typescript
-import { CFCacheStore } from "@rangojs/router/cache/cf";
+import { CFCacheStore } from "@rangojs/router/cache";
 
 const router = createRouter<AppBindings>({
   document: Document,
@@ -175,7 +175,7 @@ cache({ store: checkoutCache }, () => [
 
 ```typescript
 import { urls } from "@rangojs/router";
-import { MemorySegmentCacheStore } from "@rangojs/router/rsc";
+import { MemorySegmentCacheStore } from "@rangojs/router/cache";
 
 // Custom store for checkout (short TTL)
 const checkoutCache = new MemorySegmentCacheStore({

package/skills/document-cache/SKILL.md

@@ -14,7 +14,7 @@ Configure document cache in router:
 
 ```typescript
 import { createRouter } from "@rangojs/router";
-import { CFCacheStore } from "@rangojs/router/cache/cf";
+import { CFCacheStore } from "@rangojs/router/cache";
 import { urlpatterns } from "./urls";
 
 const router = createRouter<AppBindings>({
@@ -134,7 +134,7 @@ Segment hash ensures different cached responses for navigations from different s
 ```typescript
 // router.tsx
 import { createRouter } from "@rangojs/router";
-import { CFCacheStore } from "@rangojs/router/cache/cf";
+import { CFCacheStore } from "@rangojs/router/cache";
 import { urlpatterns } from "./urls";
 
 const router = createRouter<AppBindings>({

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/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 {

package/src/router/router-options.ts

@@ -239,7 +239,7 @@ export interface RSCRouterOptions<TEnv = any> {
    *
    * @example Static config
    * ```typescript
-   * import { MemorySegmentCacheStore } from "rsc-router/rsc";
+   * import { MemorySegmentCacheStore } from "@rangojs/router/cache";
    *
    * const router = createRouter({
    *   cache: {

package/src/rsc/index.ts

@@ -29,28 +29,8 @@ export type {
   NonceProvider,
 } from "./types.js";
 
-// Re-export HandleStore types for consumers who need custom handling
-export {
-  createHandleStore,
-  type HandleStore,
-  type HandleData,
-} from "../server/handle-store.js";
-
 // Re-export request context utilities for server-side access to env/request/params
 export {
   getRequestContext,
   requireRequestContext,
-  setRequestContextParams,
 } from "../server/request-context.js";
-
-// Re-export cache store types and implementations
-export type {
-  SegmentCacheStore,
-  CachedEntryData,
-  CachedEntryResult,
-  SegmentCacheProvider,
-  SegmentHandleData,
-} from "../cache/types.js";
-
-export { MemorySegmentCacheStore } from "../cache/memory-segment-store.js";
-export { CFCacheStore, type CFCacheStoreOptions } from "../cache/cf/index.js";

package/src/server.ts

@@ -11,6 +11,12 @@
 // Router registry (used by Vite plugin for build-time discovery)
 export { RSC_ROUTER_BRAND, RouterRegistry } from "./router.js";
 
+// Host router registry (used by Vite plugin for host-router lazy discovery)
+export {
+  HostRouterRegistry,
+  type HostRouterRegistryEntry,
+} from "./host/router.js";
+
 // Route map builder (Vite plugin injects these via virtual modules)
 export {
   registerRouteMap,

package/src/theme/index.ts

@@ -1,9 +1,10 @@
 /**
  * Theme module exports for @rangojs/router/theme
  *
- * This module provides theme management for rsc-router:
+ * This module provides the public theme API:
  * - useTheme: Hook for accessing theme state in client components
  * - ThemeProvider: Component for manual theme provider setup (typically not needed)
+ * - ThemeScript: FOUC-prevention script component for document/head usage
  * - Types for theme configuration
  *
  * @example
@@ -43,15 +44,5 @@ export type {
   ThemeContextValue,
 } from "./types.js";
 
-// Constants (for advanced use cases)
-export {
-  THEME_DEFAULTS,
-  THEME_COOKIE,
-  resolveThemeConfig,
-} from "./constants.js";
-
-// Script generation (for advanced SSR use cases)
-export { generateThemeScript, getNonceAttribute } from "./theme-script.js";
-
-// Context (for advanced use cases)
-export { ThemeContext, useThemeContext } from "./theme-context.js";
+// Constants
+export { THEME_DEFAULTS, THEME_COOKIE } from "./constants.js";

package/src/vite/discovery/discover-routers.ts

@@ -48,9 +48,8 @@ export async function discoverRouters(
     // No RSC routers found directly. Check for host routers with lazy handlers
     // that need to be resolved to trigger sub-app createRouter() calls.
     try {
-      const hostMod = await rscEnv.runner.import("@rangojs/router/host");
       const hostRegistry: Map<string, any> | undefined =
-        hostMod.HostRouterRegistry;
+        serverMod.HostRouterRegistry;
 
       if (hostRegistry && hostRegistry.size > 0) {
         console.log(
@@ -89,7 +88,7 @@ export async function discoverRouters(
         }
       }
     } catch {
-      // @rangojs/router/host not available or import failed, skip
+      // Host-router discovery is best-effort; skip if unavailable
     }
 
     // If still no routers after host router resolution, fail

package/skills/testing/SKILL.md

@@ -1,226 +0,0 @@
----
-name: testing
-description: Unit test route trees with buildRouteTree()
-argument-hint:
----
-
-# Route Tree Unit Testing
-
-Unit test route definitions by inspecting the route tree, segment IDs, middleware, intercepts, loaders, and pattern matching without running a dev server.
-
-## Setup
-
-The `buildRouteTree` helper lives in `src/__tests__/helpers/route-tree.ts` (not shipped with npm). Import it in your test files:
-
-```typescript
-import { buildRouteTree } from "./helpers/route-tree.js";
-```
-
-## buildRouteTree(urlPatterns)
-
-Takes a `urls()` result and returns a `RouteTree` with inspection methods:
-
-```typescript
-import { urls } from "@rangojs/router";
-import { buildRouteTree } from "./helpers/route-tree.js";
-
-const tree = buildRouteTree(
-  urls(({ path, layout, middleware, loader, intercept, when }) => [
-    layout(RootLayout, () => [
-      middleware(authMiddleware),
-      path("/", HomePage, { name: "home" }),
-      path("/blog/:slug", BlogPost, { name: "blog.post" }, () => [
-        loader(PostLoader),
-      ]),
-    ]),
-  ]),
-);
-```
-
-## RouteTree API
-
-### Route Patterns
-
-```typescript
-tree.routes(); // { home: "/", "blog.post": "/blog/:slug" }
-tree.routeNames(); // ["home", "blog.post"]
-```
-
-### URL Matching
-
-```typescript
-const m = tree.match("/blog/hello");
-m.routeKey; // "blog.post"
-m.params; // { slug: "hello" }
-
-tree.match("/nonexistent"); // null
-```
-
-### Segment IDs
-
-```typescript
-tree.segmentId("home"); // "M0L0L0R0"
-tree.segmentIds(); // { home: "M0L0L0R0", "blog.post": "M0L0L0R1" }
-tree.segmentPath("blog.post");
-// [
-//   { id: "M0L0",     type: "layout" },  // synthetic root
-//   { id: "M0L0L0",   type: "layout" },  // RootLayout
-//   { id: "M0L0L0R1", type: "route", pattern: "/blog/:slug" },
-// ]
-```
-
-### Entry Access
-
-```typescript
-tree.entry("blog.post"); // EntryData
-tree.entry("blog.post")!.parent!.type; // "layout"
-tree.entryByPattern("/blog/:slug"); // EntryData (lookup by URL pattern)
-```
-
-### Middleware
-
-```typescript
-tree.hasMiddleware("home"); // true (inherited from layout)
-tree.middleware("home"); // [authMiddleware] (direct only)
-tree.middlewareChain("home");
-// [{ segmentId: "M0L0L0", count: 1 }]   // all middleware root-to-route
-```
-
-### Loaders
-
-```typescript
-tree.hasLoaders("blog.post"); // true
-tree.loaders("blog.post"); // [LoaderEntry { loader, revalidate, cache? }]
-```
-
-### Intercepts
-
-```typescript
-tree.intercepts("home");
-// [{ slotName: "@modal", routeName: "card", hasWhen: true, whenCount: 1, hasLoader: false, hasMiddleware: false }]
-tree.interceptEntries("home"); // raw InterceptEntry[]
-```
-
-### Parallel Slots
-
-```typescript
-tree.parallelSlots("home"); // EntryData[] of type="parallel"
-tree.parallelSlotNames("home"); // ["@sidebar", "@main"]
-```
-
-### Boundaries
-
-```typescript
-tree.hasErrorBoundary("home"); // boolean
-tree.hasNotFoundBoundary("home"); // boolean
-```
-
-### Cache & Loading
-
-```typescript
-tree.hasCache("home"); // boolean
-tree.hasLoading("home"); // boolean
-```
-
-### Debug
-
-```typescript
-console.log(tree.debug());
-// Route Tree:
-//   home: / [M0L0L0R0] (M0L0 > M0L0L0 > M0L0L0R0) {mw:1}
-//   blog.post: /blog/:slug [M0L0L0R1] (M0L0 > M0L0L0 > M0L0L0R1) {mw:1, ld:1}
-```
-
-## Segment ID Format
-
-| Prefix | Meaning                       |
-| ------ | ----------------------------- |
-| `M0`   | Mount index (router instance) |
-| `L`    | Layout                        |
-| `R`    | Route                         |
-| `P`    | Parallel slot                 |
-| `D`    | Loader (data)                 |
-| `C`    | Cache boundary                |
-
-Example: `M0L0L0R1` = mount 0, synthetic root layout, user layout, second route.
-
-## Examples
-
-### include() with prefix
-
-```typescript
-const blogPatterns = urls(({ path }) => [
-  path("/", BlogIndex, { name: "index" }),
-  path("/:slug", BlogPost, { name: "post" }),
-]);
-
-const tree = buildRouteTree(
-  urls(({ path, include }) => [
-    path("/", HomePage, { name: "home" }),
-    include("/blog", blogPatterns, { name: "blog" }),
-  ]),
-);
-
-expect(tree.routes()).toEqual({
-  home: "/",
-  "blog.index": "/blog",
-  "blog.post": "/blog/:slug",
-});
-```
-
-### Middleware chain
-
-```typescript
-const authMw = async (ctx, next) => next();
-const logMw = async (ctx, next) => next();
-
-const tree = buildRouteTree(
-  urls(({ path, layout, middleware }) => [
-    layout(RootLayout, () => [
-      middleware(logMw),
-      layout(AuthLayout, () => [
-        middleware(authMw),
-        path("/dashboard", Dashboard, { name: "dashboard" }),
-      ]),
-    ]),
-  ]),
-);
-
-expect(tree.middlewareChain("dashboard")).toEqual([
-  { segmentId: "M0L0L0", count: 1 }, // logMw on RootLayout
-  { segmentId: "M0L0L0L0", count: 1 }, // authMw on AuthLayout
-]);
-```
-
-### Intercepts with when()
-
-```typescript
-const tree = buildRouteTree(
-  urls(({ path, layout, intercept, when }) => [
-    layout(ShopLayout, () => [
-      path("/products", ProductList, { name: "products" }),
-      path("/products/:id", ProductDetail, { name: "product.detail" }),
-      intercept("@modal", "product.detail", ProductModal, () => [
-        when((ctx) => ctx.from.pathname.startsWith("/products")),
-      ]),
-    ]),
-  ]),
-);
-
-const intercepts = tree.intercepts("products");
-// Note: intercepts are on the parent where intercept() is called
-```
-
-### Constrained parameters
-
-```typescript
-const tree = buildRouteTree(
-  urls(({ path }) => [
-    path("/:locale(en|fr)?/about", AboutPage, { name: "about" }),
-  ]),
-);
-
-expect(tree.match("/about")).not.toBeNull();
-expect(tree.match("/fr/about")!.params).toEqual({ locale: "fr" });
-expect(tree.match("/de/about")).toBeNull();
-```

package/src/route-definition/route-function.ts

@@ -1,119 +0,0 @@
-import type {
-  ResolvedRouteMap,
-  RouteConfig,
-  RouteDefinition,
-  RouteDefinitionOptions,
-  TrailingSlashMode,
-} from "../types.js";
-
-/**
- * Result of route() function with paths and trailing slash config
- */
-export interface RouteDefinitionResult<T extends RouteDefinition> {
-  routes: ResolvedRouteMap<T>;
-  trailingSlash: Record<string, TrailingSlashMode>;
-}
-
-/**
- * Check if a value is a RouteConfig object
- */
-function isRouteConfig(value: unknown): value is RouteConfig {
-  return (
-    typeof value === "object" &&
-    value !== null &&
-    "path" in value &&
-    typeof (value as RouteConfig).path === "string"
-  );
-}
-
-/**
- * Define routes with optional trailing slash configuration
- *
- * @example
- * ```typescript
- * // Simple string paths
- * const routes = route({
- *   blog: "/blog",
- *   post: "/blog/:id",
- * });
- *
- * // With trailing slash config
- * const routes = route({
- *   blog: "/blog",
- *   api: { path: "/api", trailingSlash: "ignore" },
- * }, { trailingSlash: "never" }); // global default
- * ```
- */
-export function route<const T extends RouteDefinition>(
-  input: T,
-  options?: RouteDefinitionOptions,
-): ResolvedRouteMap<T> & {
-  __trailingSlash?: Record<string, TrailingSlashMode>;
-} {
-  const trailingSlash: Record<string, TrailingSlashMode> = {};
-  const routes = flattenRoutes(
-    input as RouteDefinition,
-    "",
-    trailingSlash,
-    options?.trailingSlash,
-  );
-
-  // Attach trailing slash config as a non-enumerable property
-  // This keeps backwards compatibility while passing the config through
-  const result = routes as ResolvedRouteMap<T> & {
-    __trailingSlash?: Record<string, TrailingSlashMode>;
-  };
-  if (Object.keys(trailingSlash).length > 0) {
-    Object.defineProperty(result, "__trailingSlash", {
-      value: trailingSlash,
-      enumerable: false,
-      writable: false,
-    });
-  }
-
-  return result;
-}
-
-/**
- * Flatten nested route definitions
- */
-function flattenRoutes(
-  routes: RouteDefinition,
-  prefix: string,
-  trailingSlashConfig: Record<string, TrailingSlashMode>,
-  defaultTrailingSlash?: TrailingSlashMode,
-): Record<string, string> {
-  const flattened: Record<string, string> = {};
-
-  for (const [key, value] of Object.entries(routes)) {
-    const fullKey = prefix + key;
-
-    if (typeof value === "string") {
-      // Direct route pattern - include prefix
-      flattened[fullKey] = value;
-      // Apply default trailing slash if set
-      if (defaultTrailingSlash) {
-        trailingSlashConfig[fullKey] = defaultTrailingSlash;
-      }
-    } else if (isRouteConfig(value)) {
-      // Route config object with path and optional trailingSlash
-      flattened[fullKey] = value.path;
-      // Use route-specific config or fall back to default
-      const mode = value.trailingSlash ?? defaultTrailingSlash;
-      if (mode) {
-        trailingSlashConfig[fullKey] = mode;
-      }
-    } else {
-      // Nested routes - flatten recursively
-      const nested = flattenRoutes(
-        value,
-        `${fullKey}.`,
-        trailingSlashConfig,
-        defaultTrailingSlash,
-      );
-      Object.assign(flattened, nested);
-    }
-  }
-
-  return flattened;
-}