@rangojs/router 0.0.0-experimental.f2d1a2f1 → 0.0.0-experimental.f4a8e8de

package/skills/deployment-caching/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: deployment-caching
+description: "Choose the deployment cache boundary for a Rango app: in-function segment/prerender/PPR caches, store-backed whole-response caching, or an external CDN cache. Use when comparing Cloudflare, Vercel, and Node deployments; deciding whether Cache-Control can reduce origin work; or reasoning about middleware, live loaders, PPR, and CDN behavior."
+argument-hint: [cloudflare|vercel|node]
+---
+
+# Deployment caching boundaries
+
+Start with one question: **does the request reach Rango before shared bytes are
+served?** That boundary decides whether middleware runs, whether loaders stay
+live, and which invalidation system owns the result.
+
+## The execution matrix
+
+| Mechanism                         | Stored artifact                                 | Function/worker runs on a hit? |                                   Rango middleware on a hit? | What stays live?                     |
+| --------------------------------- | ----------------------------------------------- | -----------------------------: | -----------------------------------------------------------: | ------------------------------------ |
+| `"use cache"`                     | one function result                             |                            yes |                                                          yes | caller, handlers, loaders, rendering |
+| `cache()`                         | serialized Flight segments                      |                            yes |                                                          yes | middleware, loaders, HTML rendering  |
+| `Prerender()`                     | build-time Flight segments in the server bundle |                            yes |                                                          yes | middleware, loaders, HTML rendering  |
+| `ppr`                             | HTML prelude + React postponed state            |                            yes |                                 **yes, before shell commit** | middleware, holes, hydration payload |
+| `createDocumentCacheMiddleware()` | complete response in the app cache store        |                            yes | outer middleware runs; the hit skips its downstream pipeline | nothing downstream                   |
+| HTTP CDN cache (`s-maxage`)       | complete HTTP response outside the app          |                         **no** |                                                       **no** | nothing                              |
+
+The first five rows enter the app. The first four preserve the complete request
+model; a document-cache middleware hit intentionally short-circuits its
+downstream pipeline. The last row is a platform cache: on a hit it serves bytes
+without invoking Rango at all.
+
+## Rango PPR is in-function PPR
+
+Rango's `ppr` path option does not make the HTML shell a public static asset.
+The worker or function handles every document request:
+
+```text
+request
+  -> global middleware
+  -> route middleware
+  -> shell lookup
+  -> flush stored prelude
+  -> run live loaders + Flight + React resume
+```
+
+That ordering is the security contract. A redirect, 401, tenant decision,
+`ctx.dynamic()`, cookie, or response header from middleware wins before a shell
+byte is committed.
+
+There are two shell producers:
+
+- An ordinary `ppr` route captures after a runtime MISS.
+- A route that combines `Prerender()` with the `ppr` path option captures during
+  `vite build`, so its first production request can already be a shell HIT.
+
+Both producers feed the same in-function serve path. Build-time shells are
+content-hashed modules in the server bundle, not CDN-served HTML files.
+
+`ppr.ttl`, `ppr.swr`, and `ppr.tags` govern that shell entry. They do **not**
+emit HTTP `Cache-Control` and do not configure a platform CDN.
+
+## Platform deployment shapes
+
+### Cloudflare
+
+The Cloudflare preset runs the RSC app in a Worker. The request reaches the
+Worker at the edge, middleware runs there, and PPR shell lookup/resume stays in
+that Worker. `CFCacheStore` supplies the app cache families; client assets are
+served separately as assets.
+
+### Vercel
+
+The Vercel preset emits static client assets plus one streaming Node Function.
+HTML, Flight, prerender payloads, and PPR shells are served from that function.
+`VercelCacheStore` uses Runtime Cache inside the function; Runtime Cache is not
+Vercel's CDN/ISR cache.
+
+The preset deliberately emits no Vercel `.prerender-config.json`, response
+`chain`, or CDN-stitched resume function. Vercel's open-source Build Output
+parser accepts a generic `chain`, but the production CDN stitching protocol is
+not a documented third-party Build Output contract. More importantly, a CDN
+that emits the shell before invoking Rango cannot preserve the middleware
+ordering above. Parser support does not solve that semantic mismatch.
+
+### Generic Node
+
+The Node preset runs the same in-function model behind your server or reverse
+proxy. A CDN in front may cache complete responses when you emit shared-cache
+headers, but that CDN is outside Rango and follows the HTTP CDN row in the
+matrix.
+
+## Cache-Control is the full-response mitigation
+
+If a response is completely public and shared, HTTP caching can eliminate more
+origin work than CDN-stitched PPR:
+
+```http
+Cache-Control: public, s-maxage=300, stale-while-revalidate=3600
+```
+
+On a CDN hit the function does not run and no shell or dynamic tail crosses the
+origin boundary. The tradeoff is exact: the CDN stores the **completed** HTML
+response, including loader output, resumed holes, and hydration payload. It
+does not cache only the PPR prelude.
+
+Use shared HTTP caching only when all of these are true:
+
+- the complete response is identical for every request sharing the cache key;
+- no authorization, redirect, rate-limit, tenant, or preview middleware must
+  run on every request;
+- no loader or rendered value contains session, cart, account, experiment, or
+  other per-user data;
+- replaying the response headers is safe, with no per-client `Set-Cookie`;
+- TTL/SWR freshness for the whole response is acceptable.
+
+Do not use `Vary: Cookie` as a general escape hatch. It creates a variant for
+every cookie combination, destroys cache reuse, and makes the safety contract
+hard to audit.
+
+### One header, two possible consumers
+
+`createDocumentCacheMiddleware()` parses `Cache-Control: s-maxage` as policy for
+the configured app store's response family. The deployment platform may also
+interpret the same header and cache the response at its CDN.
+
+These are independent caches:
+
+```text
+CDN HIT
+  -> function never runs
+
+CDN MISS
+  -> function
+     -> Rango document-cache middleware HIT or MISS
+```
+
+Consequences:
+
+- `skipPaths`, `isEnabled`, and `keyGenerator` only control the Rango
+  middleware. They cannot guard a response already served by the CDN.
+- `x-document-cache-status` reports the Rango store only when the function
+  executes. A CDN may replay an old status header; use the platform's own cache
+  header or logs to identify CDN hits.
+- Platform CDN invalidation and the app store's tags/TTL are separate systems.
+  Do not assume `updateTag()` purges an external CDN response.
+
+Use a platform-targeted header such as `Vercel-CDN-Cache-Control` when you need
+to keep CDN policy out of browser/downstream `Cache-Control`, but the complete
+response and middleware-bypass rules are unchanged. Rango's document middleware
+does not parse that platform-specific header; use it when the CDN, rather than
+the app store, should own the complete response.
+
+## Decision guide
+
+| Requirement                                         | Choose                                     |
+| --------------------------------------------------- | ------------------------------------------ |
+| Per-request auth or request shaping                 | in-function caching; never shared CDN HTML |
+| Stable shell with cart/session/live prices          | `ppr` with live holes                      |
+| Build-known segments with live loaders              | `Prerender()`                              |
+| Fully public response, whole-page TTL is acceptable | HTTP `s-maxage` + SWR                      |
+| Whole response reused inside the app store          | `createDocumentCacheMiddleware()`          |
+| One query or component is expensive                 | `"use cache"`                              |
+| One route subtree is expensive                      | `cache()`                                  |
+
+For a large dynamic app, CDN-stitched PPR would mainly improve shell first-byte
+latency and avoid sending the prelude from the function. It would not remove the
+per-request function invocation, live loaders, Flight payload, or React resume.
+If the current in-function path is already fast, preserve middleware semantics
+and apply full-response CDN caching only to the smaller set of routes that are
+provably public and shared.
+
+## Related skills
+
+- `/ppr` — shell capture, holes, middleware commit point, invalidation
+- `/prerender` — build-time Flight segments and `Prerender + ppr`
+- `/document-cache` — store-backed complete-response middleware
+- `/vercel` — Vercel Build Output preset and Runtime Cache wiring
+- `/cloudflare` — Worker deployment and bindings
+- `/cache-guide` — function, loader, and segment cache selection

package/skills/document-cache/SKILL.md

@@ -1,82 +1,114 @@
 ---
 name: document-cache
-description: Cache full HTTP responses at the edge with Cache-Control headers
+description: Cache complete HTTP responses in Rango's configured app store with createDocumentCacheMiddleware, using Cache-Control s-maxage as policy. Use when reusing a whole HTML/RSC response, comparing the store-backed middleware with a platform CDN cache, or deciding whether full-response caching is safe.
 argument-hint: [setup]
 ---
 
-# Document Cache
+# Store-backed Document Cache
 
-Caches complete HTTP responses (HTML/RSC) at the edge based on Cache-Control headers. Routes opt-in by setting `s-maxage`.
+Caches complete HTTP responses (HTML/RSC) in the app-level cache store based on
+`Cache-Control`. Routes opt in by setting `s-maxage`.
+
+This middleware runs **inside** the worker/function. It is not itself a platform
+CDN cache. With `CFCacheStore` the response family can use Cloudflare's edge/KV
+tiers; with `VercelCacheStore` it uses Vercel Runtime Cache. The request still
+reaches Rango before the middleware can return a store hit.
+
+## Not this skill if…
+
+- You want loaders to stay live while rendered segments are reused — document
+  caching freezes the WHOLE response, loader output included; segment caching
+  is `cache()`: see `/caching`.
+- You want a cached HTML shell with per-request live holes — see `/ppr`.
+- You are unsure which cache layer you need — start at `/cache-guide`.
+- You mean a platform CDN that serves a complete response without invoking the
+  app — see `/deployment-caching` first.
 
 ## 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) => ({ store: 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";
+The deployment platform may independently interpret the same `s-maxage` header
+and cache the completed response at its CDN. A CDN hit bypasses the function,
+all Rango middleware, handlers, and loaders. Therefore these headers are safe
+only when the **complete** response is public and identical for every request
+sharing the cache key. The middleware's `skipPaths`, `isEnabled`, and
+`keyGenerator` cannot protect a response once an outer CDN serves it.
 
-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" }),
-]);
+```typescript
+// 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 +121,7 @@ Request → Check Cache
     ↓             ↓
   Fresh?      Run handler
     │             │
-   Yes → Return   Has documentCache?
+   Yes → Return   Has s-maxage?
     │             │
    No (stale)    Yes → Cache + Return
     │             │
@@ -99,6 +131,11 @@ Request → Check Cache
   background (SWR)
 ```
 
+This diagram starts after the request reaches the Rango middleware. A store hit
+short-circuits the middleware's downstream pipeline; global middleware that
+wraps it can still run. Route middleware, handlers, and loaders below it do not.
+An external CDN hit is different: the function never runs at all.
+
 ## Cache Status Header
 
 Response includes `x-document-cache-status`:
@@ -107,6 +144,10 @@ Response includes `x-document-cache-status`:
 - `STALE` - Served stale, revalidating in background
 - `MISS` - Cache miss, response was generated fresh
 
+This header reports the Rango store-backed middleware, not the platform CDN. A
+CDN may replay a previously cached status header, so use the platform's cache
+header or logs to identify an actual CDN hit.
+
 ## Cache Key Generation
 
 Default keys differentiate:
@@ -120,13 +161,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 +176,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) => ({ store: 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,8 +230,11 @@ 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          |
 
 Use document cache for mostly-static pages. Use segment cache when different parts of a page have different cache requirements.
+
+See `/deployment-caching` for the full in-function versus CDN execution matrix,
+middleware implications, and the shared-response safety checklist.

package/skills/fonts/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fonts
-description: Load and configure web fonts with preload hints for optimal performance
+description: Load and configure web fonts with preload hints for optimal performance. Use when adding a custom font to a Rango app, fonts flash or swap on load (FOUT/FOIT), or you want font preload for performance.
 argument-hint: [provider]
 ---
 

package/skills/handler-use/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: handler-use
-description: Attach default loaders, middleware, parallels, and other use items directly to handlers via handler.use, and compose them with explicit use() at mount sites
+description: Attach default loaders, middleware, parallels, and other use items directly to handlers via handler.use, and compose them with explicit use() at mount sites. Use when a handler needs its own default middleware/loader without repeating use() at every mount site, or deciding between handler-level defaults and per-route use().
 argument-hint: "[handler]"
 ---
 
@@ -40,7 +40,7 @@ ProductPage.use = () => [
   loading(<ProductSkeleton />),
   middleware(async (ctx, next) => {
     await next();
-    ctx.header("Cache-Control", "private, max-age=60");
+    ctx.headers.set("Cache-Control", "private, max-age=60");
   }),
 ];
 ```
@@ -51,13 +51,15 @@ Now `ProductPage` carries its loader, loading state, and response-header middlew
 
 `handler.use()` is the same callback shape regardless of where the handler runs, but the runtime validates that the items it returns are valid for the mount site. Driven by `MOUNT_SITE_ALLOWED_TYPES` in [resolve-handler-use.ts](../../src/route-definition/resolve-handler-use.ts):
 
-| Mount site                                        | Allowed item types                                                                                                                             |
-| ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
-| `path()` / `route()`                              | `layout`, `parallel`, `intercept`, `middleware`, `revalidate`, `loader`, `loading`, `errorBoundary`, `notFoundBoundary`, `cache`, `transition` |
-| `layout()`                                        | All of the above, plus `route`, `include`                                                                                                      |
-| `parallel()` (per slot)                           | `revalidate`, `loader`, `loading`, `errorBoundary`, `notFoundBoundary`, `transition`                                                           |
-| `intercept()`                                     | `middleware`, `revalidate`, `loader`, `loading`, `errorBoundary`, `notFoundBoundary`, `layout`, `route`, `when`, `transition`                  |
-| Response routes (`path.json()`, `path.text()`, …) | `middleware`, `cache`                                                                                                                          |
+| Mount site                                        | Allowed item types                                                                                                                                                                        |
+| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `path()` / `route()`                              | `layout`, `parallel`, `intercept`, `middleware`, `revalidate`, `loader`, `loading`, `errorBoundary`, `notFoundBoundary`, `cache`, `transition`                                            |
+| `layout()`                                        | All of the above, plus `route`, `include`                                                                                                                                                 |
+| `parallel()` (per slot)                           | `revalidate`, `loader`, `loading`, `errorBoundary`, `notFoundBoundary`, `transition`                                                                                                      |
+| `intercept()`                                     | `middleware`, `revalidate`, `loader`, `loading`, `errorBoundary`, `notFoundBoundary`, `layout`, `route`, `transition` (conditional activation is config-only: `intercept(..., { when })`) |
+| 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.