@rangojs/router 0.1.1 → 0.2.0

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,12 +1,18 @@
 ---
 name: document-cache
-description: Cache the whole HTTP response at the edge with Cache-Control headers. Use when caching an entire page or response at a CDN edge, setting Cache-Control headers, or cutting origin hits for public pages — not for caching a single segment or function.
+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…
 
@@ -15,6 +21,8 @@ Caches complete HTTP responses (HTML/RSC) at the edge based on Cache-Control hea
   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
 
@@ -55,6 +63,13 @@ 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).
 
+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.
+
 ```typescript
 // Cache full page for 5 min, serve stale for 1 hour
 function BlogIndexHandler(ctx) {
@@ -116,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`:
@@ -124,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:
@@ -211,3 +235,6 @@ function BlogPost(ctx) {
 | 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/ppr/SKILL.md

@@ -7,16 +7,21 @@ argument-hint: "[setup]"
 # PPR Shell Caching
 
 Caches the rendered HTML **shell** of a page route (React `prerender` prelude
-bytes plus `postponed` state) and, on a later request, flushes those bytes
-before any render work happens, then resumes fizz for just the live holes. The
-browser sees one ordinary streamed document; loaders stay fresh on every
-request. This is the second render axis — the default axis-1 path is untouched,
-and every ineligible request falls open to it.
+bytes plus `postponed` state) and, on a later request, flushes those bytes after
+route classification and the complete middleware chain, but before downstream
+tail rendering. It then resumes fizz for just the live holes. The browser sees
+one ordinary streamed document; loaders stay fresh on every request. This is
+the second render axis — the default axis-1 path is untouched, and every
+ineligible request falls open to it.
 
 Compare `/document-cache`, which freezes the WHOLE response including loader
 output. Shell caching is for pages that mix a stable shell with live data: the
 shell is shared per host+URL, the holes are per request.
 
+This is in-function PPR on every deployment. The worker/function serves the
+prelude; it is not a CDN static file. See `/deployment-caching` before combining
+PPR with HTTP shared-cache headers.
+
 ## Not this skill if…
 
 - You want the WHOLE response frozen, loader output included — see
@@ -188,21 +193,31 @@ and loader-container pins are NOT replayed on this path, so loader reads stay
 live. A route's own `cache()` scope still resolves its normal store, key, TTL,
 SWR, tags, and condition; only the implicit document scope sees the replay
 overlay, and fresh segment writes there stay request-local rather than polluting
-the canonical `doc:` namespace. Intercepts, handler-live holes,
-`transition({ when })`, an active nonce, and an absent/corrupt segment snapshot
-fall open to the ordinary partial path when encountered by the fresh shell
-capture. A transition already replayed from an explicit cache tier remains
-frozen by that tier's normal semantics.
-
-Only fresh shells replay. Production may use either a runtime entry or the
-local build manifest; development uses runtime entries only, because probing
-`/__rsc_shell` would block the foreground navigation on an on-demand capture.
-A passive stale read does not claim SWR ownership because partial requests
-cannot recapture the HTML shell. Custom `SegmentCacheStore` implementations
-must set `supportsPassiveShellReads: true` and honor
-`getShell(key, { claimRevalidation: false })` to opt into navigation replay.
-There is still no Flight resume API; this is segment replay followed by normal
-Flight streaming, not reuse of the HTML `prelude`/`postponed` bytes.
+the canonical `doc:` namespace. `transition({ when })` is evaluated from the
+matched manifest before route handlers on every PPR match, so it can vary by
+URL/params/action or middleware context without disabling replay; handler-set
+context is unavailable by design. Intercepts, handler-live holes, an active
+nonce, and an absent/corrupt segment snapshot fall open to the ordinary partial
+path when encountered by the shell capture. A transition already replayed from
+an explicit cache tier remains frozen by that tier's normal semantics.
+
+Fresh and stale-within-SWR runtime shells replay. The stale read is passive: it
+uses `getShell(key, { claimRevalidation: false })`, does not claim SWR ownership,
+and cannot recapture HTML. A later document request owns the background
+recapture; hard-expired entries fall open. Production may also use a fresh local
+build manifest; development stays runtime-only because probing `/__rsc_shell`
+would block navigation on an on-demand capture. Custom `SegmentCacheStore`
+implementations must set `supportsPassiveShellReads: true` and honor the
+non-claiming read option.
+
+Partial responses expose the actual decision as `x-rango-ppr-replay`:
+`HIT; freshness=fresh|stale` or `BYPASS; reason=<bounded-token>`. With
+performance metrics enabled, the same decision appears as
+`ppr-navigation-replay` in `Server-Timing`. `HIT` means matching consumed the
+seeded segment record after it decoded successfully, not merely that a snapshot
+existed. An explicit `cache()` scope that supplies the match cannot produce a
+false HIT. There is still no Flight resume API; this is segment replay followed
+by normal Flight streaming, not reuse of the HTML `prelude`/`postponed` bytes.
 
 ### Capture-generation invalidation
 
@@ -252,7 +267,12 @@ sees the header directly; only an explicit Flight request shape lacks it:
 curl -s -D - -o /dev/null https://app.example.com/products/1 | grep -i x-rango-shell
 ```
 
-- First document GET: `MISS`, plus a background capture.
+- Runtime-captured route: first document GET is `MISS`, plus a background
+  capture; a later request becomes a `HIT`.
+- `Prerender + ppr` route: the shell is produced during `vite build`, so the
+  first production document request can already be a `HIT`. In dev, producer B
+  runs on demand and can return a `HIT`; if capture outlasts the bounded
+  foreground wait, the request falls open to `MISS` and runtime capture.
 - Production (workerd/node): the SECOND request is a `HIT`.
 - Dev: expect a few extra MISSes — cold module transforms abort the capture
   window (per-attempt breadcrumbs: start the server with
@@ -284,6 +304,8 @@ Import from `@rangojs/router/testing` (Vitest) or `@rangojs/router/testing/e2e`
 | Helper                                            | Use for                                                      |
 | ------------------------------------------------- | ------------------------------------------------------------ |
 | `assertShellStatus(res, "HIT" \| "MISS")`         | Document Response from a real RSC serve / e2e `page.request` |
+| `assertPprReplayStatus(res, expected)`            | Partial response fresh/stale replay or bounded bypass        |
+| `parsePprReplayStatus(res)`                       | Read structured replay/bypass status or null                 |
 | `shellCacheKey(url)`                              | Production store key for `store.getShell` / custom stores    |
 | `MemorySegmentCacheStore` + `getShell`/`putShell` | Custom store contract / tag eviction (no faked HIT)          |
 
@@ -639,11 +661,18 @@ path(
 | `swr`              | —       | stale window: serve the stale shell + background recapture                                                                                                |
 | `tags`             | —       | operational tags UNIONED with the tags the capture render auto-collects — see "Invalidation" below                                                        |
 | `maxSnapshotBytes` | 8 MiB   | cap on the entry's capture data snapshot; over it the snapshot is skipped (shell still stored, warned once per key) so the entry stays under store limits |
+| `captureTimeout`   | 15000ms | capture settle budget; a timed-out capture is refused rather than storing a partial shell                                                                 |
 
 The shell store is always the app-level `createRouter({ cache })` store; the
 default key is `${host}${pathname}${sortedSearch}:shell` (host-scoped so
 multi-tenant shells never collide).
 
+These options control the in-function shell entry only. They do not emit HTTP
+`Cache-Control`. Adding `s-maxage` separately allows a platform CDN to cache the
+completed response, including the live-hole output, and CDN hits bypass Rango
+middleware entirely. Only do that for a fully public response whose complete
+output is shared; see `/deployment-caching`.
+
 ## Invalidation: tags vs revalidate()
 
 `updateTag()`/`revalidateTag()` is the ONLY lever that changes the frozen shell
@@ -676,8 +705,9 @@ evicted by tag at all — move always-fresh data under a `loading()` hole.
 - **A bake-lane container that must be fresh per document GET**: it is
   snapshot-pinned for the shell's lifetime by design. Use the live lane
   (`loading()`) or a nested promise instead.
-- **A bake-lane loader slower than the capture guard (~5s)**: the capture
-  cannot hold for it — eternal MISS with the once-per-key warning.
+- **A bake-lane loader slower than `ppr.captureTimeout` (15s by default)**: the
+  capture is refused rather than storing a partial shell. Increase the route's
+  budget only when the deployment can keep the background/build work alive.
 - **Per-user value in shell material**: baked into the shared shell —
   deterministically, not by race (handler promises deep-settle at the ring-3
   write on cached chains; awaited/resolved values bake everywhere). Put
@@ -728,8 +758,10 @@ cache"` value baked into the shell is PINNED at capture (the capture data
   prelude and detonate hydration. Wrap it in `cache()`/`"use cache"` (then it is
   pinned) or move it under a hole (`loading()`, or a pending-promise
   `<Suspense>` region).
-- **Stacking with `/document-cache`**: pick one per route — the document cache
-  would cache the composite.
+- **Stacking with `/document-cache` or HTTP CDN caching**: both cache the
+  completed composite, including live-hole output, so PPR becomes redundant on
+  a hit. A platform CDN also bypasses every Rango middleware. Restrict this to
+  fully public, shared responses; see `/deployment-caching`.
 - **Dev + HMR**: works, but edits produce stale shells until TTL/recapture.
 - **Dev cold-start cadence**: expect `MISS -> (in-place retry) -> HIT`. A
   refused capture is negatively cached with an exponential window (1s doubling

package/skills/prerender/SKILL.md

@@ -326,18 +326,25 @@ This only applies when `__PRERENDER_DEV_URL` is set by the plugin.
 
 ## Storage Layout
 
-Pre-rendered Flight payloads are stored in the build output:
+Pre-rendered Flight payloads are stored as content-hashed modules behind a lazy
+manifest in the RSC server bundle. They are not public `.rsc` files:
 
 ```
-dist/static/__<hash>/
-  prerender/
-    blog.post/
-      d4e5f6a7.flight    # hash of { slug: "hello-world" }
-      b8c9d0e1.flight    # hash of { slug: "getting-started" }
-    about/
-      _.flight            # static route, no params
+dist/rsc/
+  __prerender-manifest.js
+  assets/
+    __pr-<content-hash>.js
+
+# When a Prerender route also declares ppr:
+  __shell-manifest.js
+  assets/
+    __ps-<content-hash>.js
 ```
 
+The worker/function handles every request and reads these modules as build-time
+cache entries. See `/deployment-caching` for how this differs from a platform
+CDN static or prerender output.
+
 ## Concurrency
 
 Prerender handlers can specify how many param sets render in parallel:

package/skills/rango/SKILL.md

@@ -110,6 +110,7 @@ stated, greppable contract.
 | pre-render a route at build time        | `Prerender(...)` wrapper           | /prerender              |
 | feed live loaders from a cached shell   | replayed handle + `ctx.rendered()` | /shell-manifest         |
 | cache the HTML shell, keep loaders live | `ppr` path option                  | /ppr                    |
+| choose in-function vs CDN caching       | deployment cache boundary          | /deployment-caching     |
 | stream SSE / upgrade a WebSocket        | `path.stream()` / `path.any()`     | /streams-and-websockets |
 
 ## Invariants
@@ -161,8 +162,8 @@ Same words, different jobs — this is the most common source of the
 | Next.js `export const revalidate = N`   | **Axis 1** (cache) | Same word, opposite meaning. Next's `revalidate` is time-based cache expiry; Rango's `revalidate()` is **axis 2**. Use `cache({ ttl })` for the Next behavior.                                                                                                                          |
 | Next.js `revalidateTag` / `updateTag`   | **Axis 1** (cache) | Cache busting by tag. Tag via `cache({ tags })` / `cacheTag(...tags)`; invalidate with `updateTag(...tags)` (awaitable, read-your-own-writes) or `revalidateTag(...tags)` (background, non-blocking). Built-in stores index by tag. No `revalidatePath` (path-based busting); use tags. |
 | React Router / Remix `shouldRevalidate` | **Axis 2**         | This is the correct mental model for Rango's `revalidate()`.                                                                                                                                                                                                                            |
-| HTTP `Cache-Control` / ISR              | **Axis 1**         | Edge/document layer — see `/document-cache`. Separate from both `cache()` and `revalidate()`.                                                                                                                                                                                           |
-| Next.js PPR (partial prerendering)      | HTML shell layer   | Same idea, different wiring: the opt-in `ppr` path option captures at runtime (no build-time default); holes are render-defined — `loading()` subtrees plus pending promises under a consumer's own `<Suspense>`. See `/ppr`.                                                           |
+| HTTP `Cache-Control` / ISR              | Deployment layer   | Complete-response deployment layer. A CDN hit bypasses Rango entirely; the store-backed middleware does not. See `/deployment-caching` and `/document-cache`.                                                                                                                           |
+| Next.js PPR (partial prerendering)      | HTML shell layer   | Same React primitive, different transport: Rango serves shells in-function after middleware. Ordinary `ppr` captures at runtime; `Prerender + ppr` captures at build. See `/ppr`, `/prerender`, and `/deployment-caching`.                                                              |
 | Remix/RR `loader`                       | live data          | Like Rango loaders, fresh per request — but Rango loaders run in parallel and stream (latency overlaps first paint), and can opt into caching on demand.                                                                                                                                |
 
 See `/cache-guide` for the axis-1 decision guide, `/loader` and `/route` for
@@ -257,17 +258,18 @@ Grouped by concern — read when you need to…
 
 **Data & caching** — fetch, mutate, and cache:
 
-| Skill             | Description                                                                                                                                                       |
-| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `/loader`         | Data loaders with `createLoader()` and `revalidate()`                                                                                                             |
-| `/server-actions` | Mutations with `"use server"`, useActionState, validation, revalidation                                                                                           |
-| `/caching`        | Segment caching with memory or KV stores                                                                                                                          |
-| `/use-cache`      | Function-level caching with `"use cache"` directive                                                                                                               |
-| `/cache-guide`    | When to use `cache()` vs `"use cache"` — differences and decision guide                                                                                           |
-| `/document-cache` | Edge caching with Cache-Control headers                                                                                                                           |
-| `/ppr`            | PPR shell caching: cached shell served instantly, live holes resumed — a hole is a `loading()` subtree OR a pending promise under `<Suspense>` (no loader needed) |
-| `/prerender`      | Pre-render route segments at build time (Passthrough live fallback)                                                                                               |
-| `/shell-manifest` | Replayed handles as cache metadata read by live loaders (frozen shell, batched live holes)                                                                        |
+| Skill                 | Description                                                                                                                                                       |
+| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `/loader`             | Data loaders with `createLoader()` and `revalidate()`                                                                                                             |
+| `/server-actions`     | Mutations with `"use server"`, useActionState, validation, revalidation                                                                                           |
+| `/caching`            | Segment caching with memory or KV stores                                                                                                                          |
+| `/use-cache`          | Function-level caching with `"use cache"` directive                                                                                                               |
+| `/cache-guide`        | When to use `cache()` vs `"use cache"` — differences and decision guide                                                                                           |
+| `/document-cache`     | Store-backed complete-response middleware using Cache-Control policy                                                                                              |
+| `/deployment-caching` | Choose between in-function caches, store-backed responses, and an external CDN cache                                                                              |
+| `/ppr`                | PPR shell caching: cached shell served instantly, live holes resumed — a hole is a `loading()` subtree OR a pending promise under `<Suspense>` (no loader needed) |
+| `/prerender`          | Pre-render route segments at build time (Passthrough live fallback)                                                                                               |
+| `/shell-manifest`     | Replayed handles as cache metadata read by live loaders (frozen shell, batched live holes)                                                                        |
 
 **Client & presentation** — build the client-side UX:
 
@@ -295,10 +297,11 @@ Grouped by concern — read when you need to…
 
 **Deployment**:
 
-| Skill         | Description                                                                                                      |
-| ------------- | ---------------------------------------------------------------------------------------------------------------- |
-| `/cloudflare` | Deploy to Cloudflare Workers with the Vite plugin, typed D1/KV bindings, migrations, secrets, and preview parity |
-| `/vercel`     | Deploy to Vercel Functions (`preset: "vercel"`), Runtime Cache, and `createVercelTracing`                        |
+| Skill                 | Description                                                                                                      |
+| --------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `/cloudflare`         | Deploy to Cloudflare Workers with the Vite plugin, typed D1/KV bindings, migrations, secrets, and preview parity |
+| `/vercel`             | Deploy to Vercel Functions (`preset: "vercel"`), Runtime Cache, and `createVercelTracing`                        |
+| `/deployment-caching` | Compare deployment cache boundaries, middleware execution, PPR transport, and HTTP CDN caching                   |
 
 **Testing**:
 

package/skills/testing/SKILL.md

@@ -88,7 +88,7 @@ Each primitive links to its sub-file (API + recipe + caveats).
 | a loader's cookie / header / redirect output (auth-loader pattern)                                                                 | unit (node)  | [`runLoaderResult`](./loader.md)                                                              | `@rangojs/router/testing`        |
 | one middleware's ordering / short-circuit / cookie+header merge                                                                    | unit (node)  | [`runMiddleware`](./middleware.md)                                                            | `@rangojs/router/testing`        |
 | a `"use server"` action's cookie / header / flash output (even on `throw redirect()`)                                              | unit (node)  | [`runInRequestContext`](./server-actions.md)                                                  | `@rangojs/router/testing`        |
-| a `transition({ when })` gate (keep/drop) against nav source / target / action metadata                                            | unit (node)  | `runTransitionWhen` (`{ kept, whenContext }`)                                                 | `@rangojs/router/testing`        |
+| a `transition({ when })` gate (keep/drop) against nav source / target / action metadata                                            | unit (node)  | `runTransitionWhen` (`{ kept, whenContext }`; pass `{ ppr: true }` for pre-handler timing)    | `@rangojs/router/testing`        |
 | a handle's `collect`/accumulator, or a seeded handle read                                                                          | unit         | [`collectHandle` / seeded `handles`](./handles.md)                                            | `@rangojs/router/testing`        |
 | a CLIENT component reading router context (`useParams`/`useReverse`/`Outlet`/`useNavigation`/`useLoader`)                          | unit (DOM)   | [`renderRoute`](./client-components.md)                                                       | `@rangojs/router/testing/dom`    |
 | a redirect / status / headers / cookies / **response route** (json/text/html/xml/md), no Flight                                    | integration  | [`dispatch`](./response-routes.md)                                                            | `@rangojs/router/testing`        |

package/skills/testing/cache-prerender.md

@@ -113,7 +113,7 @@ expect(decision.segments?.[0].shouldRevalidate).toBe(true);
 
 `events` accumulates across requests, so the FIRST matching segment for a `routeKey` wins — slice or recreate the sink between requests for the same route.
 
-## PPR shell (`x-rango-shell`)
+## PPR shell and navigation replay
 
 **DSL:** `ppr: true | PartialPrerenderProps` on a page route (see `/ppr`). **Not** the same header as `X-Rango-Cache` — shell is a second render axis.
 
@@ -123,6 +123,9 @@ expect(decision.segments?.[0].shouldRevalidate).toBe(true);
 | `parseShellStatus(res)`                   | same                                 | `"HIT" \| "MISS" \| null` (null = header absent / unrecognized)                                        |
 | `shellCacheKey(url)`                      | same                                 | Production shell store key (`host+pathname+sorted search+:shell`) for `store.getShell` / custom stores |
 | `SHELL_STATUS_HEADER`                     | same                                 | `"x-rango-shell"` constant                                                                             |
+| `assertPprReplayStatus(res, expected)`    | same                                 | Assert fresh/stale replay or a bounded bypass decision                                                 |
+| `parsePprReplayStatus(res)`               | same                                 | Structured replay/bypass status, or null for an absent/unrecognized header                             |
+| `PPR_REPLAY_STATUS_HEADER`                | same                                 | `"x-rango-ppr-replay"` constant                                                                        |
 
 ### What unit can prove vs e2e
 
@@ -131,6 +134,7 @@ expect(decision.segments?.[0].shouldRevalidate).toBe(true);
 | **Unit** | store family + key identity | `MemorySegmentCacheStore` + `shellCacheKey(url)` + `putShell`/`getShell` / tag eviction — dogfood in `e2e/mini/test/shell-store-family.test.ts` and `src/testing/__tests__/shell-status.test.ts` |
 | **Unit** | header helper contract      | `assertShellStatus` on a Response that already carries the header (characterizes the helper; **never** invent a HIT to claim capture worked)                                                     |
 | **E2E**  | live MISS → capture → HIT   | document GET, poll until `x-rango-shell: HIT` (background capture) — `e2e/shell-cache.test.ts`                                                                                                   |
+| **E2E**  | partial replay decision     | soft navigation to a warmed shell and `assertPprReplayStatus(response, { outcome: "HIT", freshness: "fresh" })`                                                                                  |
 
 `dispatch` is RSC-free: it never runs shell serve/capture. `renderHandler` only surfaces `ctx.dynamic()` opt-out, not bake/serve.
 

package/skills/vercel/SKILL.md

@@ -8,6 +8,25 @@ argument-hint:
 
 The `vercel` preset builds like the `node` preset (Vercel runs Node Functions, not Workers): rango owns the RSC entry, folds `process.env.NODE_ENV` for the SSR/RSC build, and after `vite build` assembles a `.vercel/output` directory (Build Output API v3) from `dist/` — a single streaming Node Function plus the static client assets.
 
+## Deployment boundary
+
+Only client JS, CSS, and public assets are emitted under
+`.vercel/output/static`. HTML, Flight, prerender payloads, and PPR shells are
+served from the streaming Node Function. `VercelCacheStore` is an in-function
+Runtime Cache backend; it is separate from Vercel's CDN/ISR cache.
+
+The preset does not emit `.prerender-config.json`, a response `chain`, or a
+CDN-stitched PPR resume function. Rango PPR intentionally runs the whole global
+and route middleware chain before committing shell bytes. A CDN-first shell
+cannot preserve that contract because the resume function is invoked after the
+shell starts streaming.
+
+For fully public responses, HTTP `s-maxage`/`stale-while-revalidate` can cache
+the completed response at Vercel's CDN and avoid the function on a hit. That is
+whole-response caching: it freezes loader output and bypasses all Rango
+middleware. Use `/deployment-caching` for the execution matrix and safety
+checklist before adding shared-cache headers.
+
 ## Setup
 
 ```bash
@@ -48,7 +67,9 @@ rango({
 
 ## Runtime Cache
 
-`VercelCacheStore` wraps the Vercel Runtime Cache. Locally (no `process.env.VERCEL`) fall back to an in-memory store so dev/preview work without the platform:
+`VercelCacheStore` wraps the Vercel Runtime Cache for segment, item, response,
+and PPR shell families. Locally (no `process.env.VERCEL`) fall back to an
+in-memory store so dev/preview work without the platform:
 
 ```typescript
 import {