@rangojs/router 0.0.0-experimental.tapabs3 → 0.1.1

package/skills/ppr/SKILL.md

@@ -21,11 +21,12 @@ shell is shared per host+URL, the holes are per request.
 
 - You want the WHOLE response frozen, loader output included — see
   `/document-cache`.
-- You want routes rendered at build time with `Static()`/`Prerender()` — the
-  `ppr` path option captures at runtime; see `/prerender`.
+- You want build-time Flight segment payloads from `Static()`/`Prerender()` —
+  see `/prerender`. A `Prerender` page may also declare `ppr`; then producer B
+  can bake the HTML shell at build time while loaders stay live.
 - You are unsure which cache layer you need — start at `/cache-guide`.
 
-## Setup: one path option, no middleware
+## Setup: one path option, no PPR middleware to mount
 
 PPR is a DOCUMENT-level property declared on the page route via the `ppr` path
 option. Serving is **integral to the router** — there is nothing to mount. The
@@ -169,15 +170,86 @@ 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
+
+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:
+
+- preserves client-owned shared layouts by segment id;
+- returns only new or revalidating destination segments;
+- runs DSL loaders fresh with their normal `loading()` streaming behavior;
+- keeps the existing prefetch key, source scope, and in-flight lock unchanged.
+
+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.
+
+### Capture-generation invalidation
+
+If handler or bake-lane code calls `updateTag()` on one of the shell's own tags
+while capture is running, that generation is rejected. Built-in stores report it;
+Rango warns with the shell key and backs capture off instead of rendering the
+same doomed generation on every request. Move a deterministic self-invalidation
+out of render code if you want the shell to persist.
+
+### Opting out per request with `ctx.dynamic()`
+
+Middleware and handlers can call `ctx.dynamic()` to force this request back to
+axis 1. In middleware it runs before the PPR commit point, so the router skips
+shell lookup, HIT serving, and MISS capture for that request. In handlers it is
+too late to prevent a MISS render from already happening, but it still prevents
+the follow-up shell capture.
+
+During `Prerender` + `ppr` build-shell capture, middleware is replayed with
+`ctx.build === true`, `ctx.waitUntil()` inert, and the same `ctx.dynamic()`
+opt-out. Use that for routes where the shell depends on runtime-only auth,
+cookies, or side-effectful SDK calls. A skipped build shell can still be owned
+later by runtime capture when runtime middleware does not call `ctx.dynamic()`.
+
+`ctx.dynamic()` also **re-permits handler header/cookie writes** (issue #735).
+The header doctrine below forbids handler writes on a ppr route because they
+ride MISSes and vanish on HITs — but a `dynamic()` render never HITs, so its
+write is deterministic. Calling `ctx.dynamic()` clears the header latch for the
+rest of the render, so the SAME handler can write its control-flow header
+directly (no middleware relay). Ordering is a contract: call `dynamic()` BEFORE
+the write — a write before it still throws.
+
+```ts
+function catalogPage(ctx) {
+  ctx.dynamic(); // declare live -> refuses capture AND clears the header latch
+  ctx.headers.set("x-rango-sfra-proxy", "catalog");
+  return <Catalog />;
+}
+```
+
 ## Verifying it works
 
-The header exists on DOCUMENT responses only. A bare `curl` (no `Accept`)
-content-negotiates a Flight payload (`text/x-component`) with NO
-`x-rango-shell` header at all — which reads as "PPR is off" but is only the
-wrong request shape:
+The header exists on DOCUMENT responses only. A bare `curl` gets the HTML
+document (Flight is explicit-opt-in via `Accept: text/x-component`), so it
+sees the header directly; only an explicit Flight request shape lacks it:
 
 ```
-curl -s -D - -o /dev/null -H "Accept: text/html" https://app.example.com/products/1 | grep -i x-rango-shell
+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.
@@ -193,6 +265,47 @@ curl -s -D - -o /dev/null -H "Accept: text/html" https://app.example.com/product
 - A ppr-declared route that CANNOT be honored (missing shell store family,
   per-request nonce) serves plain axis 1 with NO header and warns once per
   key — no header + a declared `ppr` means look for that warning.
+- On Cloudflare, `CFCacheStore` WITHOUT a KV namespace has an inert shell
+  family (the shell tier is KV-only): every ppr route stays `MISS` forever.
+  The store warns once per isolate — bind KV
+  (`new CFCacheStore({ ctx, kv: env.CACHE_KV })`) or use another store.
+- 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
+  last capture outcome for a key also rides the next document GET's
+  `Server-Timing` as `ppr-capture;desc="…"`.
+
+### Unit / integration testing (public primitives)
+
+Import from `@rangojs/router/testing` (Vitest) or `@rangojs/router/testing/e2e`
+(Playwright):
+
+| Helper                                            | Use for                                                      |
+| ------------------------------------------------- | ------------------------------------------------------------ |
+| `assertShellStatus(res, "HIT" \| "MISS")`         | Document Response from a real RSC serve / e2e `page.request` |
+| `shellCacheKey(url)`                              | Production store key for `store.getShell` / custom stores    |
+| `MemorySegmentCacheStore` + `getShell`/`putShell` | Custom store contract / tag eviction (no faked HIT)          |
+
+```ts
+import { MemorySegmentCacheStore } from "@rangojs/router/cache";
+import { assertShellStatus, shellCacheKey } from "@rangojs/router/testing";
+
+// Unit: store + key (after a real putShell / capture flush in e2e)
+const store = new MemorySegmentCacheStore();
+const key = shellCacheKey("http://localhost/products/1");
+// ... after production putShell ...
+expect(await store.getShell(key)).not.toBeNull();
+
+// E2E: header on a real document GET
+assertShellStatus({ headers: new Headers(res.headers()) }, "HIT");
+```
+
+**Out of unit scope** (stay e2e): live MISS → background capture → HIT,
+browser resume of holes, build-time producer B. `dispatch` never runs PPR.
+`renderHandler` only exposes `ctx.dynamic()` / `build` for the opt-out path.
+Do not invent a HIT Response in unit tests. Full recipe: `/testing` skill →
+`cache-prerender.md` (PPR shell section).
 
 ## The hole doctrine (encode this in your head)
 
@@ -309,8 +422,21 @@ The lane is decided PER TREE NODE, at the entry that REGISTERS the loaders —
 `loading()` on a CHILD route does not change a parent layout's lane, and
 `loading()` IS valid on layout and parallel entries, not just routes.
 
-Three hard edges (each e2e/unit-pinned):
-
+Four hard edges (each e2e/unit-pinned):
+
+- **Header writes throw (issue #713).** ppr is a document-scoped `cache()`:
+  in any cached scenario ONLY MIDDLEWARE writes response headers. A handler
+  or loader on a ppr route calling `ctx.headers.set()`, `cookies().set()`,
+  `ctx.header()`, `ctx.setTheme()`, or `setStatus()` throws on EVERY render —
+  dev and prod,
+  first render, same guard family as the `cache()` boundary guard. Handlers
+  are replayed on HITs (the write would silently differ between MISS and
+  HIT); loaders are live but settle AFTER the response headers flushed with
+  the shell (dead letters). Move the write into route middleware — it runs
+  on every request, including HITs, and its headers/cookies merge into every
+  response. The one exception: a handler that calls `ctx.dynamic()` FIRST
+  re-permits its own header/cookie write (#735) — a dynamic() render never
+  HITs, so the write is deterministic (see "Opting out per request").
 - **Identity refuses.** `cookies()`/`headers()` inside a bake-lane loader
   throws during capture and the capture REFUSES (deterministic, once-per-key
   warned) — identity can never bake into the shared shell. Give that loader's
@@ -321,7 +447,8 @@ Three hard edges (each e2e/unit-pinned):
   Pitfalls: the session-object bake trap).
 - **A rejecting bake-lane loader refuses.** Error UI never bakes.
 - **Baked containers show CAPTURE-time data** for the shell's lifetime on
-  document GETs (client navigations stay fresh — axis 1). That IS the bake
+  document GETs. Soft navigations may replay the captured handler segments, but
+  DSL loaders and their item/response reads remain fresh. That IS the bake
   lane's meaning; if a value must be fresh on every serve, it belongs on the
   live lane (`loading()`) or in a nested promise.
 
@@ -455,9 +582,10 @@ bake-lane container — or key per variant at the CDN tier.
 
 ## What always stays on axis 1
 
-Non-GET, RSC/partial/action/loader fetches, per-request CSP nonce,
-`streamMode: "allReady"`, redirects, 404s, error renders, routes without `ppr`,
-and any store without the shell family. A stored shell is invalidated when
+Non-GET, non-partial RSC/action/loader fetches, partial requests without an
+eligible captured segment snapshot, per-request CSP nonce, `streamMode:
+"allReady"`, redirects, 404s, error renders, routes without `ppr`, and any store
+without the shell family. A stored shell is invalidated when
 `React.version` changes (postponed state is build-coupled), so deploys
 self-heal via recapture.
 
@@ -505,11 +633,12 @@ path(
 );
 ```
 
-| Field  | Default | Notes                                                                                              |
-| ------ | ------- | -------------------------------------------------------------------------------------------------- |
-| `ttl`  | `300`   | shell freshness window in seconds (`ppr: true` uses the default)                                   |
-| `swr`  | —       | stale window: serve the stale shell + background recapture                                         |
-| `tags` | —       | operational tags UNIONED with the tags the capture render auto-collects — see "Invalidation" below |
+| Field              | Default | Notes                                                                                                                                                     |
+| ------------------ | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ttl`              | `300`   | shell freshness window in seconds (`ppr: true` uses the default)                                                                                          |
+| `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 |
 
 The shell store is always the app-level `createRouter({ cache })` store; the
 default key is `${host}${pathname}${sortedSearch}:shell` (host-scoped so

package/skills/prerender/SKILL.md

@@ -138,6 +138,7 @@ interface BuildContext<TParams> {
     search?: Record<string, unknown>,
   ): string; // URL generation
   passthrough(): PrerenderPassthroughResult; // Skip local artifact (Passthrough routes only)
+  dynamic(): void; // No-op in Prerender/Static handlers; use middleware for PPR shell opt-out
   env: DefaultEnv; // Available when buildEnv is configured in rango() (throws otherwise)
   // NOT available: request, headers, cookies (always throw)
 }
@@ -257,7 +258,7 @@ path("/blog/:slug", BlogPost, { name: "blog.post" }, () => [
 | `cache()`      | Orthogonal -- use on parent layouts and loaders.                                                                                                                                                                                                                         |
 | `layout()`     | Child layouts inside path are pre-rendered. Parent layouts are live.                                                                                                                                                                                                     |
 | `parallel()`   | Parallel slots inside path are pre-rendered.                                                                                                                                                                                                                             |
-| `middleware()` | Skipped during pre-render (no request). Runs at request time for loaders.                                                                                                                                                                                                |
+| `middleware()` | Skipped while collecting build-time Flight payloads (no request). For `Prerender` + `ppr`, producer B replays global and route middleware during build-shell capture with `ctx.build === true`; `ctx.dynamic()` skips that shell. Runs at request time for loaders.      |
 | `loading()`    | Ignored without Passthrough. Works for live fallback with Passthrough.                                                                                                                                                                                                   |
 | `intercept()`  | Pre-rendered at build time. Intercept variant stored under `/i` key alongside main segments. At runtime, the correct variant is served based on `ctx.isIntercept`. `when` config conditions are skipped at build time (all intercepts are pre-rendered unconditionally). |
 
@@ -265,6 +266,48 @@ When Passthrough revalidation is enabled, remember that revalidation is
 still partial: opting a child segment into revalidation does not
 implicitly re-run outer prerender-derived handlers/layouts.
 
+## Prerender + PPR Build Shells
+
+A `Prerender` page may also declare `ppr` on the path option. The build still
+stores the Flight payload first. After that, producer B tries to bake the HTML
+shell for each generated URL so the first document request can be an
+`x-rango-shell: HIT`.
+
+That shell capture is request-shaped enough to run middleware safely:
+
+- global and route middleware run before shell capture;
+- middleware sees `ctx.build === true`;
+- `ctx.waitUntil()` is inert during build;
+- `ctx.dynamic()` skips the baked shell for that URL.
+
+Use `ctx.build` inside middleware to avoid runtime-only side effects during
+build shell capture, or call `ctx.dynamic()` to leave that route to runtime
+PPR. Runtime requests still run the normal middleware chain.
+
+### Freshness of a build shell
+
+A build-baked shell is not on a wall clock the way a pure runtime `ppr` shell is.
+It serves from the first request after a deploy and keeps serving until one of:
+
+- **a redeploy** — the `buildVersion` gate retires every build entry (like a
+  React-version bump); the new build re-bakes;
+- **`updateTag`** on a tag the shell carries — drops it, so the next request
+  MISSes and a runtime capture takes over.
+
+`ppr.ttl` / `swr` are staleness-only here, NOT an expiry: past `ttl` the baked
+entry STILL serves and a runtime recapture is scheduled that upgrades it in place
+(SWR is the upgrade path from build entry → fresher runtime entry). Because the
+`Prerender` handler is evicted from the production bundle, that recapture never
+re-runs the handler — it replays the same build-time segments and only refreshes
+`cache()`-scoped data baked into the shell. **If nothing in the shell is
+`cache()`-backed, `ttl` has nothing to refresh** — reach for `updateTag` (or a
+redeploy) instead of a shorter `ttl`.
+
+`ctx.dynamic()` opts a request off the shell axis ONLY. A `Prerender` route has
+no live handler to fall back to (it was evicted), so a `dynamic()` request still
+serves the build-baked B-segments — fresh loaders in their holes, not a fresh
+handler render. There is no "fully dynamic" render for a prerendered route.
+
 ## Dev Mode
 
 In dev mode there is no production-style prerender build pass and no handler

package/skills/rango/SKILL.md

@@ -219,13 +219,12 @@ without leaving the call site?_ (type-safety), _what re-renders after this
 action?_ (partial rendering). If any answer needs another file, it isn't legible
 yet.
 
-**Reading Rango's own source.** Rango is consumed as raw TypeScript — the
-`exports` map resolves `@rangojs/router` and its subpaths to `./src/*.ts` for
-both types and runtime, so a consuming app bundles Rango straight from source.
-Only the `./vite` plugin entry and the CLI `bin` load from `dist/`. To confirm
-any runtime or type detail against an installed copy, read the resolved source
-under `node_modules/@rangojs/router/src/`, not `dist/` — the runtime does not
-resolve `dist/` outside `./vite`, and it may lag `src/`.
+**Reading Rango's own source.** Runtime exports resolve to `./src/*.ts`, so Vite
+bundles Rango straight from source; type conditions resolve to emitted
+`./dist/types/*.d.ts` so a consumer's standalone `tsc` does not check Rango's
+implementation. The `./vite` plugin and CLI also execute compiled files from
+`dist/`. Read `src/` to confirm runtime behavior and `dist/types/` to inspect
+the exact declarations consumers receive.
 
 ## Skills
 
@@ -296,9 +295,10 @@ Grouped by concern — read when you need to…
 
 **Deployment**:
 
-| Skill     | Description                                                                               |
-| --------- | ----------------------------------------------------------------------------------------- |
-| `/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`                        |
 
 **Testing**:
 

package/skills/response-routes/SKILL.md

@@ -115,9 +115,15 @@ path.md(
 );
 ```
 
-Headers set via `ctx.header()` and cookies set via `cookies().set()` are merged into the
-auto-wrapped Response. If the handler returns a `Response` directly, these are ignored
-(use the Response headers instead).
+Headers set via `ctx.header()` and cookies set via `cookies().set()` are merged
+into both auto-wrapped and handler-returned responses. Headers on the returned
+`Response` are preserved; request-context writes are then merged into the final
+response.
+
+A handler may either return or throw a `Response`. Both are response control
+flow: status/body/headers are preserved, request-context headers and cookies
+merge, and router `onError` is not invoked. Throw ordinary errors (including
+`RouterError`) only when you want the configured error serialization path.
 
 ### Environment Access
 
@@ -206,6 +212,26 @@ path.json(
 );
 ```
 
+`path.json()` describes the response representation. It does not parse the
+incoming request body, so signed webhooks can read the original bytes with
+`await ctx.request.text()` from either `path.json()` or `path.any()`.
+
+### External redirects
+
+Rango blocks unbranded cross-origin redirects at the final response boundary.
+For an OAuth, SSO, or payment callback, validate the registered target and
+return an explicitly external redirect:
+
+```typescript
+path.any("/oauth/decision", async (ctx) => {
+  const redirectUri = await readAndValidateRedirectUri(ctx.request);
+  return redirect(redirectUri, { status: 303, external: true });
+});
+```
+
+`external: true` permits off-origin HTTP(S); it does not permit unsafe schemes.
+Never apply it before validating a user-controlled URL.
+
 ## Client-Side Type Safety
 
 ### Discriminating success vs. error with res.ok
@@ -362,6 +388,17 @@ path.json("/api/users", handler, { name: "users" }, () => [
 ]);
 ```
 
+### `cache()` safety (parity with document cache)
+
+Response-route `cache()` stores whole `Response`s. The serve leaf
+(`serveResponseRouteWithCache`) applies the same safety gates as document cache:
+
+| Gate                   | Behavior                                                                                                                                                                                |
+| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **GET/HEAD only**      | Non-GET/HEAD methods skip the cache (handler runs uncached).                                                                                                                            |
+| **Per-client signals** | A response with `Set-Cookie` or `x-rango-keep-cache` is returned live but **not** stored (MISS + SWR revalidation also skip put).                                                       |
+| **Default key**        | `response:{type}:{cacheKeyBase(host, path, searchParams)}` — sorted search, reserved `_rsc*` / allowlisted `__*` params excluded. Custom `key()` / store `keyGenerator` still override. |
+
 ## Mountable Module Pattern
 
 A self-contained module with RSC pages + JSON APIs, mountable via `include()`:
@@ -490,7 +527,7 @@ best-effort basis.
 1. `path.json()` tags the route at the trie level with a MIME type
 2. `coreRequestHandler()` checks the tag before the RSC pipeline
 3. Tagged routes short-circuit: handler runs, Response is returned directly
-4. JSON routes serialize the return value verbatim (bare) on success; a thrown error becomes an RFC 9457 `problem+json` body (`application/problem+json`)
+4. JSON routes serialize the return value verbatim (bare) on success; a returned or thrown `Response` is control flow; any other thrown error becomes an RFC 9457 `problem+json` body (`application/problem+json`)
 5. Client-side navigation to response routes gets `X-RSC-Reload` header, triggering hard navigation
 6. Response types flow through `_responses` phantom type on `UrlPatterns`, propagated by `include()`
 7. When multiple routes share a URL pattern, the trie merges them for content negotiation (see `/mime-routes`)

package/skills/route/SKILL.md

@@ -487,6 +487,12 @@ beat one giant one. Sizing rules and the numbers behind them:
 [skills/composability](../composability/SKILL.md) → "Sizing async include
 groups (measured)".
 
+`include()` has three name modes: omit `{ name }` for a private local route-name
+scope, pass a non-empty name to namespace children globally, or pass
+`{ name: "" }` to flatten globally unique child names into the parent map. URL
+matching works in all three modes; the option controls name visibility, not
+whether the routes mount.
+
 ## View Transitions
 
 A route can configure its own `transition()` — the wrap goes around the route's component itself (routes are leaves; they have no separate default outlet channel). If the route component renders a `<ParallelOutlet />` directly, that slot remains inside the route's VT subtree, so prefer mounting parallel slots in a layout when combining intercept modals with route-level transitions. See [skills/view-transitions](../view-transitions/SKILL.md) for examples and the wrap-location rules across layouts, routes, and slots.

package/skills/testing/SKILL.md

@@ -97,6 +97,7 @@ Each primitive links to its sub-file (API + recipe + caveats).
 | a real route **handler** `(ctx) => rsc` (params/loaders/vars -> rendered RSC + effects)                                            | RSC unit     | [`renderHandler`](./render-handler.md)                                                        | `@rangojs/router/testing/flight` |
 | navigation, hydration, PE parity, view transitions, real SSR                                                                       | e2e          | [`createRangoE2E` -> `parityDescribe`/`expectParity`](./e2e-parity.md)                        | `@rangojs/router/testing/e2e`    |
 | cache hit/miss/stale, prerender (= a cache hit by design)                                                                          | e2e + signal | [`assertCacheStatus` (header) / `assertCacheDecision` (telemetry sink)](./cache-prerender.md) | `@rangojs/router/testing[/e2e]`  |
+| PPR shell HIT/MISS (`ppr` path option), shell store key / getShell after flush                                                     | e2e + signal | [`assertShellStatus` / `shellCacheKey` + store](./cache-prerender.md#ppr-shell-x-rango-shell) | `@rangojs/router/testing[/e2e]`  |
 | generated route map drift vs runtime                                                                                               | unit (node)  | [`assertGeneratedRoutesMatch`](./reverse-and-types.md)                                        | `@rangojs/router/testing`        |
 | a platform binding (`env.DB` / Durable Object / `env.R2`)                                                                          | unit/integr. | [your own double via `env`](./bindings.md)                                                    | (any primitive's `env` option)   |
 

package/skills/testing/cache-prerender.md

@@ -113,15 +113,56 @@ 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`)
+
+**DSL:** `ppr: true | PartialPrerenderProps` on a page route (see `/ppr`). **Not** the same header as `X-Rango-Cache` — shell is a second render axis.
+
+| Helper                                    | Import                               | Role                                                                                                   |
+| ----------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------ |
+| `assertShellStatus(res, "HIT" \| "MISS")` | `@rangojs/router/testing` or `…/e2e` | Assert `x-rango-shell` on a **real document** Response                                                 |
+| `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                                                                             |
+
+### What unit can prove vs e2e
+
+| Layer    | What you assert             | How                                                                                                                                                                                              |
+| -------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **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`                                                                                                   |
+
+`dispatch` is RSC-free: it never runs shell serve/capture. `renderHandler` only surfaces `ctx.dynamic()` opt-out, not bake/serve.
+
+### Recipe (e2e)
+
+```ts
+import { assertShellStatus, shellCacheKey } from "@rangojs/router/testing/e2e";
+// or from @rangojs/router/testing under Vitest
+
+// Document GET (not Accept: text/x-component):
+const first = await page.request.get(f.url("/products/1"));
+assertShellStatus({ headers: new Headers(first.headers()) }, "MISS");
+// After capture flushes (poll — background putShell):
+const second = await page.request.get(f.url("/products/1"));
+assertShellStatus({ headers: new Headers(second.headers()) }, "HIT");
+
+// Custom store / unit: same key the serve path uses
+const key = shellCacheKey(new URL("http://localhost/products/1"));
+expect(await store.getShell(key)).not.toBeNull();
+```
+
 ## Caveats
 
 - The `X-Rango-Cache` header is emitted ONLY when the gate is on: `createRouter({ debugCacheSignal: true })` or `process.env.RANGO_TEST_SIGNALS === "1"`. Off by default — zero production surface. With the gate off, `assertCacheStatus` throws a clear "header missing" error.
+- `x-rango-shell` is always set on document GETs the serve path considered for a ppr route (no debug gate). Absent header = axis-1 fall-open or non-ppr.
 - v1 is COARSE: route-level, keyed by the route NAME (e.g. `product.detail`), NOT the URL pattern (`/products/:id`); not per-individual-segment. The signal is built from `ctx.routeKey`, so a pattern-shaped key never matches. (`parseCacheHeader` exposes the raw `{ routeKey: status }` map if you need it.)
 - Prerender is indistinguishable from a cache hit by design — no static `.html`/`.rsc` files, the worker handles every request and looks up a stored Flight payload; the browser cannot tell. Do not assert "prerendered" from the DOM. Assert via the signal (`assertCacheStatus(res, seg, "prerendered")`) and run prerender assertions in PRODUCTION mode (the build-time artifacts only exist after `pnpm build`).
-- In a Playwright e2e import the cache-status helpers from the `/e2e` entry — the `@rangojs/router/testing` barrel is Vitest-only (it pulls a build-only virtual that does not resolve in a plain Playwright runner). Zero-prod-surface alternative: the telemetry sink (`createCacheSink`/`filterCacheDecisions`), no header at all. Note: the non-RSC `dispatch()` primitive never emits this header — get the Response from the router's real RSC fetch path.
+- In a Playwright e2e import the cache-status / shell-status helpers from the `/e2e` entry — the `@rangojs/router/testing` barrel is Vitest-only (it pulls a build-only virtual that does not resolve in a plain Playwright runner). Zero-prod-surface alternative for segment cache: the telemetry sink (`createCacheSink`/`filterCacheDecisions`), no header at all. Note: the non-RSC `dispatch()` primitive never emits either header — get the Response from the router's real RSC fetch path.
+- Never stub a shell HIT Response in unit tests to claim the capture path works.
 
 ## See also
 
-- `/caching`, `/prerender`, `/use-cache` — the DSL this tests
+- `/caching`, `/prerender`, `/use-cache`, `/ppr` — the DSL this tests
 - Siblings: [`./e2e-parity.md`](./e2e-parity.md), [`./response-routes.md`](./response-routes.md)
 - Long-form prose: [docs/testing.md](https://github.com/ivogt/vite-rsc/blob/main/packages/rangojs-router/docs/testing.md) — section "Cache, SWR, and prerender"

package/skills/testing/response-routes.md

@@ -39,7 +39,7 @@ function dispatch<TEnv = any>(
 ): Promise<Response>;
 ```
 
-A real `Response`: response-route body, a 308 redirect (`Location`), a 404, or a middleware short-circuit. A `path.json` handler that returns a bare value is serialized verbatim (no envelope); a returned `Response` passes through unchanged; cookies and `ctx.header(...)` surface on the `Response`. `dispatch` accepts your public router type directly (no cast).
+A real `Response`: response-route body, a 308 redirect (`Location`), a 404, or a middleware short-circuit. A `path.json` handler that returns a bare value is serialized verbatim (no envelope); a returned or thrown `Response` uses the same control-flow path; cookies and `ctx.header(...)` surface on the `Response`. `dispatch` accepts your public router type directly (no cast).
 
 ## Recipe
 
@@ -82,7 +82,7 @@ describe("api routes via dispatch", () => {
 
 - Hitting a COMPONENT (RSC) route throws a clear directive error: `dispatch` is for response routes + redirects + 404 + content negotiation, plus the global + route-level middleware guard stack on RESPONSE routes — it never renders React. Use Flight primitives or e2e to exercise component rendering.
 - A COMPONENT route's guard stack cannot run here. Assert it at e2e, or extract the middleware fn and unit-test it with `runMiddleware` (see `./middleware.md`).
-- JSON serialization is bare, applied in `response-route-handler.ts`: a `path.json` handler that returns a value is serialized verbatim (`JSON.stringify(value)`, status 200, `application/json`) — no envelope. Returning a `Response` (e.g. `Response.json(x)`) passes through unchanged. A thrown error yields an RFC 9457 problem+json body `{ title, status, detail, code }` (`application/problem+json`) with the error's status (`RouterError.status`, else 500, or a non-200 `ctx.res.status` already set upstream in the request pipeline); `code` is the `RouterError.code`, else `"INTERNAL"`. The `type` member is omitted this phase. Assert the shape matching what your handler returns.
+- JSON serialization is bare, applied in `response-route-handler.ts`: a `path.json` handler that returns a value is serialized verbatim (`JSON.stringify(value)`, status 200, `application/json`) — no envelope. Returning or throwing a `Response` (e.g. `Response.json(x)`) uses the same control-flow path. Any other thrown error yields an RFC 9457 problem+json body `{ title, status, detail, code }` (`application/problem+json`) with the error's status (`RouterError.status`, else 500, or a non-200 `ctx.res.status` already set upstream in the request pipeline); `code` is the `RouterError.code`, else `"INTERNAL"`. The `type` member is omitted this phase. Assert the shape matching what your handler returns.
 - Setup: needs the preset (alias + virtual stubs) or a Vite-RSC env (see `./setup.md`); a bare router import throws on Vite virtuals.
 - A router using `Prerender()`/`createLoader()`/`Static()` now constructs in a bare test (each assigns a runtime fallback `$$id`). Importing the whole router _file_ may still need the plugin (its page modules pull app deps / `virtual:` modules) — build from a focused include (your API routes) for whole-router dispatch.
 - A `_rsc_partial` request to a response route runs global middleware first (an auth gate can still 401/redirect), then returns `X-RSC-Reload` — route-level middleware is skipped, exactly like production.

package/src/browser/dev-discovery.ts

@@ -0,0 +1,66 @@
+import {
+  DEV_DISCOVERY_QUERY_EVENT,
+  DEV_DISCOVERY_READY_EVENT,
+  isValidDevDiscoveryEpoch,
+} from "../dev-discovery-protocol.js";
+
+export interface DevDiscoveryHot {
+  on(
+    event: typeof DEV_DISCOVERY_READY_EVENT | "vite:ws:connect",
+    listener: (payload: unknown) => void,
+  ): void;
+  send(
+    event: typeof DEV_DISCOVERY_QUERY_EVENT,
+    payload: { epoch: number },
+  ): void;
+}
+
+export interface DevDiscoveryHandshakeOptions {
+  reload?: () => void;
+}
+
+function readEpoch(payload: unknown): number | undefined {
+  if (
+    typeof payload !== "object" ||
+    payload === null ||
+    !("epoch" in payload)
+  ) {
+    return undefined;
+  }
+
+  return isValidDevDiscoveryEpoch(payload.epoch) ? payload.epoch : undefined;
+}
+
+export function startDevDiscoveryHandshake(
+  documentEpoch: unknown,
+  hot: DevDiscoveryHot,
+  options: DevDiscoveryHandshakeOptions = {},
+): void {
+  if (!isValidDevDiscoveryEpoch(documentEpoch)) return;
+  const currentDocumentEpoch = documentEpoch;
+
+  const reload = options.reload ?? (() => window.location.reload());
+  let reloadRequested = false;
+
+  function reloadIfNewer(payload: unknown): void {
+    const readyEpoch = readEpoch(payload);
+    if (
+      reloadRequested ||
+      readyEpoch === undefined ||
+      readyEpoch <= currentDocumentEpoch
+    ) {
+      return;
+    }
+
+    reloadRequested = true;
+    reload();
+  }
+
+  function requestReadyEpoch(): void {
+    hot.send(DEV_DISCOVERY_QUERY_EVENT, { epoch: currentDocumentEpoch });
+  }
+
+  hot.on(DEV_DISCOVERY_READY_EVENT, reloadIfNewer);
+  hot.on("vite:ws:connect", requestReadyEpoch);
+  requestReadyEpoch();
+}

package/src/browser/event-controller.ts

@@ -615,8 +615,22 @@ export function createEventController(
     const arbitration = arb;
     arbitration.inflight++;
 
-    // Track if this action started while others were pending (concurrent)
-    const hadConcurrent = inflightActions.size > 0;
+    // Track if this action started while another was genuinely in-flight.
+    // Completed entries don't count: complete()/fail() ran, so the prior
+    // action's response was fully processed and applied — a request dispatched
+    // after that point is strictly ordered behind the prior action's server
+    // execution, and there is no skipped render or order uncertainty for
+    // consolidation to repair. Completed entries still linger in the map for
+    // the 100ms doSettle window (useAction reads) and, on a slow connection,
+    // while the Flight stream drains its EOF after complete(). Counting them
+    // latched hadAnyConcurrentActions for back-to-back sequential actions,
+    // which made the LAST action classify as consolidation-needed; the
+    // consolidation refetch omits every concurrently-revalidated segment id
+    // from _rsc_segments, so the server re-ran gated loaders as "new-segment"
+    // — bypassing revalidate(({ isAction }) => ...) on a plain GET (#675).
+    const hadConcurrent = [...inflightActions.values()].some(
+      (a) => !a.completed,
+    );
     if (hadConcurrent) {
       hadAnyConcurrentActions = true;
     }

package/src/browser/navigation-client.ts

@@ -28,6 +28,7 @@ import {
   consumePrefetch,
   type DecodedPrefetch,
 } from "./prefetch/cache.js";
+import { cancelAllPrefetches } from "./prefetch/loader.js";
 
 /**
  * Create a navigation client for fetching RSC payloads
@@ -101,6 +102,11 @@ export function createNavigationClient(
         fetchUrl.searchParams.set("_rsc_rid", routerId);
       }
 
+      // If the lazy prefetch runtime has not loaded yet, prevent a deferred
+      // speculative request from starting after this navigation misses the
+      // synchronous cache lookup and begins its own fetch.
+      cancelAllPrefetches(targetUrl);
+
       // Check completed in-memory prefetch cache before making a network
       // request. Try the source-scoped key first (populated when the server
       // tagged the prefetch response as source-sensitive, e.g. intercepts,