@rangojs/router 0.0.0-experimental.fb4fdc18 → 0.0.0-experimental.fce7fbd1

package/skills/caching/SKILL.md

@@ -8,6 +8,46 @@ argument-hint: [setup]
 
 @rangojs/router supports segment-level caching with stale-while-revalidate (SWR) for optimal performance.
 
+> SWR support is store-specific. `CFCacheStore` revalidates segment, response,
+> and `"use cache"` entries in the background. `MemorySegmentCacheStore`
+> supports SWR for response and `"use cache"` item entries, but its
+> route-segment entries expire at TTL with no background revalidation — use
+> `CFCacheStore` for real segment SWR. See `/cache-guide`.
+
+## cache() is Partial Prerendering (PPR)
+
+`cache()` caches **everything except loaders**. On a cache hit, the cached
+segments (layouts, route components, parallels — including any resolved
+Suspense) are served from the store, and **loaders re-run fresh on every
+request**, streaming their results into the same response. Loaders are the
+dynamic "holes" of an otherwise-cached tree.
+
+This means a `cache()` boundary at the document root **is** whole-document
+Partial Prerendering: the static shell is cached and served instantly while
+per-request/per-user data stays live — in one streamed response, no extra round
+trip. The browser cannot tell the shell came from cache.
+
+```typescript
+cache({ ttl: 60, swr: 300 }, () => [
+  layout(<RootLayout />), // cached shell
+  path("/dashboard", Dashboard, { name: "dashboard" }, () => [
+    loader(StatsLoader), // DYNAMIC HOLE — re-runs every request
+  ]),
+]);
+```
+
+The consumer rule: **want it cached? render it inline. want it dynamic? put it
+in a loader and read it with `useLoader()` in a client component.** Anything
+read with `cookies()`, `headers()`, or a non-cacheable variable belongs in a
+loader (loaders always run fresh). Reading it directly in a cached handler
+throws; awaiting it with `ctx.use()` and rendering the result in a cached
+handler silently bakes per-request data into the shared shell (see "Cache purity
+& tainted objects" below).
+
+Pre-rendering (`/prerender`) is the build-time twin: it caches the same shell at
+build time instead of on first request. Both feed the segment system
+identically, and loaders always run fresh at request time.
+
 ## Route-Level Caching with cache()
 
 Use the `cache()` DSL function to cache routes:
@@ -116,7 +156,6 @@ import { MemorySegmentCacheStore } from "@rangojs/router/cache";
 
 const store = new MemorySegmentCacheStore({
   defaults: { ttl: 60, swr: 300 },
-  maxSize: 1000, // Max entries
 });
 ```
 
@@ -173,13 +212,82 @@ const router = createRouter<AppBindings>({
 KV entries require `expirationTtl >= 60s`. Short-lived entries (< 60s total TTL)
 are only cached in L1.
 
-## Context Variables Inside Cache Boundaries
+## Cache purity & tainted objects
+
+A `cache()` boundary caches everything except loaders, so anything read inside a
+cached handler is **frozen into the shared cache entry** and served to every
+subsequent visitor. To stop one user's request-scoped data from leaking to
+another, request-scoped APIs are guarded inside a cache scope:
+
+| Inside a `cache()` boundary                                     | Behavior                                            |
+| --------------------------------------------------------------- | --------------------------------------------------- |
+| `cookies()` / `headers()` (read or write)                       | **throws** — request-scoped, would poison the entry |
+| `ctx.header()` / `setCookie()` / `setStatus()` / `onResponse()` | **throws** — response side effects lost on a hit    |
+| `ctx.get(var)` where the var is `{ cache: false }`              | **throws** on read                                  |
+| `ctx.set(var, value)` for a cacheable var                       | allowed (children are cached too)                   |
+| Any of the above **inside a loader**                            | **allowed** — loaders always run fresh              |
+
+**Tainted objects.** Request-scoped objects (`ctx`, `env`, `request`) carry an
+internal taint symbol so they are excluded from `"use cache"` cache keys, and
+the cache scope is tracked via async-local state. Two flags back the guards:
+`INSIDE_CACHE_EXEC` (set while a `"use cache"` function runs) and the `cache()`
+DSL scope (`isInsideCacheScope()`). `isInsideCacheScope()` deliberately returns
+`false` inside loaders — which is exactly why loaders are the dynamic holes:
+they may read `cookies()`/`headers()` and re-run on every request.
+
+The fix for "I need request data in a cached route": register a `loader()` and
+**consume it with `useLoader()` in a client component**. The loader is the
+dynamic hole — its data rides the fresh (never-cached) loader segment and is
+rendered in the client component, so it never lands in the cached shell.
+
+This is NOT the same as awaiting the loader in the handler. A cached handler
+that does `await ctx.use(Loader)` and renders the result bakes that per-request
+data straight into the shared cached segment — the loader running "fresh" does
+not help, because its output was inlined into the cached parent, and `ctx.use()`
+is **not** guarded. `ctx.use()` is a server-side escape hatch for non-rendered
+uses (set a ctx var, make a routing decision); never render its result inside a
+cached handler.
+
+```typescript
+// WRONG — throws: cookies() read directly in a cached handler
+cache({ ttl: 60 }, () => [
+  path("/me", () => <Profile id={cookies().get("uid")?.value} />),
+]);
+
+// ALSO WRONG (unguarded, but leaks) — the awaited loader data is rendered into
+// the cached handler, so the user's data is frozen into the shared shell.
+cache({ ttl: 60 }, () => [
+  path(
+    "/me",
+    async (ctx) => {
+      const { user } = await ctx.use(MeLoader); // runs fresh…
+      return <Profile user={user} />; // …but inlined into the CACHED segment → leak
+    },
+    { name: "me" },
+    () => [loader(MeLoader)],
+  ),
+]);
+
+// RIGHT — consume the loader in a CLIENT component via useLoader(). The cached
+// route segment holds only the <Profile/> reference; the user data rides the
+// fresh loader segment and renders client-side.
+
+// profile.tsx (client component)
+"use client";
+import { useLoader } from "@rangojs/router/client";
+
+export function Profile() {
+  const { user } = useLoader(MeLoader); // fresh per request; never cached
+  return <span>{user.name}</span>;
+}
+
+// urls — register the loader; MeLoader reads cookies() inside the loader (allowed)
+cache({ ttl: 60 }, () => [
+  path("/me", () => <Profile />, { name: "me" }, () => [loader(MeLoader)]),
+]);
+```
 
-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.
+See `/cache-guide` for the full decision guide and the `cache()` vs `"use cache"` comparison.
 
 ## Nested Cache Boundaries
 
@@ -245,7 +353,7 @@ export const urlpatterns = urls(({ path, layout, cache, loader, revalidate }) =>
     path("/shop/product/:slug", ProductPage, { name: "product" }, () => [
       loader(ProductLoader, () => [cache({ ttl: 120 })]),
       loader(CartLoader, () => [
-        revalidate(({ actionId }) => actionId?.includes("Cart") ?? false),
+        revalidate(({ actionId }) => actionId?.includes("Cart") || undefined),
       ]),
     ]),
   ]),

package/skills/composability/SKILL.md

@@ -55,7 +55,9 @@ import { cache, revalidate, loading, errorBoundary, middleware } from "@rangojs/
 // Shared caching configuration
 const withCaching = () => [
   cache({ ttl: 600_000 }),
-  revalidate(({ actionId }) => !!actionId),
+  // 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
@@ -71,6 +73,29 @@ const withAuth = () => [
 ];
 ```
 
+> **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):
@@ -107,7 +132,7 @@ import { authMiddleware } from "./middleware/auth";
 
 export const withPublicDefaults = () => [
   cache({ ttl: 300 }),
-  revalidate(({ actionId }) => !!actionId),
+  revalidate(({ actionId }) => (actionId ? true : undefined)),
 ];
 
 export const withProtectedDefaults = () => [

package/skills/document-cache/SKILL.md

@@ -10,73 +10,82 @@ Caches complete HTTP responses (HTML/RSC) at the edge based on Cache-Control hea
 
 ## Setup
 
-Configure document cache in 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 { createRouter } from "@rangojs/router";
-import { CFCacheStore } from "@rangojs/router/cache";
+import {
+  createDocumentCacheMiddleware,
+  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! }),
+  // 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",
   }),
-});
+);
 
 export default router;
 ```
 
-## Route Opt-In with cache()
+## Route Opt-In with Cache-Control
 
-Routes opt-in to document caching using the `cache()` DSL with `documentCache` option:
+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
-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" }),
-]);
+// 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.
 ```
 
 ## Document Cache Options
 
-```typescript
-createRouter({
-  // ...
-  documentCache: (_env, ctx) => ({
-    // Cache store (required)
-    store: new CFCacheStore({ ctx: ctx! }),
+`createDocumentCacheMiddleware(options?)` accepts:
 
-    // Skip specific paths
-    skipPaths: ["/api", "/admin"],
+```typescript
+createDocumentCacheMiddleware({
+  // Skip specific paths (matched by pathname prefix)
+  skipPaths: ["/api", "/admin"],
 
-    // Custom cache key
-    keyGenerator: (url) => url.pathname,
+  // Custom cache key generator
+  keyGenerator: (url) => url.pathname,
 
-    // Conditional caching
-    isEnabled: (ctx) => !ctx.request.headers.has("x-preview"),
+  // Conditional caching, evaluated per request
+  isEnabled: (ctx) => !ctx.request.headers.has("x-preview"),
 
-    // Debug logging
-    debug: true,
-  }),
+  // 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
 
 ```
@@ -89,7 +98,7 @@ Request → Check Cache
     ↓             ↓
   Fresh?      Run handler
     │             │
-   Yes → Return   Has documentCache?
+   Yes → Return   Has s-maxage?
     │             │
    No (stale)    Yes → Cache + Return
     │             │
@@ -120,13 +129,14 @@ 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 documentCache enabled
+- Only 200 OK responses whose `Cache-Control` includes `s-maxage`
 
 ## What's NOT Cached
 
 - Server actions (`_rsc_action`)
 - Loader requests (`_rsc_loader`)
-- Routes without `documentCache` option
+- Non-GET requests
+- Responses without an `s-maxage` `Cache-Control` directive
 - Non-200 responses
 
 ## Complete Example
@@ -134,40 +144,53 @@ 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";
+import { createDocumentCacheMiddleware, 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! }),
+  cache: (_env, ctx) => new CFCacheStore({ ctx: ctx! }),
+});
+
+router.use(
+  createDocumentCacheMiddleware({
     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),
-      ]),
+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 - no document cache (dynamic content)
+  // 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 <BlogIndexPage />;
+}
+
+function BlogPost(ctx) {
+  ctx.headers.set("Cache-Control", "s-maxage=300, stale-while-revalidate=3600");
+  return <BlogPostPage />;
+}
 ```
 
 ## Document Cache vs Segment Cache
@@ -175,7 +198,7 @@ export const urlpatterns = urls(({ path, layout, cache, loader }) => [
 | Feature      | Document Cache             | Segment Cache         |
 | ------------ | -------------------------- | --------------------- |
 | Granularity  | Full response              | Individual segments   |
-| Opt-in       | `documentCache` in cache() | `cache({ ttl, swr })` |
+| Opt-in       | `Cache-Control` `s-maxage` | `cache({ ttl, swr })` |
 | Use case     | Static pages               | Dynamic compositions  |
 | Key includes | URL + segment hash         | Route params          |
 

package/skills/handler-use/SKILL.md

@@ -59,6 +59,8 @@ Now `ProductPage` carries its loader, loading state, and response-header middlew
 | `intercept()`                                     | `middleware`, `revalidate`, `loader`, `loading`, `errorBoundary`, `notFoundBoundary`, `layout`, `route`, `when`, `transition`                  |
 | Response routes (`path.json()`, `path.text()`, …) | `middleware`, `cache`                                                                                                                          |
 
+For per-item semantics see the dedicated skills: [middleware](../middleware/SKILL.md), [loader](../loader/SKILL.md), [parallel](../parallel/SKILL.md), [intercept](../intercept/SKILL.md), [layout](../layout/SKILL.md), [view-transitions](../view-transitions/SKILL.md).
+
 If `handler.use()` returns a disallowed item for a mount site, registration throws:
 
 ```
@@ -295,7 +297,7 @@ QuickViewModal.use = () => [
 
 ## `loading()` is a single-assignment item — scope it correctly
 
-Most `use` items accumulate when merged: `handler.use` `middleware()` runs _and_ explicit `middleware()` runs; both `loader()` registrations apply. `loading()` is different — it mutates `entry.loading` directly, last call wins ([dsl-helpers.ts `loadingFn`](../../src/route-definition/dsl-helpers.ts)).
+Most `use` items accumulate when merged: `handler.use` `middleware()` runs _and_ explicit `middleware()` runs; both `loader()` registrations apply. `loading()` is different — it mutates `entry.loading` directly, last call wins ([dsl-helpers.ts `loading`](../../src/route-definition/dsl-helpers.ts)).
 
 For pages, layouts, and intercepts that's straightforward: explicit `loading()` at the mount site replaces any `loading()` from `handler.use`. The merge order is `handler.use → explicit`, so the explicit one is the last writer and wins.