@rangojs/router 0.0.0-experimental.002d056c

package/skills/caching/SKILL.md

@@ -0,0 +1,253 @@
+---
+name: caching
+description: Configure segment caching with memory or Cloudflare KV stores in @rangojs/router
+argument-hint: [setup]
+---
+
+# Caching
+
+@rangojs/router supports segment-level caching with stale-while-revalidate (SWR) for optimal performance.
+
+## Route-Level Caching with cache()
+
+Use the `cache()` DSL function to cache routes:
+
+```typescript
+import { urls } from "@rangojs/router";
+
+export const urlpatterns = urls(({ path, cache }) => [
+  // Cache these routes for 60 seconds, SWR for 5 minutes
+  cache({ ttl: 60, swr: 300 }, () => [
+    path("/blog", BlogIndex, { name: "blog" }),
+    path("/blog/:slug", BlogPost, { name: "blogPost" }),
+  ]),
+
+  // Uncached routes
+  path("/account", AccountPage, { name: "account" }),
+]);
+```
+
+## Cache Options
+
+```typescript
+cache(
+  {
+    ttl: 60, // Time-to-live in seconds (default: 60)
+    swr: 300, // Stale-while-revalidate window (default: 300)
+  },
+  () => [
+    // Cached routes
+  ],
+);
+```
+
+## Named Profile Shorthand
+
+Use a named cache profile string instead of an options object. The profile must be
+defined in `createRouter({ cacheProfiles })`. Unknown names throw at boot time.
+
+```typescript
+// Define profiles in router
+createRouter({
+  cacheProfiles: {
+    default: { ttl: 900, swr: 1800 },
+    short: { ttl: 60, swr: 120 },
+    long: { ttl: 3600, swr: 7200 },
+  },
+});
+
+// Use by name in urls
+export const urlpatterns = urls(({ path, cache }) => [
+  cache("long", () => [path("/blog", BlogIndex, { name: "blog" })]),
+
+  // Also works without children (orphan cache boundary)
+  cache("short"),
+  path("/feed", FeedPage, { name: "feed" }),
+]);
+```
+
+These profile names are shared with the `"use cache: <name>"` directive. See
+`/use-cache` for function-level caching.
+
+## Loader-Level Caching
+
+Cache individual loaders:
+
+```typescript
+path("/product/:slug", ProductPage, { name: "product" }, () => [
+  // Cache this loader's results
+  loader(ProductLoader, () => [cache({ ttl: 300 })]),
+
+  // This loader is not cached
+  loader(CartLoader),
+]);
+```
+
+## Global Cache Configuration
+
+Configure a cache store in the router:
+
+```typescript
+import { createRouter } from "@rangojs/router";
+import { MemorySegmentCacheStore } from "@rangojs/router/cache";
+
+const store = new MemorySegmentCacheStore({
+  defaults: { ttl: 60, swr: 300 },
+});
+
+const router = createRouter({
+  document: Document,
+  urls: urlpatterns,
+  cache: {
+    store,
+    enabled: true,
+  },
+});
+```
+
+## Cache Stores
+
+### Memory Store
+
+For single-instance deployments:
+
+```typescript
+import { MemorySegmentCacheStore } from "@rangojs/router/cache";
+
+const store = new MemorySegmentCacheStore({
+  defaults: { ttl: 60, swr: 300 },
+  maxSize: 1000, // Max entries
+});
+```
+
+### Cloudflare Edge Cache Store
+
+For distributed caching on Cloudflare Workers using the Cache API:
+
+```typescript
+import { CFCacheStore } from "@rangojs/router/cache";
+
+const router = createRouter<AppBindings>({
+  document: Document,
+  urls: urlpatterns,
+  cache: (env, ctx) => ({
+    store: new CFCacheStore({
+      ctx,
+      defaults: { ttl: 60, swr: 300 },
+    }),
+    enabled: true,
+  }),
+});
+```
+
+### With KV L2 Persistence
+
+Add a KV namespace for global cross-colo persistence. On Cache API miss, KV is
+checked and hits are promoted back to L1. Writes go to both layers.
+
+```typescript
+import { CFCacheStore } from "@rangojs/router/cache";
+
+const router = createRouter<AppBindings>({
+  document: Document,
+  urls: urlpatterns,
+  cache: (env, ctx) => ({
+    store: new CFCacheStore({
+      ctx,
+      kv: env.CACHE_KV, // optional KV namespace binding
+      defaults: { ttl: 60, swr: 300 },
+    }),
+    enabled: true,
+  }),
+});
+```
+
+**How the two layers work:**
+
+| Scenario     | L1 (Cache API) | L2 (KV) | Result                        |
+| ------------ | -------------- | ------- | ----------------------------- |
+| Hot request  | HIT            | —       | Serve from L1 (fast)          |
+| Cold colo    | MISS           | HIT     | Serve from KV, promote to L1  |
+| First render | MISS           | MISS    | Render, write to both L1 + KV |
+
+KV entries require `expirationTtl >= 60s`. Short-lived entries (< 60s total TTL)
+are only cached in L1.
+
+## Nested Cache Boundaries
+
+Override cache settings for specific sections:
+
+```typescript
+// Global cache
+cache({ ttl: 300 }, () => [
+  path("/blog", BlogIndex, { name: "blog" }),
+
+  // Override: shorter TTL for dynamic content
+  cache({ ttl: 30 }, () => [
+    path("/blog/:slug", BlogPost, { name: "blogPost" }),
+  ]),
+]);
+```
+
+## Custom Cache Store
+
+Create a dedicated store for specific routes:
+
+```typescript
+const checkoutCache = new MemorySegmentCacheStore({
+  defaults: { ttl: 10 },
+});
+
+// In urls
+cache({ store: checkoutCache }, () => [
+  path("/checkout", CheckoutPage, { name: "checkout" }),
+]);
+```
+
+## Complete Example
+
+```typescript
+import { urls } from "@rangojs/router";
+import { MemorySegmentCacheStore } from "@rangojs/router/cache";
+
+// Custom store for checkout (short TTL)
+const checkoutCache = new MemorySegmentCacheStore({
+  defaults: { ttl: 10 },
+});
+
+export const urlpatterns = urls(({ path, layout, cache, loader, revalidate }) => [
+  // Public routes with aggressive caching
+  cache({ ttl: 300, swr: 600 }, () => [
+    path("/", HomePage, { name: "home" }),
+    path("/about", AboutPage, { name: "about" }),
+  ]),
+
+  // Blog routes with moderate caching
+  cache({ ttl: 60, swr: 300 }, () => [
+    layout(<BlogLayout />, () => [
+      path("/blog", BlogIndex, { name: "blog" }),
+      path("/blog/:slug", BlogPost, { name: "blogPost" }, () => [
+        loader(BlogPostLoader, () => [cache()]),  // Use boundary cache settings
+      ]),
+    ]),
+  ]),
+
+  // Shop routes with per-loader caching
+  layout(<ShopLayout />, () => [
+    path("/shop/product/:slug", ProductPage, { name: "product" }, () => [
+      loader(ProductLoader, () => [cache({ ttl: 120 })]),
+      loader(CartLoader, () => [
+        revalidate(({ actionId }) => actionId?.includes("Cart") ?? false),
+      ]),
+    ]),
+  ]),
+
+  // Checkout with custom cache store
+  cache({ store: checkoutCache }, () => [
+    path("/checkout", CheckoutPage, { name: "checkout" }),
+  ]),
+
+  // No cache for account pages
+  path("/account", AccountPage, { name: "account" }),
+]);
+```

package/skills/composability/SKILL.md

@@ -0,0 +1,172 @@
+---
+name: composability
+description: Reusable composition patterns with globally importable route helpers in @rangojs/router
+argument-hint: "pattern-name"
+---
+
+# Composability
+
+Route helpers can be imported directly from `@rangojs/router` and used to build reusable composition factories. This enables sharing common route configurations across multiple routes and modules.
+
+## Globally Importable Helpers
+
+These helpers can be imported and called outside the `urls()` callback parameter:
+
+```typescript
+import {
+  layout,
+  cache,
+  middleware,
+  revalidate,
+  loader,
+  loading,
+  parallel,
+  intercept,
+  when,
+  errorBoundary,
+  notFoundBoundary,
+} from "@rangojs/router";
+```
+
+They work because they use AsyncLocalStorage internally and resolve context at call time, not import time.
+
+## Why path() and include() Are Not Global
+
+`path()` and `include()` remain exclusive to the `urls()` callback:
+
+```typescript
+urls(({ path, include }) => [
+  path("/blog", BlogPage, { name: "blog" }),
+  include("/shop", shopPatterns, { name: "shop" }),
+]);
+```
+
+They define the route structure -- the URL patterns and how modules compose. Keeping them in the `urls()` callback makes the route tree readable at a glance. When scanning a URL file, `path()` and `include()` calls show what renders where. Moving them into factories would hide the routing structure and make it harder to understand which URLs exist and how they nest.
+
+The globally importable helpers (`cache`, `middleware`, `loading`, etc.) are configuration -- they modify behavior of routes but don't define routes themselves. Extracting them into factories doesn't obscure the route structure.
+
+## Composition Factories
+
+Define reusable factories that return arrays of use items:
+
+```typescript
+import { cache, revalidate, loading, errorBoundary, middleware } from "@rangojs/router";
+
+// Shared caching configuration
+const withCaching = () => [
+  cache({ ttl: 600_000 }),
+  revalidate(({ actionId }) => !!actionId),
+];
+
+// Shared loading and error handling
+const withLoadingAndError = (skeleton: ReactNode) => [
+  loading(skeleton),
+  errorBoundary(() => <div>Something went wrong</div>),
+];
+
+// Shared auth middleware
+const withAuth = () => [
+  middleware(authMiddleware),
+  middleware(loggingMiddleware),
+];
+```
+
+## Using Factories in Routes
+
+Place factory calls inside `path()` or `layout()` use callbacks. The returned arrays are flattened automatically (up to 3 levels):
+
+```typescript
+import { urls } from "@rangojs/router";
+import { withCaching, withLoadingAndError, withAuth } from "./route-config";
+
+export const urlpatterns = urls(({ path, layout }) => [
+  layout(<AppLayout />, () => [
+    withAuth(),
+
+    path("/blog", BlogIndex, { name: "blog" }, () => [
+      withCaching(),
+      withLoadingAndError(<BlogSkeleton />),
+    ]),
+
+    path("/shop", ShopIndex, { name: "shop" }, () => [
+      withCaching(),
+      withLoadingAndError(<ShopSkeleton />),
+    ]),
+  ]),
+]);
+```
+
+## Sharing Across Modules
+
+Factories can be defined in shared modules and reused across separate `urls()` definitions:
+
+```typescript
+// src/route-config.ts
+import { cache, revalidate, middleware } from "@rangojs/router";
+import { authMiddleware } from "./middleware/auth";
+
+export const withPublicDefaults = () => [
+  cache({ ttl: 300 }),
+  revalidate(({ actionId }) => !!actionId),
+];
+
+export const withProtectedDefaults = () => [
+  middleware(authMiddleware),
+  cache({ ttl: 60 }),
+];
+```
+
+```typescript
+// src/urls/blog.ts
+import { urls } from "@rangojs/router";
+import { withPublicDefaults } from "../route-config";
+
+export const blogPatterns = urls(({ path }) => [
+  path("/", BlogIndex, { name: "index" }, () => [withPublicDefaults()]),
+]);
+```
+
+```typescript
+// src/urls/admin.ts
+import { urls } from "@rangojs/router";
+import { withProtectedDefaults } from "../route-config";
+
+export const adminPatterns = urls(({ path }) => [
+  path("/", AdminDashboard, { name: "index" }, () => [withProtectedDefaults()]),
+]);
+```
+
+## Composition Types
+
+For typed factories, import the composition types:
+
+```typescript
+import type { RouteUseItem, LayoutUseItem, UseItems } from "@rangojs/router";
+
+// Factory for path() use callbacks
+const withCaching = (): RouteUseItem[] => [
+  cache({ ttl: 600_000 }),
+];
+
+// Factory for layout() use callbacks
+const withAuth = (): LayoutUseItem[] => [
+  middleware(authMiddleware),
+];
+
+// Factory that nests other factories (use UseItems for nested arrays)
+const withEverything = (): UseItems<RouteUseItem> => [
+  withCaching(),
+  loading(<Skeleton />),
+];
+```
+
+- `RouteUseItem[]` -- flat array for `path()` use callbacks
+- `LayoutUseItem[]` -- flat array for `layout()` use callbacks
+- `UseItems<T>` -- allows nested arrays from composing factories together
+
+## Rules
+
+- Helpers execute lazily -- factory functions are defined anywhere, but only called inside a `urls()` context (within `path()` or `layout()` use callbacks)
+- Calling helpers outside a `urls()` context throws an error
+- Nested arrays from factories are flattened automatically via `.flat(3)`
+- `path()` and `include()` cannot be used in factories -- they define route structure and must remain visible in the `urls()` callback

package/skills/debug-manifest/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: debug-manifest
+description: Debug and inspect route manifest structure
+argument-hint:
+---
+
+# Debug Manifest
+
+Inspect the route manifest to verify parent relationships, shortCodes, and route structure.
+
+## Quick Access
+
+In development, visit:
+
+```
+http://localhost:PORT/__debug_manifest
+```
+
+Returns formatted JSON with all routes and layouts.
+
+## Programmatic Access
+
+```typescript
+import { router } from "./router.js";
+
+// Only in development
+if (process.env.NODE_ENV !== "production") {
+  const manifest = await router.debugManifest();
+  console.log(JSON.stringify(manifest, null, 2));
+}
+```
+
+## Manifest Structure
+
+```json
+{
+  "routes": {
+    "home.index": {
+      "id": "debug.M0.$root.$route.0.home.index",
+      "shortCode": "M0L0R0",
+      "type": "route",
+      "parentShortCode": "M0L0",
+      "pattern": "/",
+      "hasLoader": false,
+      "hasMiddleware": false,
+      "hasErrorBoundary": false,
+      "parallelCount": 0,
+      "interceptCount": 0
+    }
+  },
+  "layouts": {
+    "debug.M0.$root": {
+      "id": "debug.M0.$root",
+      "shortCode": "M0L0",
+      "type": "layout",
+      "parentShortCode": null
+    }
+  },
+  "totalRoutes": 45,
+  "totalLayouts": 18
+}
+```
+
+## ShortCode Format
+
+| Prefix | Meaning                                  |
+| ------ | ---------------------------------------- |
+| **M**  | Mount index (multiple `.routes()` calls) |
+| **L**  | Layout                                   |
+| **C**  | Cache boundary                           |
+| **R**  | Route                                    |
+| **P**  | Parallel slot                            |
+
+Example: `M0L0L1C0R0` = Mount 0 → Root Layout → Nested Layout → Cache → Route
+
+## Debugging Checklist
+
+1. **Routes have parents**: `parentShortCode` should NOT be `null` (except root layout)
+2. **Correct hierarchy**: ShortCode should reflect nesting (e.g., `M0L0R0` not `M0R0`)
+3. **Loaders attached**: Check `hasLoader: true` for routes with data requirements
+4. **Intercepts registered**: `interceptCount > 0` for modal/overlay patterns
+
+## Comparing Manifests
+
+```typescript
+import {
+  serializeManifest,
+  compareManifests,
+  formatManifestDiff,
+} from "@rangojs/router/__internal";
+
+const oldManifest = await router.debugManifest();
+// ... make changes ...
+const newManifest = await router.debugManifest();
+
+const diff = compareManifests(oldManifest, newManifest);
+console.log(formatManifestDiff(diff));
+```
+
+## Common Issues
+
+### Routes have `parentShortCode: null`
+
+Routes should have a layout parent. Check that `urls()` handler is being wrapped in root layout.
+
+### Missing layouts in hierarchy
+
+Verify `layout()` calls wrap child routes correctly.
+
+### Wrong mount index
+
+Multiple `.routes()` calls create separate mounts (M0, M1, etc.). Use `include()` to share context.

package/skills/document-cache/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: document-cache
+description: Cache full HTTP responses at the edge with Cache-Control headers
+argument-hint: [setup]
+---
+
+# Document Cache
+
+Caches complete HTTP responses (HTML/RSC) at the edge based on Cache-Control headers. Routes opt-in by setting `s-maxage`.
+
+## Setup
+
+Configure document cache in router:
+
+```typescript
+import { createRouter } from "@rangojs/router";
+import { CFCacheStore } from "@rangojs/router/cache";
+import { urlpatterns } from "./urls";
+
+const router = createRouter<AppBindings>({
+  document: Document,
+  urls: urlpatterns,
+  documentCache: (_env, ctx) => ({
+    store: new CFCacheStore({ ctx: ctx! }),
+    skipPaths: ["/api", "/admin"],
+    debug: process.env.NODE_ENV === "development",
+  }),
+});
+
+export default router;
+```
+
+## Route Opt-In with cache()
+
+Routes opt-in to document caching using the `cache()` DSL with `documentCache` option:
+
+```typescript
+import { urls } from "@rangojs/router";
+
+export const urlpatterns = urls(({ path, cache }) => [
+  // Cache full page for 5 min, serve stale for 1 hour
+  cache({ documentCache: { sMaxAge: 300, swr: 3600 } }, () => [
+    path("/blog", BlogIndex, { name: "blog" }),
+  ]),
+
+  // Long cache for individual posts
+  cache({ documentCache: { sMaxAge: 3600, swr: 86400 } }, () => [
+    path("/blog/:slug", BlogPost, { name: "blogPost" }),
+  ]),
+
+  // No cache for dashboard (no documentCache option)
+  path("/dashboard", Dashboard, { name: "dashboard" }),
+]);
+```
+
+## Document Cache Options
+
+```typescript
+createRouter({
+  // ...
+  documentCache: (_env, ctx) => ({
+    // Cache store (required)
+    store: new CFCacheStore({ ctx: ctx! }),
+
+    // Skip specific paths
+    skipPaths: ["/api", "/admin"],
+
+    // Custom cache key
+    keyGenerator: (url) => url.pathname,
+
+    // Conditional caching
+    isEnabled: (ctx) => !ctx.request.headers.has("x-preview"),
+
+    // Debug logging
+    debug: true,
+  }),
+});
+```
+
+## How It Works
+
+```
+Request → Check Cache
+           ↓
+    ┌──────┴──────┐
+    │             │
+  HIT           MISS
+    │             │
+    ↓             ↓
+  Fresh?      Run handler
+    │             │
+   Yes → Return   Has documentCache?
+    │             │
+   No (stale)    Yes → Cache + Return
+    │             │
+    ↓            No → Return (no cache)
+  Return stale,
+  revalidate in
+  background (SWR)
+```
+
+## Cache Status Header
+
+Response includes `x-document-cache-status`:
+
+- `HIT` - Fresh cache hit
+- `STALE` - Served stale, revalidating in background
+- `MISS` - Cache miss, response was generated fresh
+
+## Cache Key Generation
+
+Default keys differentiate:
+
+- HTML requests: `{pathname}:html`
+- RSC partials: `{pathname}:{segmentHash}:rsc`
+
+Segment hash ensures different cached responses for navigations from different source pages (with different layouts).
+
+## What Gets Cached
+
+- Full HTML responses (document requests)
+- RSC payloads (client navigation)
+- Only 200 OK responses with documentCache enabled
+
+## What's NOT Cached
+
+- Server actions (`_rsc_action`)
+- Loader requests (`_rsc_loader`)
+- Routes without `documentCache` option
+- Non-200 responses
+
+## Complete Example
+
+```typescript
+// router.tsx
+import { createRouter } from "@rangojs/router";
+import { CFCacheStore } from "@rangojs/router/cache";
+import { urlpatterns } from "./urls";
+
+const router = createRouter<AppBindings>({
+  document: Document,
+  urls: urlpatterns,
+  documentCache: (_env, ctx) => ({
+    store: new CFCacheStore({ ctx: ctx! }),
+    skipPaths: ["/api"],
+    debug: process.env.NODE_ENV === "development",
+  }),
+});
+
+export default router;
+
+// urls.tsx
+import { urls } from "@rangojs/router";
+
+export const urlpatterns = urls(({ path, layout, cache, loader }) => [
+  // Blog with document caching
+  cache({ documentCache: { sMaxAge: 300, swr: 3600 } }, () => [
+    layout(<BlogLayout />, () => [
+      path("/blog", BlogIndex, { name: "blog" }),
+      path("/blog/:slug", BlogPost, { name: "blogPost" }, () => [
+        loader(BlogPostLoader),
+      ]),
+    ]),
+  ]),
+
+  // Dashboard - no document cache (dynamic content)
+  layout(<DashboardLayout />, () => [
+    path("/dashboard", Dashboard, { name: "dashboard" }),
+  ]),
+]);
+```
+
+## Document Cache vs Segment Cache
+
+| Feature      | Document Cache             | Segment Cache         |
+| ------------ | -------------------------- | --------------------- |
+| Granularity  | Full response              | Individual segments   |
+| Opt-in       | `documentCache` in cache() | `cache({ ttl, swr })` |
+| Use case     | Static pages               | Dynamic compositions  |
+| Key includes | URL + segment hash         | Route params          |
+
+Use document cache for mostly-static pages. Use segment cache when different parts of a page have different cache requirements.