@rangojs/router 0.1.1 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.1.1",
+  "version": "0.4.0",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",
@@ -176,19 +176,6 @@
     "access": "public",
     "tag": "latest"
   },
-  "scripts": {
-    "build": "pnpm run build:types && pnpm exec esbuild src/vite/index.ts --bundle --format=esm --outfile=dist/vite/index.js --platform=node --packages=external && mkdir -p dist/vite/plugins && cp src/vite/plugins/cloudflare-protocol-loader-hook.mjs dist/vite/plugins/cloudflare-protocol-loader-hook.mjs && pnpm exec esbuild src/testing/vitest.ts --bundle --format=esm --outfile=dist/testing/vitest.js --platform=node --packages=external && pnpm exec esbuild src/bin/rango.ts --bundle --format=esm --outfile=dist/bin/rango.js --platform=node --packages=external --banner:js='#!/usr/bin/env node' && chmod +x dist/bin/rango.js",
-    "build:types": "rm -rf dist/types && pnpm exec tsc -p tsconfig.types.json",
-    "prepublishOnly": "pnpm build",
-    "typecheck": "tsc --noEmit && tsc -p tsconfig.strict-check.json --noEmit && tsc -p tsconfig.augment-check.json --noEmit",
-    "test": "playwright test",
-    "test:ui": "playwright test --ui",
-    "test:hmr-local": "playwright test --project=dev-warmup --project=hmr-basename --project=hmr-prerender --no-deps --workers=1 && RANGO_E2E_ROUTE_HMR_ONLY=1 playwright test --project=hmr-routes --no-deps --workers=1",
-    "test:hmr-routes-local": "RANGO_E2E_ROUTE_HMR_ONLY=1 playwright test --project=hmr-routes --no-deps --workers=1",
-    "test:unit": "pnpm run build:types && vitest run",
-    "test:unit:watch": "vitest",
-    "test:unit:rsc": "vitest run --config vitest.rsc.config.ts"
-  },
   "dependencies": {
     "@types/debug": "^4.1.12",
     "@vitejs/plugin-rsc": "^0.5.27",
@@ -204,19 +191,19 @@
     "@opentelemetry/context-async-hooks": "^2.9.0",
     "@opentelemetry/sdk-trace-base": "^2.9.0",
     "@playwright/test": "^1.49.1",
-    "@shared/e2e": "workspace:*",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/react": "^16.3.2",
     "@types/node": "^24.10.1",
-    "@types/react": "catalog:",
-    "@types/react-dom": "catalog:",
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
     "esbuild": "^0.28.1",
     "happy-dom": "^20.10.1",
     "jiti": "^2.7.0",
-    "react": "catalog:",
-    "react-dom": "catalog:",
+    "react": "^19.2.6",
+    "react-dom": "^19.2.6",
     "typescript": "^5.3.0",
-    "vitest": "^4.1.9"
+    "vitest": "^4.1.9",
+    "@shared/e2e": "0.0.1"
   },
   "peerDependencies": {
     "@cloudflare/vite-plugin": "^1.42.1",
@@ -255,5 +242,17 @@
   },
   "engines": {
     "node": ">=24.0.0"
+  },
+  "scripts": {
+    "build": "pnpm run build:types && pnpm exec esbuild src/vite/index.ts --bundle --format=esm --outfile=dist/vite/index.js --platform=node --packages=external && mkdir -p dist/vite/plugins && cp src/vite/plugins/cloudflare-protocol-loader-hook.mjs dist/vite/plugins/cloudflare-protocol-loader-hook.mjs && pnpm exec esbuild src/testing/vitest.ts --bundle --format=esm --outfile=dist/testing/vitest.js --platform=node --packages=external && pnpm exec esbuild src/bin/rango.ts --bundle --format=esm --outfile=dist/bin/rango.js --platform=node --packages=external --banner:js='#!/usr/bin/env node' && chmod +x dist/bin/rango.js",
+    "build:types": "rm -rf dist/types && pnpm exec tsc -p tsconfig.types.json",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.strict-check.json --noEmit && tsc -p tsconfig.augment-check.json --noEmit",
+    "test": "playwright test",
+    "test:ui": "playwright test --ui",
+    "test:hmr-local": "playwright test --project=dev-warmup --project=hmr-basename --project=hmr-prerender --no-deps --workers=1 && RANGO_E2E_ROUTE_HMR_ONLY=1 playwright test --project=hmr-routes --no-deps --workers=1",
+    "test:hmr-routes-local": "RANGO_E2E_ROUTE_HMR_ONLY=1 playwright test --project=hmr-routes --no-deps --workers=1",
+    "test:unit": "pnpm run build:types && vitest run",
+    "test:unit:watch": "vitest",
+    "test:unit:rsc": "vitest run --config vitest.rsc.config.ts"
   }
-}
+}

package/skills/cache-guide/SKILL.md

@@ -131,8 +131,10 @@ recompute for a merely-aging entry.
   layer.
 - **Client forward/back** is SWR after a mutation — see "Correctness &
   invalidation" → Client cache.
-- **Edge / document layer** uses the HTTP `stale-while-revalidate` directive; see
-  `/document-cache`.
+- **Store-backed document layer** uses the HTTP `stale-while-revalidate`
+  directive as policy for `createDocumentCacheMiddleware`; see
+  `/document-cache`. A platform CDN may independently consume the same header
+  and bypass the function on hits; see `/deployment-caching`.
 
 SWR softens normal TTL expiry, **not** a cross-deploy cold cache — a new build
 has no stale entry to serve (see version-segmented store keys above).
@@ -485,5 +487,6 @@ overrides — see `/loader` for the full reference.
 
 - `/caching` — cache() DSL setup, stores, nested boundaries
 - `/use-cache` — "use cache" directive details, profiles, transforms, guards
-- `/document-cache` — Edge caching with Cache-Control headers (different layer)
+- `/document-cache` — store-backed complete-response middleware
+- `/deployment-caching` — in-function versus external CDN cache boundaries
 - `/ppr` — PPR shell caching: cached HTML shell + live loader holes (different layer)

package/skills/catalog.json

@@ -69,9 +69,15 @@
       "argumentHint": "",
       "path": "skills/defer-hydration/SKILL.md"
     },
+    {
+      "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.",
+      "argumentHint": "[cloudflare|vercel|node]",
+      "path": "skills/deployment-caching/SKILL.md"
+    },
     {
       "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.",
       "argumentHint": "[setup]",
       "path": "skills/document-cache/SKILL.md"
     },

package/skills/comparison/references/framework-comparison.md

@@ -539,7 +539,8 @@ analog but operates on loader/query reload, not RSC-segment render.
 
 ### Prefetching: stability and control
 
-`<Link prefetch="hover|viewport|render|adaptive|none">` (default `"none"`), plus
+`<Link prefetch="hover|viewport|render|adaptive|none">` (default: the router's
+`defaultPrefetch`, `"none"` in development and `"viewport"` in production), plus
 `prefetchKey` (`":source"` scopes a prefetch to the originating page for routes
 whose response branches on `currentUrl`). The distinguishing part is the stability
 gating: a queued prefetch (`viewport`/`render`) will not fire until **both** the

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
@@ -170,12 +175,14 @@ On a document GET to a ppr route the router runs:
 point is after the chain, an unauthorized request NEVER sees shell bytes — put
 auth middleware anywhere (global or route DSL) and it guards PPR for free.
 
-### Soft navigation reuses the captured segment shell
+### Soft navigation caches and reuses the handler layer
 
-A usable shell snapshot also accelerates ordinary partial RSC navigations to
-the same URL. The capture records the canonical document segment tree alongside
-the HTML prelude. On a partial request the server replays only that segment
-record through the normal `matchPartial()` pipeline, which then:
+Ordinary partial RSC navigations to a `ppr` URL use the same handler-layer cache
+contract even when no document request has captured an HTML shell yet. When a
+shell snapshot exists, the server replays its canonical document segment record.
+On a cold partial request, normal matching renders the response and schedules a
+background navigation-only shell capture; later navigations and prefetches
+replay its eligible snapshot. In both cases `matchPartial()`:
 
 - preserves client-owned shared layouts by segment id;
 - returns only new or revalidating destination segments;
@@ -186,23 +193,41 @@ This is deliberately invisible to the browser: the response is the same
 `RscPayload` shape as any other partial navigation. Captured item/response values
 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.
+SWR, tags, and condition; only the implicit PPR scope sees this behavior.
+`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 schedule a navigation-only capture. Production
+may also use a fresh local build manifest. Development does not probe
+`/__rsc_shell`; it schedules the same local background capture instead. Custom `SegmentCacheStore`
+implementations must set `supportsPassiveShellReads: true` and honor the
+non-claiming read option.
+
+The first cold partial request reports `BYPASS; reason=no-entry` because no
+artifact could supply that response; its successful render schedules
+`scheduleShellCapture` with a navigation-only marker. The next request reports
+`HIT` when the capture produced an eligible snapshot. Navigation snapshots use
+a separate shell key, so they cannot overwrite or be served as a document shell.
+The capture runs with the stripped target document URL and loads SSR support in
+the bounded background queue, outside the triggering partial response's latency.
+An `allReady` decision still declines capture.
+
+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 +277,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
@@ -272,7 +302,9 @@ curl -s -D - -o /dev/null https://app.example.com/products/1 | grep -i x-rango-s
 - Structured capture diagnostics: `createRouter({ debugShellCapture: true })`
   logs one line per capture attempt/skip (outcome, durations, prelude and
   snapshot bytes, backoff state); pass a function to receive each
-  `ShellCaptureDebugEvent` instead. In dev, with `debugPerformance` on, the
+  `ShellCaptureDebugEvent` instead. `skip-capacity` means the isolate already
+  has 32 queued/running captures; the dropped best-effort capture can retry on a
+  later request. In dev, with `debugPerformance` on, the
   last capture outcome for a key also rides the next document GET's
   `Server-Timing` as `ppr-capture;desc="…"`.
 
@@ -284,6 +316,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 +673,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 +717,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
@@ -720,7 +762,10 @@ cache"` value baked into the shell is PINNED at capture (the capture data
   it: call `cacheTag(...)` from the shell-material render code (the render-time
   lever), or add the tag to `ppr.tags` (operational tags the render cannot know —
   a tenant id, a deploy marker). Ring-1/ring-3 tag invalidation does NOT drop the
-  shell.
+  shell. Tags are optional: if TTL/SWR is the complete freshness policy, leave
+  the shell untagged. Rango does not warn for that choice; with
+  `debugShellCapture` enabled, a stored event reports `untaggedBake: true` when
+  bake-lane loader material uses TTL/SWR-only invalidation.
 - **Uncached nondeterminism in the shell is a hydration hazard**: a raw
   `Date.now()` / `Math.random()` / uncached `fetch` rendered directly in shell
   material (outside any cache ring) drifts between capture and hit and the
@@ -728,8 +773,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: