@rangojs/router 0.0.0-experimental.2 → 0.0.0-experimental.204030a9

package/skills/composability/SKILL.md

@@ -0,0 +1,197 @@
+---
+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 }),
+  // Defer on navigation (|| undefined) so each route keeps its own param/search
+  // revalidation default; only force a re-run when an action ran.
+  revalidate(({ actionId }) => (actionId ? true : undefined)),
+];
+
+// 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),
+];
+```
+
+> **Factories compose logic, not just values.** A `revalidate()` predicate in a
+> shared factory applies its logic to _every_ route that composes it, so a
+> footgun here is amplified across the app. Two rules:
+>
+> 1. Use `|| undefined` (defer), not `?? false` (hard short-circuit), in shared
+>    predicates — a hard `false` ends the chain and overrides each consuming
+>    route's own default, and a downstream revalidator never runs. See `/loader`
+>    → "`|| undefined` (defer) vs `?? false` (hard)".
+> 2. Match actions with `ctx.isAction(Action)`, not an inline
+>    `actionId.includes("…")` buried in a factory: it resolves the action from an
+>    imported reference, so a rename is a compile error in one place instead of
+>    silent drift across every consumer.
+>
+> Remember the axis: a factory's `revalidate()` controls client-update
+> selection, while its `cache()` controls stored-value freshness. They are
+> independent even when bundled in the same factory (`/cache-guide` → "Two axes").
+
+> **Keep factories small and intention-named.** The anti-pattern that kills
+> readability is over-bundling — a `withDefaults()` that secretly adds five
+> things — and factory-of-factories nesting (leaning on `.flat(3)`). Surprising
+> config stays inline; extract only the boring, repeated parts; compose by
+> _naming concerns_ (`withAuth()`, `withCaching()`), not by hiding them.
+
+## 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 ? true : undefined)),
+];
+
+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

@@ -10,51 +10,82 @@ Caches complete HTTP responses (HTML/RSC) at the edge based on Cache-Control hea
 
 ## Setup
 
-Add middleware to router:
+Document caching is a middleware. Add `createDocumentCacheMiddleware()` to the
+router with `.use()`. The cache store it reads from is the app-level store you
+configure on `createRouter({ cache })` (available on the request context as
+`requestCtx._cacheStore`), not a store passed to the middleware.
 
 ```typescript
-import { createRSCRouter, createDocumentCacheMiddleware } from "@rangojs/router/server";
-import { CFCacheStore } from "@rangojs/router/cache/cf";
-
-const router = createRSCRouter<AppEnv>({
+import { createRouter } from "@rangojs/router";
+import {
+  createDocumentCacheMiddleware,
+  CFCacheStore,
+} from "@rangojs/router/cache";
+import { urlpatterns } from "./urls";
+
+const router = createRouter<AppBindings>({
   document: Document,
-  cache: (env) => ({
-    store: new CFCacheStore({ ctx: env.ctx }),
+  urls: urlpatterns,
+  // App-level cache store. The document cache middleware uses this store's
+  // getResponse/putResponse methods.
+  cache: (_env, ctx) => new CFCacheStore({ ctx: ctx! }),
+});
+
+router.use(
+  createDocumentCacheMiddleware({
+    skipPaths: ["/api", "/admin"],
+    debug: process.env.NODE_ENV === "development",
   }),
-})
-  .use(createDocumentCacheMiddleware())
-  .routes(routes);
+);
+
+export default router;
 ```
 
-## Route Opt-In
+## Route Opt-In with Cache-Control
 
-Routes opt-in by setting `Cache-Control` with `s-maxage`:
+Routes opt-in to document caching by setting a `Cache-Control` response header
+with `s-maxage`. The middleware caches responses whose `Cache-Control` includes
+`s-maxage`; `stale-while-revalidate` enables background revalidation (SWR).
 
 ```typescript
-route("home", (ctx) => {
-  ctx.headers.set("Cache-Control", "s-maxage=60, stale-while-revalidate=300");
-  return <HomePage />;
-});
+// Cache full page for 5 min, serve stale for 1 hour
+function BlogIndexHandler(ctx) {
+  ctx.headers.set("Cache-Control", "s-maxage=300, stale-while-revalidate=3600");
+  return <BlogIndex />;
+}
+
+// Long cache for individual posts
+function BlogPostHandler(ctx) {
+  ctx.headers.set("Cache-Control", "s-maxage=3600, stale-while-revalidate=86400");
+  return <BlogPost />;
+}
+
+// Dashboard sets no Cache-Control header, so it is never document-cached.
 ```
 
-## Middleware Options
+## Document Cache Options
+
+`createDocumentCacheMiddleware(options?)` accepts:
 
 ```typescript
 createDocumentCacheMiddleware({
-  // Skip specific paths
+  // Skip specific paths (matched by pathname prefix)
   skipPaths: ["/api", "/admin"],
 
-  // Custom cache key
+  // Custom cache key generator
   keyGenerator: (url) => url.pathname,
 
-  // Conditional caching
+  // Conditional caching, evaluated per request
   isEnabled: (ctx) => !ctx.request.headers.has("x-preview"),
 
-  // Debug logging
+  // Debug logging (HIT, MISS, STALE, REVALIDATED)
   debug: true,
 });
 ```
 
+The cache store is not a middleware option — it comes from the app-level
+`createRouter({ cache })` store.
+
 ## How It Works
 
 ```
@@ -80,6 +111,7 @@ Request → Check Cache
 ## 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
@@ -87,6 +119,7 @@ Response includes `x-document-cache-status`:
 ## Cache Key Generation
 
 Default keys differentiate:
+
 - HTML requests: `{pathname}:html`
 - RSC partials: `{pathname}:{segmentHash}:rsc`
 
@@ -96,57 +129,77 @@ Segment hash ensures different cached responses for navigations from different s
 
 - Full HTML responses (document requests)
 - RSC payloads (client navigation)
-- Only 200 OK responses with `s-maxage`
+- Only 200 OK responses whose `Cache-Control` includes `s-maxage`
 
 ## What's NOT Cached
 
 - Server actions (`_rsc_action`)
 - Loader requests (`_rsc_loader`)
-- Responses without `s-maxage`
+- Non-GET requests
+- Responses without an `s-maxage` `Cache-Control` directive
 - Non-200 responses
 
 ## Complete Example
 
 ```typescript
 // router.tsx
-const router = createRSCRouter<AppEnv>({
+import { createRouter } from "@rangojs/router";
+import { createDocumentCacheMiddleware, CFCacheStore } from "@rangojs/router/cache";
+import { urlpatterns } from "./urls";
+
+const router = createRouter<AppBindings>({
   document: Document,
-  cache: (env) => ({
-    store: new CFCacheStore({ ctx: env.ctx }),
-  }),
-})
-  .use(createDocumentCacheMiddleware({
+  urls: urlpatterns,
+  cache: (_env, ctx) => new CFCacheStore({ ctx: ctx! }),
+});
+
+router.use(
+  createDocumentCacheMiddleware({
     skipPaths: ["/api"],
     debug: process.env.NODE_ENV === "development",
-  }))
-  .routes(routes);
-
-// handlers.tsx
-route("blog", (ctx) => {
-  // Cache for 5 min, serve stale for 1 hour while revalidating
+  }),
+);
+
+export default router;
+
+// urls.tsx
+import { urls } from "@rangojs/router";
+
+export const urlpatterns = urls(({ path, layout, loader }) => [
+  // Blog pages opt into document caching via Cache-Control headers set in
+  // their handlers (see BlogIndex / BlogPost below).
+  layout(<BlogLayout />, () => [
+    path("/blog", BlogIndex, { name: "blog" }),
+    path("/blog/:slug", BlogPost, { name: "blogPost" }, () => [
+      loader(BlogPostLoader),
+    ]),
+  ]),
+
+  // Dashboard sets no Cache-Control header, so it is never document-cached.
+  layout(<DashboardLayout />, () => [
+    path("/dashboard", Dashboard, { name: "dashboard" }),
+  ]),
+]);
+
+// Blog handlers set s-maxage to opt into the document cache.
+function BlogIndex(ctx) {
   ctx.headers.set("Cache-Control", "s-maxage=300, stale-while-revalidate=3600");
-  return <BlogIndex />;
-});
+  return <BlogIndexPage />;
+}
 
-route("blog.post", (ctx) => {
-  // Long cache for individual posts
-  ctx.headers.set("Cache-Control", "s-maxage=3600, stale-while-revalidate=86400");
-  return <BlogPost slug={ctx.params.slug} />;
-});
-
-route("dashboard", (ctx) => {
-  // No cache header = not cached
-  return <Dashboard />;
-});
+function BlogPost(ctx) {
+  ctx.headers.set("Cache-Control", "s-maxage=300, stale-while-revalidate=3600");
+  return <BlogPostPage />;
+}
 ```
 
 ## Document Cache vs Segment Cache
 
-| Feature | Document Cache | Segment Cache |
-|---------|---------------|---------------|
-| Granularity | Full response | Individual segments |
-| Opt-in | `s-maxage` header | `cache()` DSL |
-| Use case | Static pages | Dynamic compositions |
-| Key includes | URL + segment hash | Route params |
+| Feature      | Document Cache             | Segment Cache         |
+| ------------ | -------------------------- | --------------------- |
+| Granularity  | Full response              | Individual segments   |
+| Opt-in       | `Cache-Control` `s-maxage` | `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.