@rangojs/router 0.0.0-experimental.8 → 0.0.0-experimental.80daa23e

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/cf";
+import {
+  createDocumentCacheMiddleware,
+  CFCacheStore,
+} from "@rangojs/router/cache";
 import { urlpatterns } from "./urls";
 
-const router = createRouter<AppEnv>({
+const router = createRouter<AppBindings>({
   document: Document,
   urls: urlpatterns,
-  documentCache: (env) => ({
-    store: new CFCacheStore({ ctx: env.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()
-
-Routes opt-in to document caching using the `cache()` DSL with `documentCache` option:
-
-```typescript
-import { urls } from "@rangojs/router";
+## Route Opt-In with Cache-Control
 
-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" }),
-  ]),
+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).
 
-  // Long cache for individual posts
-  cache({ documentCache: { sMaxAge: 3600, swr: 86400 } }, () => [
-    path("/blog/:slug", BlogPost, { name: "blogPost" }),
-  ]),
+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.
 
-  // 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) => ({
-    // Cache store (required)
-    store: new CFCacheStore({ ctx: env.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,16 +131,27 @@ 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`:
+
 - `HIT` - Fresh cache hit
 - `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:
+
 - HTML requests: `{pathname}:html`
 - RSC partials: `{pathname}:{segmentHash}:rsc`
 
@@ -118,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
@@ -132,49 +176,65 @@ 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/cf";
+import { createDocumentCacheMiddleware, CFCacheStore } from "@rangojs/router/cache";
 import { urlpatterns } from "./urls";
 
-const router = createRouter<AppEnv>({
+const router = createRouter<AppBindings>({
   document: Document,
   urls: urlpatterns,
-  documentCache: (env) => ({
-    store: new CFCacheStore({ ctx: env.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
 
-| 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 |
+| 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.
+
+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

@@ -0,0 +1,167 @@
+---
+name: fonts
+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]
+---
+
+# Fonts
+
+Load web fonts in the Document component with `<link rel="preload">` for optimal performance. Fonts are declared in `<head>` alongside your stylesheet.
+
+## Google Fonts
+
+```tsx
+// src/document.tsx
+"use client";
+
+import type { ReactNode } from "react";
+import { MetaTags } from "@rangojs/router/client";
+import styles from "./index.css?url";
+
+export function Document({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en">
+      <head>
+        {/* Preconnect to Google Fonts */}
+        <link rel="preconnect" href="https://fonts.googleapis.com" />
+        <link
+          rel="preconnect"
+          href="https://fonts.gstatic.com"
+          crossOrigin="anonymous"
+        />
+
+        {/* Load font stylesheet */}
+        <link
+          href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap"
+          rel="stylesheet"
+        />
+
+        {/* App styles */}
+        <link rel="preload" href={styles} as="style" />
+        <link rel="stylesheet" href={styles} />
+        <MetaTags />
+      </head>
+      <body>{children}</body>
+    </html>
+  );
+}
+```
+
+Then reference the font in CSS:
+
+```css
+/* src/index.css */
+body {
+  font-family: "Inter", sans-serif;
+}
+```
+
+Or with Tailwind (see `/tailwind`):
+
+```css
+/* src/index.css */
+@theme {
+  --font-sans: "Inter", sans-serif;
+}
+```
+
+## Self-Hosted Fonts
+
+Place font files in `public/fonts/` and use `@font-face`:
+
+```css
+/* src/index.css */
+@font-face {
+  font-family: "CustomFont";
+  src: url("/fonts/custom-regular.woff2") format("woff2");
+  font-weight: 400;
+  font-style: normal;
+  font-display: swap;
+}
+
+@font-face {
+  font-family: "CustomFont";
+  src: url("/fonts/custom-bold.woff2") format("woff2");
+  font-weight: 700;
+  font-style: normal;
+  font-display: swap;
+}
+
+body {
+  font-family: "CustomFont", sans-serif;
+}
+```
+
+Preload the most critical weight in the Document:
+
+```tsx
+export function Document({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en">
+      <head>
+        <link
+          rel="preload"
+          href="/fonts/custom-regular.woff2"
+          as="font"
+          type="font/woff2"
+          crossOrigin="anonymous"
+        />
+        <link rel="preload" href={styles} as="style" />
+        <link rel="stylesheet" href={styles} />
+        <MetaTags />
+      </head>
+      <body>{children}</body>
+    </html>
+  );
+}
+```
+
+## Fontsource (Recommended for Vite)
+
+`@fontsource-variable` packages are the recommended approach with Vite. Fonts are installed as npm dependencies, bundled by Vite, and served from your own domain -- no external requests, no privacy concerns, no FOUT from slow CDNs.
+
+```bash
+pnpm add @fontsource-variable/inter
+```
+
+Import the font CSS in your stylesheet. Vite resolves the `@fontsource-variable` import from `node_modules` and bundles the woff2 files as hashed assets automatically:
+
+```css
+/* src/index.css */
+@import "@fontsource-variable/inter";
+
+body {
+  font-family: "Inter Variable", sans-serif;
+}
+```
+
+With Tailwind:
+
+```css
+/* src/index.css */
+@import "@fontsource-variable/inter";
+@import "tailwindcss";
+
+@theme {
+  --font-sans: "Inter Variable", sans-serif;
+}
+```
+
+Why this is preferred over Google Fonts with Vite:
+
+- No external network requests at runtime -- fonts are bundled into your build output
+- No `<link rel="preconnect">` or extra stylesheet needed in the Document
+- Variable font = single file covers all weights, smaller total download
+- Vite handles cache-busting via content hashes
+- Works offline and in edge deployments (Cloudflare Workers) without external dependencies
+
+Browse available fonts at fontsource.org. Use `@fontsource-variable/*` for variable fonts and `@fontsource/*` for static fonts.
+
+## Performance Tips
+
+- Prefer `@fontsource-variable` with Vite for self-hosted, zero-config font loading
+- Use `font-display: swap` to prevent invisible text during font load
+- Preload only the most critical font weight (usually regular 400)
+- Prefer `woff2` format for smaller file sizes
+- Use variable fonts when multiple weights are needed to reduce total file count
+- `<link rel="preconnect">` eliminates DNS + TLS latency for external font providers