@rangojs/router 0.0.0-experimental.19 → 0.0.0-experimental.1b930379

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

@@ -65,19 +65,24 @@ export const urlpatterns = urls(({ path, loader }) => [
 
 ## Consuming Loader Data
 
-### In Server Components
+Loaders are the **live data layer** — they resolve fresh on every request.
+The way you consume them depends on whether you're in a server component
+(route handler) or a client component.
 
-```typescript
-import { useLoader } from "@rangojs/router";
-import { ProductLoader } from "./loaders/product";
+> **IMPORTANT: Prefer consuming loaders in client components.** Keeping data
+> fetching in loaders and consumption in client components creates a clean
+> separation: the server-side handler renders static markup that can be
+> freely cached with `cache()`, while loader data stays fresh on every
+> request. When you consume loaders in server handlers via `ctx.use()`, the
+> handler output depends on the loader data, which means caching the handler
+> also caches the data — defeating the purpose of the live data layer.
 
-async function ProductPage() {
-  const { product } = await useLoader(ProductLoader);
-  return <h1>{product.name}</h1>;
-}
-```
+### In Client Components (Preferred)
 
-### In Client Components
+Client components use `useLoader()` from `@rangojs/router/client`.
+The loader **must** be registered with `loader()` in the route's DSL
+segments so the framework knows to resolve it during SSR and stream
+the data to the client:
 
 ```typescript
 "use client";
@@ -90,6 +95,42 @@ function ProductDetails() {
 }
 ```
 
+```typescript
+// Route definition — loader() registration required for client consumption
+path("/product/:slug", ProductPage, { name: "product" }, () => [
+  loader(ProductLoader), // Required for useLoader() in client components
+]);
+```
+
+### In Route Handlers (Server Components)
+
+In server components, use `ctx.use(Loader)` directly in the route handler.
+This doesn't require `loader()` registration in the DSL — it works
+standalone. **However**, prefer client-side consumption when possible (see
+note above).
+
+```typescript
+import { ProductLoader } from "./loaders/product";
+
+// Route handler — server component
+path("/product/:slug", async (ctx) => {
+  const { product } = await ctx.use(ProductLoader);
+  return <h1>{product.name}</h1>;
+}, { name: "product" })
+```
+
+When you do register with `loader()` in the DSL, `ctx.use()` returns the
+same memoized result — loaders never run twice per request.
+
+**Never use `useLoader()` in server components** — it is a client-only API.
+
+### Summary
+
+| Context                      | API                 | `loader()` DSL required? |
+| ---------------------------- | ------------------- | ------------------------ |
+| Client component (preferred) | `useLoader(Loader)` | **Yes**                  |
+| Route handler (server)       | `ctx.use(Loader)`   | No                       |
+
 ## Loader Context
 
 Loaders receive the same context as route handlers:
@@ -538,13 +579,12 @@ export const urlpatterns = urls(({ path, layout, loader, loading, cache, revalid
   ]),
 ]);
 
-// pages/product.tsx
-import { useLoader } from "@rangojs/router";
+// pages/product.tsx — server component (route handler)
 import { ProductLoader, CartLoader } from "./loaders/shop";
 
-async function ProductPage() {
-  const { product } = await useLoader(ProductLoader);
-  const { cart } = await useLoader(CartLoader);
+async function ProductPage(ctx) {
+  const { product } = await ctx.use(ProductLoader);
+  const { cart } = await ctx.use(CartLoader);
 
   return (
     <div>

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

@@ -103,8 +103,8 @@ export const SearchPage: Handler<"search"> = (ctx) => {
 ```
 
 Supported types: `"string"`, `"number"`, `"boolean"`, with `?` suffix for optional.
-Required params default to zero values when missing (`""`, `0`, `false`).
-Optional params are omitted from the result when not in the query string.
+Missing params are `undefined` regardless of required/optional. The required/optional
+distinction is a consumer-facing contract (for `href()` and `reverse()` autocomplete).
 
 Use `RouteSearchParams<"name">` and `RouteParams<"name">` to extract types for props:
 
@@ -355,8 +355,7 @@ urls(({ path, layout }) => [
 ## Complete Example
 
 ```typescript
-import { urls } from "@rangojs/router";
-import { Breadcrumbs } from "./handles/breadcrumbs";
+import { urls, Breadcrumbs } from "@rangojs/router";
 
 export const urlpatterns = urls(({ path, layout, loader, loading }) => [
   // Simple route

package/skills/router-setup/SKILL.md

@@ -78,7 +78,7 @@ interface RSCRouterOptions<TEnv> {
   // Document component wrapping entire app
   document?: ComponentType<{ children: ReactNode }>;
 
-  // Enable performance metrics
+  // Enable per-request performance timeline (console waterfall + Server-Timing header)
   debugPerformance?: boolean;
 
   // Default error boundary
@@ -108,6 +108,11 @@ interface RSCRouterOptions<TEnv> {
   // Connection warmup (default: true)
   warmup?: boolean;
 
+  // Prefetch cache TTL in seconds (default: 300)
+  // Controls in-memory cache duration and Cache-Control max-age for prefetch responses.
+  // Set to false to disable prefetch caching.
+  prefetchCacheTTL?: number | false;
+
   // CSP nonce provider (for router.fetch)
   nonce?: (
     request: Request,
@@ -297,10 +302,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

@@ -281,7 +281,7 @@ import type { RouteSearchParams, RouteParams } from "@rangojs/router";
 
 // RouteSearchParams<"name"> resolves the search schema to a typed object
 type SP = RouteSearchParams<"search">;
-// { q: string; page?: number; sort?: string }
+// { q: string | undefined; page?: number; sort?: string }
 
 // RouteParams<"name"> resolves URL params from the route pattern
 type P = RouteParams<"blogPost">;
@@ -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);
@@ -414,26 +414,30 @@ Both approaches coexist: `ctx.get("user")` (global via Vars) and
 Handles have typed data:
 
 ```typescript
-// handles/breadcrumbs.ts
-import { createHandle } from "@rangojs/router";
-
-// All export patterns work: export const, const + export { X }, export { X as Y }
-export const Breadcrumbs = createHandle<{ label: string; href: string }>();
-
-// In route definition - use handle() DSL
-import { urls } from "@rangojs/router";
-
-export const urlpatterns = urls(({ path, handle }) => [
-  path("/shop/product/:slug", ProductPage, { name: "product" }, () => [
-    handle(Breadcrumbs, { label: "Products", href: "/shop/products" }),
-  ]),
-]);
-
-// In client - typed array
+// Built-in Breadcrumbs handle — import from "@rangojs/router"
+import { Breadcrumbs } from "@rangojs/router";
+// Type: Handle<BreadcrumbItem, BreadcrumbItem[]>
+// BreadcrumbItem: { label: string; href: string; content?: ReactNode | Promise<ReactNode> }
+
+// In route handler — push is fully typed
+path("/shop/product/:slug", (ctx) => {
+  const breadcrumb = ctx.use(Breadcrumbs);
+  breadcrumb({ label: "Products", href: "/shop/products" });
+  return <ProductPage />;
+}, { name: "product" });
+
+// In client — typed array
+import { useHandle, Breadcrumbs } from "@rangojs/router/client";
 function BreadcrumbNav() {
   const crumbs = useHandle(Breadcrumbs);
-  // crumbs: Array<{ label: string; href: string }>
+  // crumbs: BreadcrumbItem[]
 }
+
+// Custom handles also work the same way
+import { createHandle } from "@rangojs/router";
+export const PageTitle = createHandle<string, string>(
+  (segments) => segments.flat().at(-1) ?? "Default Title"
+);
 ```
 
 ## Ref Prop Type Safety (Loaders & Handles)
@@ -447,14 +451,12 @@ export const ProductLoader = createLoader(async (ctx) => {
   return { product: await fetchProduct(ctx.params.slug) };
 });
 
-// handles.ts
-export const Breadcrumbs = createHandle<{ label: string; href: string }>();
+// Built-in Breadcrumbs — or any custom handle created with createHandle()
 
 // Client component — typeof infers all generics
 ("use client");
-import { useLoader, useHandle } from "@rangojs/router/client";
+import { useLoader, useHandle, type Breadcrumbs } from "@rangojs/router/client";
 import type { ProductLoader } from "../loaders";
-import type { Breadcrumbs } from "../handles";
 
 function MyComponent({
   loader,

package/src/__internal.ts

@@ -164,6 +164,98 @@ export type {
  */
 export type { InternalHandlerContext } from "./types.js";
 
+// ============================================================================
+// Rendering (Internal)
+// ============================================================================
+
+/**
+ * @internal
+ * Builds React element trees from route segments.
+ */
+export { renderSegments } from "./segment-system.js";
+
+// ============================================================================
+// Error Utilities (Internal)
+// ============================================================================
+
+/**
+ * @internal
+ * Error sanitization and network error utilities.
+ */
+export { sanitizeError, NetworkError, isNetworkError } from "./errors.js";
+
+// ============================================================================
+// Type Utilities (Internal)
+// ============================================================================
+
+/**
+ * @internal
+ * Scoped view of GeneratedRouteMap for Handler<"localName", ScopedRouteMap<"prefix">>.
+ */
+export type { ScopedRouteMap } from "./types.js";
+
+/**
+ * @internal
+ * Type-level utilities for reverse URL generation.
+ */
+export type { MergeRoutes, SanitizePrefix } from "./reverse.js";
+
+/**
+ * @internal
+ * Individual telemetry event types.
+ */
+export type {
+  RequestStartEvent,
+  RequestEndEvent,
+  RequestErrorEvent,
+  RequestTimeoutEvent,
+  LoaderStartEvent,
+  LoaderEndEvent,
+  LoaderErrorEvent,
+  HandlerErrorEvent,
+  CacheDecisionEvent,
+  RevalidationDecisionEvent,
+} from "./router/telemetry.js";
+
+// ============================================================================
+// Pre-render / Static Handler Guards (Internal)
+// ============================================================================
+
+/**
+ * @internal
+ * Type guard for prerender handler definitions.
+ */
+export { isPrerenderHandler } from "./prerender.js";
+
+/**
+ * @internal
+ * Type guard for static handler definitions.
+ */
+export { isStaticHandler } from "./static-handler.js";
+
+// ============================================================================
+// URL Pattern Internals
+// ============================================================================
+
+/**
+ * @internal
+ * Sentinel used to tag response-type route entries.
+ */
+export { RESPONSE_TYPE } from "./urls.js";
+
+// ============================================================================
+// Route Match Debug (Internal)
+// ============================================================================
+
+/**
+ * @internal
+ * Debug utilities for route matching performance analysis.
+ */
+export {
+  enableMatchDebug,
+  getMatchDebugStats,
+} from "./router/pattern-matching.js";
+
 // ============================================================================
 // Debug Utilities (Internal)
 // ============================================================================

package/src/bin/rango.ts

@@ -6,6 +6,8 @@ import {
   writeCombinedRouteTypes,
   detectUnresolvableIncludes,
   detectUnresolvableIncludesForUrlsFile,
+  findNestedRouterConflict,
+  formatNestedRouterConflictError,
   type UnresolvableInclude,
 } from "../build/generate-route-types.ts";
 
@@ -205,6 +207,14 @@ function runStaticGeneration(args: string[], mode: "default" | "static") {
     console.warn("");
   }
 
+  const nestedRouterConflict = findNestedRouterConflict(routerFiles);
+  if (nestedRouterConflict) {
+    console.error(
+      `\n${formatNestedRouterConflictError(nestedRouterConflict, "[rango]")}\n`,
+    );
+    process.exit(1);
+  }
+
   // Phase 3: Write all outputs (only reached if diagnostics pass or --static)
   for (const urlsFile of urlsFiles) {
     writePerModuleRouteTypesForFile(urlsFile);
@@ -259,6 +269,14 @@ async function runRuntimeDiscovery(args: string[], configFile?: string) {
     process.exit(1);
   }
 
+  const nestedRouterConflict = findNestedRouterConflict(routerEntries);
+  if (nestedRouterConflict) {
+    console.error(
+      `\n${formatNestedRouterConflictError(nestedRouterConflict, "[rango]")}\n`,
+    );
+    process.exit(1);
+  }
+
   let discoverAndWriteRouteTypes: typeof import("../build/runtime-discovery.ts").discoverAndWriteRouteTypes;
   try {
     const mod = await import("../build/runtime-discovery.ts");

package/src/browser/link-interceptor.ts

@@ -117,6 +117,7 @@ export function setupLinkInterception(
     // Read navigation options from data attributes (set by Link component)
     const scrollAttr = link.getAttribute("data-scroll");
     const replaceAttr = link.getAttribute("data-replace");
+    const revalidateAttr = link.getAttribute("data-revalidate");
 
     const navigateOptions: NavigateOptions = {};
     if (scrollAttr === "false") {
@@ -125,6 +126,9 @@ export function setupLinkInterception(
     if (replaceAttr === "true") {
       navigateOptions.replace = true;
     }
+    if (revalidateAttr === "false") {
+      navigateOptions.revalidate = false;
+    }
 
     onNavigate(href, navigateOptions);
   };