@rangojs/router 0.0.0-experimental.2 → 0.0.0-experimental.20dbba0c

package/skills/caching/SKILL.md

@@ -1,319 +1,261 @@
 ---
 name: caching
-description: Configure segment caching with memory or Cloudflare KV stores in rsc-router
+description: Configure segment caching with memory or Cloudflare KV stores in @rangojs/router
 argument-hint: [setup]
 ---
 
 # Caching
 
-rsc-router supports segment-level caching with stale-while-revalidate (SWR) for optimal performance.
+@rangojs/router supports segment-level caching with stale-while-revalidate (SWR) for optimal performance.
 
-## Router Cache Configuration
+## Route-Level Caching with cache()
 
-Configure caching in `createRSCRouter`:
+Use the `cache()` DSL function to cache routes:
 
 ```typescript
-import { createRSCRouter } from "rsc-router/server";
-import { MemorySegmentCacheStore } from "rsc-router/cache";
+import { urls } from "@rangojs/router";
 
-const store = new MemorySegmentCacheStore({
-  defaults: { ttl: 60, swr: 300 }
-});
+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" }),
+  ]),
 
-const router = createRSCRouter<AppEnv>({
-  document: Document,
-  cache: {
-    store,
-    enabled: true,
-  },
-});
+  // Uncached routes
+  path("/account", AccountPage, { name: "account" }),
+]);
 ```
 
-### Dynamic Cache Configuration
-
-Use a factory function for environment-based config:
+## Cache Options
 
 ```typescript
-const router = createRSCRouter<AppEnv>({
-  document: Document,
-  cache: (env) => ({
-    store: new CFCacheStore({
-      baseUrl: env.Bindings.CACHE_URL,
-      waitUntil: (fn) => env.ctx.waitUntil(fn),
-    }),
-    enabled: env.Bindings.CACHE_ENABLED === "true",
-  }),
-});
+cache(
+  {
+    ttl: 60, // Time-to-live in seconds (default: 60)
+    swr: 300, // Stale-while-revalidate window (default: 300)
+  },
+  () => [
+    // Cached routes
+  ],
+);
 ```
 
-## Cache Stores
+## Named Profile Shorthand
 
-### Memory Store (Development)
+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
-import { MemorySegmentCacheStore } from "rsc-router/cache";
-
-const store = new MemorySegmentCacheStore({
-  defaults: { ttl: 60, swr: 300 }
+// Define profiles in router
+createRouter({
+  cacheProfiles: {
+    default: { ttl: 900, swr: 1800 },
+    short: { ttl: 60, swr: 120 },
+    long: { ttl: 3600, swr: 7200 },
+  },
 });
 
-// Debug cache stats
-console.log(store.getStats());
+// 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" }),
+]);
 ```
 
-Features:
-- Survives HMR in development
-- No true SWR (entries expire at TTL)
-- Good for development and single-instance deployments
+These profile names are shared with the `"use cache: <name>"` directive. See
+`/use-cache` for function-level caching.
 
-### Cloudflare Cache Store (Production)
+## Loader-Level Caching
+
+Cache individual loaders:
 
 ```typescript
-import { CFCacheStore } from "rsc-router/cache/cf";
-
-const store = new CFCacheStore({
-  namespace: "rsc-cache",              // Optional, uses caches.default
-  baseUrl: "https://cache.example.com/",
-  defaults: { ttl: 3600, swr: 7200 },
-  waitUntil: (fn) => ctx.waitUntil(fn),
-  version: "1.0.0",                    // For cache invalidation on deploy
-});
+path("/product/:slug", ProductPage, { name: "product" }, () => [
+  // Cache this loader's results
+  loader(ProductLoader, () => [cache({ ttl: 300 })]),
+
+  // This loader is not cached
+  loader(CartLoader),
+]);
 ```
 
-Features:
-- Cloudflare Cache API integration
-- True SWR with atomic revalidation (prevents thundering herd)
-- Non-blocking writes via `waitUntil`
-- Version-based cache invalidation
+## Global Cache Configuration
 
-## Cache Options
+Configure a cache store in the router:
 
 ```typescript
-interface CacheOptions {
-  // Time-to-live in seconds
-  ttl: number;
-
-  // Stale-while-revalidate window (seconds after TTL)
-  swr?: number;
+import { createRouter } from "@rangojs/router";
+import { MemorySegmentCacheStore } from "@rangojs/router/cache";
 
-  // Override cache store for this boundary
-  store?: SegmentCacheStore;
-
-  // Conditional caching
-  condition?: (ctx) => boolean;
-
-  // Custom cache key
-  key?: (ctx) => string | Promise<string>;
+const store = new MemorySegmentCacheStore({
+  defaults: { ttl: 60, swr: 300 },
+});
 
-  // Tags for invalidation
-  tags?: string[] | ((ctx) => string[]);
-}
+const router = createRouter({
+  document: Document,
+  urls: urlpatterns,
+  cache: {
+    store,
+    enabled: true,
+  },
+});
 ```
 
-## Route-Level Caching
+## Cache Stores
 
-Use `cache()` in handlers to set cache boundaries:
+### Memory Store
 
-```typescript
-import { map } from "rsc-router/server";
-
-export default map<typeof routes>(({ route, layout, cache }) => [
-  // Cache entire layout and children
-  cache({ ttl: 3600, swr: 7200 }, () => [
-    layout(<StaticLayout />, () => [
-      route("about", AboutPage),
-      route("contact", ContactPage),
-    ]),
-  ]),
+For single-instance deployments:
 
-  // Different cache settings per route
-  cache({ ttl: 60 }, () => [
-    route("dashboard", DashboardPage),
-  ]),
+```typescript
+import { MemorySegmentCacheStore } from "@rangojs/router/cache";
 
-  // No caching (default)
-  route("checkout", CheckoutPage),
-]);
+const store = new MemorySegmentCacheStore({
+  defaults: { ttl: 60, swr: 300 },
+  maxSize: 1000, // Max entries
+});
 ```
 
-## Conditional Caching
+### Cloudflare Edge Cache Store
 
-Skip cache based on request context:
+For distributed caching on Cloudflare Workers using the Cache API:
 
 ```typescript
-cache({
-  ttl: 3600,
-  condition: (ctx) => {
-    // Don't cache for authenticated users
-    const hasAuth = ctx.request.headers.has("Authorization");
-    return !hasAuth;
-  },
-}, () => [
-  route("products", ProductList),
-])
+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,
+  }),
+});
 ```
 
-## Custom Cache Keys
+### With KV L2 Persistence
 
-Override the default cache key:
+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
-cache({
-  ttl: 3600,
-  key: (ctx) => {
-    // Include user segment in cache key
-    const segment = ctx.request.headers.get("x-user-segment") || "default";
-    return `${segment}:products:${ctx.params.category}`;
-  },
-}, () => [
-  route("products.category", CategoryPage),
-])
-```
-
-Store-level key modification:
+import { CFCacheStore } from "@rangojs/router/cache";
 
-```typescript
-const store = new CFCacheStore({
-  keyGenerator: (ctx, defaultKey) => {
-    const region = ctx.request.cf?.colo || "unknown";
-    return `${region}:${defaultKey}`;
-  },
+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,
+  }),
 });
 ```
 
-## Stale-While-Revalidate (SWR)
-
-SWR serves stale content while fetching fresh data in the background:
+**How the two layers work:**
 
-```
-Timeline:
-├─ 0 to TTL ─────────┤ Fresh content served
-├─ TTL to TTL+SWR ───┤ Stale content served, revalidation in background
-├─ After TTL+SWR ────┤ Cache expired, new fetch required
-```
+| 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 |
 
-```typescript
-cache({
-  ttl: 60,      // Fresh for 60 seconds
-  swr: 300,     // Stale-but-usable for 5 more minutes
-}, () => [
-  route("feed", FeedPage),
-])
-```
+KV entries require `expirationTtl >= 60s`. Short-lived entries (< 60s total TTL)
+are only cached in L1.
 
-## Multi-Store Setup
+## Context Variables Inside Cache Boundaries
 
-Use different stores for different data patterns:
+Context variables (`createVar`) are cacheable by default and can be read and
+written inside `cache()` scopes. Variables marked with `{ cache: false }` (at
+the var level or write level) throw when read inside a cache scope. Response
+side effects (`ctx.header()`, `ctx.cookie()`) always throw inside cache
+boundaries. See `/cache-guide` for the full cache safety table.
 
-```typescript
-const hotStore = new MemorySegmentCacheStore({
-  defaults: { ttl: 10 }
-});
+## Nested Cache Boundaries
 
-const coldStore = new CFCacheStore({
-  defaults: { ttl: 3600, swr: 7200 }
-});
+Override cache settings for specific sections:
 
-export default map<typeof routes>(({ route, cache }) => [
-  // Frequently changing data - short TTL, memory
-  cache({ store: hotStore, ttl: 10 }, () => [
-    route("dashboard", DashboardPage),
-    route("notifications", NotificationsPage),
-  ]),
+```typescript
+// Global cache
+cache({ ttl: 300 }, () => [
+  path("/blog", BlogIndex, { name: "blog" }),
 
-  // Rarely changing data - long TTL, edge cache
-  cache({ store: coldStore, ttl: 3600 }, () => [
-    route("archive", ArchivePage),
-    route("docs", DocsPage),
+  // Override: shorter TTL for dynamic content
+  cache({ ttl: 30 }, () => [
+    path("/blog/:slug", BlogPost, { name: "blogPost" }),
   ]),
 ]);
 ```
 
-## Cache Invalidation
+## Custom Cache Store
 
-### Version-Based (Cloudflare)
+Create a dedicated store for specific routes:
 
 ```typescript
-import packageJson from "./package.json";
-
-const store = new CFCacheStore({
-  version: packageJson.version,  // All cache invalidated on deploy
+const checkoutCache = new MemorySegmentCacheStore({
+  defaults: { ttl: 10 },
 });
-```
-
-### Tag-Based (Future)
 
-```typescript
-cache({
-  tags: (ctx) => [`product:${ctx.params.id}`, "products"],
-}, () => [
-  route("products.detail", ProductDetail),
-])
-
-// Invalidate by tag
-await store.invalidateTag("products");
+// In urls
+cache({ store: checkoutCache }, () => [
+  path("/checkout", CheckoutPage, { name: "checkout" }),
+]);
 ```
 
-## Complete Production Example
+## Complete Example
 
 ```typescript
-// router.tsx
-import { createRSCRouter } from "rsc-router/server";
-import { CFCacheStore } from "rsc-router/cache/cf";
-import packageJson from "./package.json";
+import { urls } from "@rangojs/router";
+import { MemorySegmentCacheStore } from "@rangojs/router/cache";
 
-const router = createRSCRouter<AppEnv>({
-  document: Document,
-  cache: (env) => ({
-    store: new CFCacheStore({
-      baseUrl: "https://rsc-cache.internal/",
-      defaults: { ttl: 300, swr: 3600 },
-      waitUntil: (fn) => env.ctx.waitUntil(fn),
-      version: packageJson.version,
-    }),
-    enabled: env.Bindings.NODE_ENV === "production",
-  }),
+// Custom store for checkout (short TTL)
+const checkoutCache = new MemorySegmentCacheStore({
+  defaults: { ttl: 10 },
 });
 
-// handlers/shop.tsx
-export default map<typeof shopRoutes>(({ route, layout, cache }) => [
-  // Static pages - aggressive caching
-  cache({ ttl: 86400, swr: 604800 }, () => [
-    route("shop.about", AboutPage),
-    route("shop.terms", TermsPage),
+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
+      ]),
+    ]),
   ]),
 
-  // Product listing - moderate caching
-  cache({ ttl: 300, swr: 3600 }, () => [
-    route("shop.products", ProductList),
+  // 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),
+      ]),
+    ]),
   ]),
 
-  // Product detail - cache with product-specific key
-  cache({
-    ttl: 600,
-    swr: 3600,
-    key: (ctx) => `product:${ctx.params.slug}`,
-  }, () => [
-    route("shop.product", ProductDetail),
+  // Checkout with custom cache store
+  cache({ store: checkoutCache }, () => [
+    path("/checkout", CheckoutPage, { name: "checkout" }),
   ]),
 
-  // User-specific pages - no caching
-  route("shop.cart", CartPage),
-  route("shop.checkout", CheckoutPage),
+  // No cache for account pages
+  path("/account", AccountPage, { name: "account" }),
 ]);
 ```
-
-## Cache Headers (Cloudflare)
-
-CFCacheStore sets these headers for debugging:
-
-- `x-edge-cache-status`: `HIT` or `REVALIDATING`
-- `x-edge-cache-stale-at`: Timestamp when entry becomes stale
-
-## What Gets Cached
-
-- Route segments (components, layouts, loading states)
-- Handle data (breadcrumbs, metadata)
-- **Not cached by default**: Loader data (fetched fresh each request)
-
-To cache loader results, use loader-level caching or external caching strategies.

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