@rangojs/router 0.0.0-experimental.259 → 0.0.0-experimental.26

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.0.0-experimental.259",
+  "version": "0.0.0-experimental.26",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",
@@ -31,7 +31,7 @@
     "!src/**/*.test.tsx",
     "dist",
     "skills",
-    "CLAUDE.md",
+    "AGENTS.md",
     "README.md"
   ],
   "type": "module",
@@ -152,7 +152,7 @@
     "vitest": "^4.0.0"
   },
   "peerDependencies": {
-    "@cloudflare/vite-plugin": "^1.25.6",
+    "@cloudflare/vite-plugin": "^1.25.0",
     "@vitejs/plugin-rsc": "^0.5.14",
     "react": "^18.0.0 || ^19.0.0",
     "vite": "^7.3.0"

package/skills/cache-guide/SKILL.md

@@ -67,9 +67,11 @@ HIT  → function body skipped, calling code runs, handle data replayed
 MISS → function body runs, return value + handle data cached
 ```
 
-Runtime guards throw if you call ctx.header(), ctx.set(), ctx.setCookie(),
+Runtime guards throw if you call cookies(), headers(), ctx.header(), ctx.set(),
 ctx.onResponse(), ctx.setTheme(), or ctx.setLocationState() inside a "use cache"
-function. Use ctx.use(Handle) instead — handle data is captured and replayed.
+function. cookies() and headers() are blocked because per-request data is not in the
+cache key. Side-effect methods are blocked because their effects are lost on hit.
+Use ctx.use(Handle) instead for data — handle data is captured and replayed.
 
 ## When to Use cache()
 
@@ -149,8 +151,8 @@ Neither mechanism caches response headers or cookies.
 - **cache()**: Headers set by handlers are naturally absent on hit because no
   handler runs. If you need headers on every response, set them in middleware
   (which runs before cache lookup).
-- **"use cache"**: ctx.header() and ctx.setCookie() throw inside the cached
-  function. Move them outside.
+- **"use cache"**: cookies() and headers() throw inside the cached function
+  (both reads and writes). ctx.header() also throws. Move them outside.
 
 ```typescript
 // Set headers that must appear on every response in middleware
@@ -234,7 +236,9 @@ path("/product/:slug", ProductPage, { name: "product" }, () => [
 ```
 
 This attaches the cache config directly to the loader entry. The loader's
-data is cached independently from the route's segment cache.
+data is cached independently from the route's segment cache. Loader caching
+supports custom keys, tags, SWR, conditional bypass, and per-loader store
+overrides — see `/loader` for the full reference.
 
 ## Decision Flowchart
 

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() {
@@ -238,22 +239,6 @@ export const FileUploadLoader = createLoader(async (ctx) => {
 }, true); // true = fetchable (can be called from the client via load())
 ```
 
-### useLoaderData()
-
-Get all loader data in current context:
-
-```tsx
-"use client";
-import { useLoaderData } from "@rangojs/router";
-
-function DebugPanel() {
-  const allData = useLoaderData();
-  // Record<string, any> - Map of loader ID to data
-
-  return <pre>{JSON.stringify(allData, null, 2)}</pre>;
-}
-```
-
 ## Handle Hooks
 
 ### useHandle()
@@ -262,7 +247,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 +309,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 +344,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.
@@ -398,6 +383,33 @@ import { ProductState } from "./state";
 </Link>;
 ```
 
+Pass typed state just in time (getter evaluated at click time, not render time):
+
+```tsx
+"use client"; // JIT state requires a client component (getter can't cross RSC boundary)
+
+import { Link } from "@rangojs/router/client";
+import { ProductState } from "./state";
+
+// The getter is stored lazily and only called when the user clicks the link.
+// This is useful for capturing values that change after render (e.g., scroll
+// position, form state, ref values).
+<Link
+  to="/product/123"
+  state={[ProductState(() => ({ name: product.name, price: product.price }))]}
+>
+  View Product
+</Link>;
+```
+
+Plain state can also be evaluated just in time (also requires a client component):
+
+```tsx
+<Link to="/product/123" state={() => ({ from: window.location.pathname })}>
+  View Product
+</Link>
+```
+
 ### Flash State (read-once)
 
 Create a location state with `{ flash: true }` for read-once state that
@@ -457,7 +469,7 @@ Or via `ctx.setLocationState()` on any response:
 
 ```tsx
 (ctx) => {
-  ctx.setLocationState([FlashMessage({ text: "Welcome back!" })]);
+  ctx.setLocationState(FlashMessage({ text: "Welcome back!" }));
   return <Dashboard />;
 };
 ```
@@ -482,7 +494,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();
@@ -510,7 +522,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 (
@@ -531,7 +543,7 @@ Access outlet content programmatically:
 
 ```tsx
 "use client";
-import { useOutlet } from "@rangojs/router";
+import { useOutlet } from "@rangojs/router/client";
 
 function ConditionalLayout() {
   const outlet = useOutlet();
@@ -668,7 +680,6 @@ See `/links` for full URL generation guide including server-side `ctx.reverse`.
 | `useLinkStatus()`    | Link pending state                | { pending }                                     |
 | `useLoader()`        | Loader data (strict)              | data, isLoading, error                          |
 | `useFetchLoader()`   | Loader with on-demand fetch       | data, load, isLoading                           |
-| `useLoaderData()`    | All loader data                   | Record<string, any>                             |
 | `useHandle()`        | Accumulated handle data           | T (handle type)                                 |
 | `useAction()`        | Server action state               | state, error, result                            |
 | `useLocationState()` | History state (persists or flash) | T \| undefined                                  |

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

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