@rangojs/router 0.17.0 → 0.18.0

package/skills/testing/serve-shell-request.md

@@ -0,0 +1,188 @@
+# Testing a PPR shell — serveShellRequest
+
+**Layer:** RSC unit (react-server project) · **Import:** `@rangojs/router/testing/flight` · **DSL it tests:** the `ppr` path option (see `/ppr`)
+
+`serveShellRequest(router, url, options?)` serves one GET through your router's production request handler — built as `router.fetch` builds it, with the router's `nonce`, `version`, `cache` config and middleware — and settles every background task the request scheduled before it resolves. So the first request for a `ppr` route is a MISS whose real capture has stored its shell (`putShell` landed), and the next request with the same store is a real HIT: shell read, version gates, the tail replaying the handler output the capture baked (no handler runs), live loaders. A `partial` request is a real client navigation with its `x-rango-ppr-replay` decision. Flight is real.
+
+The one stub is the HTML step (the SSR module), because `react-dom/server` does not load under the react-server condition:
+
+| SSR step           | Under `serveShellRequest`                                                                              |
+| ------------------ | ------------------------------------------------------------------------------------------------------ |
+| `renderHTML`       | passes the Flight stream through: a document body is its Flight payload                                |
+| `captureShellHTML` | stores, as the prelude, the Flight text the capture rendered before it went quiet; `postponed` is null |
+| `resumeShellHTML`  | passes the tail's Flight through: a HIT body is the stored prelude, then the tail's Flight payload     |
+
+So `prelude` is the shell as captured (Flight text, not HTML): a value the shell froze appears there, and a hole (a live loader under `loading()`) does not.
+
+## API
+
+### Options — `ServeShellRequestOptions`
+
+| Field        | Type                                             | Meaning                                                                                                                                                                                                    |
+| ------------ | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `cacheStore` | `SegmentCacheStore`                              | The store for this request, in place of the store your `createRouter({ cache })` config returns. The rest of that config (`enabled`, `searchParams`) still applies. Omit it to use the router's own store. |
+| `env`        | `TEnv`                                           | Bindings, as `router.fetch(request, { env })` passes them. A function `cache` config receives them.                                                                                                        |
+| `headers`    | `HeadersInit`                                    | Request headers (e.g. `cookie`). A document request defaults `accept` to `text/html`.                                                                                                                      |
+| `partial`    | `true \| { from?: string; segments?: string[] }` | Serve the navigation request the browser sends instead of a document GET: from `from` (default the site root) with `segments` mounted (default none).                                                      |
+
+### Returns — `ServeShellRequestResult`
+
+| Field          | Type                                     | Meaning                                                                                                                                                                             |
+| -------------- | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `shellStatus`  | `"HIT" \| "MISS" \| null`                | `x-rango-shell`; null when the serve path did not consider the request (not a `ppr` route, a nonce'd request, a partial request).                                                   |
+| `replayStatus` | `PprReplayStatus \| null`                | `x-rango-ppr-replay` on a partial request: `{ outcome: "HIT", freshness }` or `{ outcome: "BYPASS", reason }`.                                                                      |
+| `prelude`      | `string \| undefined`                    | The prelude a HIT served (the capture's Flight text). `undefined` unless `shellStatus` is `"HIT"`.                                                                                  |
+| `flight`       | `string \| undefined`                    | The Flight payload this request rendered: a HIT's tail, a document render, or a partial response. `undefined` when no Flight rendered (a redirect, a middleware response).          |
+| `key`          | `string`                                 | The shell key the serve path resolved for a document it read (MISS or HIT), request partition included. Otherwise (no `ppr`, a partial request) the URL's key without a partition.  |
+| `readEntry`    | `() => Promise<ShellCacheEntry \| null>` | Reads the document entry under `key` from the request's store (a passive `getShell`). A read: on a store with a shell memo it warms the memo, so call it after the reads you count. |
+| `response`     | `Response`                               | Status and headers. Its body is already read.                                                                                                                                       |
+| `body`         | `string`                                 | The body text.                                                                                                                                                                      |
+
+### `resetShellTestState(): Promise<void>`
+
+A worker keeps some PPR state across requests, and so does the test process across tests: the capture's stampede guard and backoff (a refused capture backs its URL off for later tests too), the capture's and the serve path's once-per-key warnings, the build-shell manifest memo, and `CFCacheStore`'s isolate memos (shells, tag markers, tag hints), which every `CFCacheStore` shares by namespace and URL — a later test's first request can be a HIT from an earlier test's shell. `resetShellTestState()` clears all of it. Call it in `beforeEach`, never while a request is in flight. `VercelCacheStore`'s memos live on the `cache` handle you pass it: a new handle per test starts empty.
+
+## Recipe
+
+```ts
+// test/product-shell.rsc-test.tsx — in the react-server project (./setup.md)
+import { beforeEach, expect, it } from "vitest";
+import { createRouter, updateTag, urls } from "@rangojs/router";
+import { MemorySegmentCacheStore } from "@rangojs/router/cache";
+import { runInRequestContext } from "@rangojs/router/testing";
+import {
+  resetShellTestState,
+  serveShellRequest,
+} from "@rangojs/router/testing/flight";
+import { ProductPage } from "../src/pages/product"; // renders the product name
+import { StockLoader } from "../src/loaders/stock"; // live stock count
+
+const router = createRouter().routes(
+  urls(({ path, loader, loading }) => [
+    path("/product/:id", ProductPage, { name: "product", ppr: { tags: ["catalog"] } }, () => [
+      loader(StockLoader),
+      loading(<p>Checking stock…</p>),
+    ]),
+  ]),
+);
+
+beforeEach(() => resetShellTestState());
+
+it("serves the captured shell and fills the stock hole live", async () => {
+  const cacheStore = new MemorySegmentCacheStore();
+
+  const miss = await serveShellRequest(router, "/product/1", { cacheStore });
+  expect(miss.shellStatus).toBe("MISS"); // a normal render; the capture stored the shell
+
+  const hit = await serveShellRequest(router, "/product/1", { cacheStore });
+  expect(hit.shellStatus).toBe("HIT");
+  expect(hit.prelude).toContain("Widget"); // frozen at capture
+  expect(hit.prelude).not.toContain("in stock"); // the hole
+  expect(hit.flight).toContain("in stock"); // rendered by this request
+
+  await runInRequestContext(() => updateTag("catalog"), { cacheStore });
+  const recapture = await serveShellRequest(router, "/product/1", { cacheStore });
+  expect(recapture.shellStatus).toBe("MISS");
+});
+
+it("replays the captured segments on a client navigation", async () => {
+  const cacheStore = new MemorySegmentCacheStore();
+  await serveShellRequest(router, "/product/2", { cacheStore });
+
+  const nav = await serveShellRequest(router, "/product/2", {
+    cacheStore,
+    partial: { from: "/" },
+  });
+  expect(nav.replayStatus).toEqual({ outcome: "HIT", freshness: "fresh" });
+});
+```
+
+A store built per request from a function `cache` config gets the request's execution context (`ctx`), so its own `waitUntil` writes (`CFCacheStore({ ctx })`) settle with the call. A store built outside the request with its own `waitUntil` (`VercelCacheStore`'s option) is not settled by the call. For `CFCacheStore`, stub the `caches` global and pass a KV double in `env`; for `VercelCacheStore`, pass a `cache` double. A store's shell memo then behaves as in production (count your double's reads across two HITs).
+
+## A HIT runs no handler
+
+A HIT replays what the capture's handlers produced — their elements, the promises they passed or pushed, their handle values — and runs only middleware and loaders. Count runs to pin it:
+
+```ts
+let pageRuns = 0;
+// the page handler does `pageRuns += 1` and renders `page-run-${pageRuns}`
+
+it("a HIT runs no handler", async () => {
+  const cacheStore = new MemorySegmentCacheStore();
+  await serveShellRequest(router, "/product/3", { cacheStore }); // MISS + capture
+  const baked = pageRuns; // the capture's run
+
+  const hit = await serveShellRequest(router, "/product/3", { cacheStore });
+  expect(hit.shellStatus).toBe("HIT");
+  expect(pageRuns).toBe(baked);
+  expect(hit.flight).toContain(`page-run-${baked}`);
+});
+```
+
+## Request-partitioned shells
+
+A route whose `cache()` record is partitioned by the request (`cache({ key })`, or the store's `keyGenerator`) has a shell per partition. Serve each partition with the request headers or cookies its key reads; the result's `key` is the key the serve path resolved, partition included, and `readEntry()` reads it:
+
+```ts
+// cache({ ttl: 300, key: (ctx) => `tier:${ctx.request.headers.get("x-tier")}` }, () => [
+//   path("/pricing", PricingPage, { ppr: true }),
+// ])
+const tier = (name: string) => ({ cacheStore, headers: { "x-tier": name } });
+
+await serveShellRequest(router, "/pricing", tier("gold")); // MISS + capture
+const silver = await serveShellRequest(router, "/pricing", tier("silver"));
+expect(silver.shellStatus).toBe("MISS"); // its own capture, never gold's shell
+const gold = await serveShellRequest(router, "/pricing", tier("gold"));
+expect(gold.shellStatus).toBe("HIT");
+expect(gold.key).toBe(shellCacheKey("/pricing", undefined, "tier:gold"));
+expect(await gold.readEntry()).not.toBeNull();
+```
+
+Under nested keyed `cache()` boundaries the partition is their `key()` results composed, outermost first (see `/caching`, "Keys nest"). Pass them to `shellCacheKey` as an array and it composes them the same way:
+
+```ts
+// cache({ key: tierKey }, () => [
+//   layout(TierLayout, () => [
+//     cache({ key: (ctx) => `v:${variantOf(ctx)}` }, () => [path("/plans", PlansPage, { ppr: true })]),
+//   ]),
+// ])
+expect(result.key).toBe(
+  shellCacheKey("/plans", undefined, ["tier:gold", "v:a"]),
+);
+```
+
+A partial request has no HTML step, so its `key` is the URL's key without a partition: read a partitioned route's entry from a document request's result.
+
+## Handles and loader data
+
+The result carries no structured `handles` map (unlike `renderHandler`): a handle value and loader data ride the payload, so you assert them as text in `prelude` and `flight`. A value the handler pushed is in the prelude and in every HIT's tail; a live loader's data is only in the tail. No public helper decodes a payload string into values: `normalizeFlight` and the `flightMatchers` (`toMatchFlight`) work on the text too.
+
+```ts
+// The handler pushed ctx.use(Meta)({ title: "Widget - Shop" })
+expect(hit.prelude).toContain('"title":"Widget - Shop"');
+expect(hit.flight).toContain('"title":"Widget - Shop"');
+```
+
+## Caveats
+
+What the HTML stub cannot reproduce, so keep it in e2e:
+
+- The prelude's `<body` sanity gate. A route whose production capture refuses for a root postpone (a live loader read with no `loading()` or `<Suspense>` above it) stores a shell here.
+- The capture deadline. `ppr.captureTimeout` (default 15s) bounds the whole capture: the match, the handler output, then the shell render. A capture that runs out of it stores nothing and is not retried in place, here as in production, so the call waits one deadline: give such a route a short `captureTimeout` in a test (Vitest's default test timeout is 5s). One difference: when the handler output settled but the shell render does not go quiet in what is left, the stub returns no shell, while production goes on to its abort and can still store the prelude rendered by then.
+- SSR render errors. In production a fizz render error during the capture refuses it (#915). The stub renders no HTML and reports none, so a shell whose client component throws during SSR is stored here. A server component that throws still refuses the capture, as in production.
+- Fizz resume of the holes, bootstrap scripts, nonce injection, and browser resume.
+
+Other caveats:
+
+- A HIT's tail carries replayed segments as Flight fragments inside JSON strings, so their quotes are escaped (`\"`). Match plain text, or unescape before matching JSON-shaped text.
+- Call `resetShellTestState()` in `beforeEach` (see above). Without it, a URL a previous test left backed off, or a shell memoized by another `CFCacheStore`, changes what the next test sees.
+- `readEntry()` reads the document entry under `key`. A partial request that finds no entry captures a navigation-only entry, which is stored apart from it.
+- `updateTag()` needs a request context with the store: call it through `runInRequestContext(fn, { cacheStore })` or your app's own endpoint (`dispatch`). A store refuses a capture that starts in the invalidation's millisecond (the invalidation wins) and backs the key off; `serveShellRequest` starts each request in a later millisecond than the call, so an invalidation made before the call cannot collide with it.
+- GET only. Server actions are not served; test their effects with `runInRequestContext`.
+- Same setup as every Flight test: the react-server condition and `rangoTestAliases()` (see [`./setup.md`](./setup.md)).
+
+## See also
+
+- `/ppr` — the DSL this tests; `/caching` — stores and tags
+- Siblings: [`./cache-prerender.md`](./cache-prerender.md) (the shell-status helpers and the e2e recipe), [`./render-handler.md`](./render-handler.md)
+- Long-form prose: [docs/testing.md](https://github.com/rangojs/rango/blob/main/packages/rangojs-router/docs/testing.md) — section "serveShellRequest — a real PPR capture and HIT"

package/skills/theme/SKILL.md

@@ -86,10 +86,13 @@ from `@rangojs/router/theme` in `<head>` instead. It takes the resolved config
 are rejected with a console warning. Both are typed optional because they only
 exist when `theme` is configured.
 
+`ctx.theme` is the visitor's theme cookie, so a handler reads it only on a
+route whose output is rendered per request:
+
 ```typescript
 import type { Middleware } from "@rangojs/router";
 
-// In a handler
+// In a handler on a route without ppr or cache()
 path("/settings", (ctx) => {
   const currentTheme = ctx.theme; // "light" | "dark" | "system" | undefined
   return <SettingsPage theme={currentTheme} />;
@@ -105,9 +108,41 @@ export const themeFromQuery: Middleware = async (ctx, next) => {
 };
 ```
 
-Loaders do not get `ctx.theme` or `ctx.setTheme`. A loader that needs the
-theme reads the cookie directly (loaders run fresh on every request, so the
-read is safe):
+### On `ppr` and `cache()` routes
+
+A `ppr` shell and a `cache()` entry are shared by every visitor, so a handler
+there must not read the visitor's theme. `ctx.theme` (handler and middleware)
+and `getRequestContext().theme` are guarded like `cookies()`:
+
+| Where the theme is read                                    | What happens                                                                                          |
+| ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| a handler on a `ppr` route                                 | The shell capture is refused (warned once per URL); every request stays a MISS                        |
+| inside a `cache()` boundary                                | Throws on a cache miss, like `cookies()`                                                              |
+| inside a `"use cache"` function (handler or middleware)    | Throws; read it outside and pass it in as an argument                                                 |
+| after `ctx.dynamic()` on `ppr`                             | Allowed: that render is never captured                                                                |
+| middleware `ctx.set()` of the theme, read by a handler     | Not guarded: the first visitor's theme bakes into the shell or `cache()` entry, like a session object |
+| a route with no `ppr` or `cache()` above it, or middleware | Allowed: rendered per request                                                                         |
+| a loader with its own `cache()` and no `key()`             | The miss fails and stores nothing (#972), like a `cookies()` read there; key the theme                |
+
+The theme getters are read-only and non-enumerable: `{ ...ctx }` and
+`Object.assign({}, ctx)` do not carry `theme`, and assigning it throws.
+
+`ctx.setTheme()` throws in a handler on these routes too, like any response
+write there; call it from middleware.
+
+Read the theme where it is per request instead:
+
+- `useTheme()` in a client component. The `<html>` class is right before
+  paint (the theme script sets it). On a `ppr` HIT the shell carries the
+  no-cookie default (`defaultTheme`), whoever captured it: a visitor with no
+  stored theme sees the default, and one with a stored theme sees it after
+  hydration.
+- A live loader (no `ssr: false`). Loaders do not get `ctx.theme` or
+  `ctx.setTheme`; read the cookie directly. A live loader runs on every
+  request, HITs included, and on a `ppr` route needs `loading()` or an inline
+  `<Suspense>` above its reader. A bake-lane loader (`ssr: false`) runs at
+  capture, where this `cookies()` read refuses the capture, and so does a
+  loader a handler awaits with `ctx.use()`.
 
 ```typescript
 import { cookies, createLoader } from "@rangojs/router";
@@ -118,6 +153,19 @@ export const ThemedLoader = createLoader(async () => {
 });
 ```
 
+If you bind it with its own `cache()`, the entry is shared across users, so the
+miss fails unless it has a `key()`. Any `key()` switches that check off, so
+make it include the theme:
+
+```typescript
+loader(ThemedLoader, () => [
+  cache({
+    ttl: 300,
+    key: () => `themed:${cookies().get("theme")?.value ?? "system"}`,
+  }),
+]);
+```
+
 ## Client
 
 ```tsx

package/skills/typesafety/env-and-bindings.md

@@ -103,7 +103,8 @@ interface PaginationData {
 }
 export const Pagination = createVar<PaginationData>();
 
-// Non-cacheable var — reading inside cache() or "use cache" throws at runtime
+// Non-cacheable var — reading inside cache(), "use cache", or a PPR shell
+// capture throws at runtime
 interface SessionData {
   userId: string;
 }
@@ -115,7 +116,14 @@ export const Session = createVar<SessionData>({ cache: false });
 Write-level escalation is also supported: `ctx.set(Var, value, { cache: false })`
 marks a specific write as non-cacheable even if the var itself is cacheable.
 "Least cacheable wins" — if either says `cache: false`, the value throws on
-read inside `cache()` or `"use cache"`.
+read inside `cache()` or `"use cache"`. On a `ppr` route the read also throws
+anywhere the shell capture waits for it (a handler, a promise it passes or
+pushes, an async server component, an `ssr: false` loader, a loader a handler
+awaits) and refuses the capture: the route keeps rendering without a shell,
+and a warning fires once per key. A loader without `ssr: false` that no
+handler awaits may read it, unless it is bound with its own `cache()` and no
+`key()`: that miss fails, since the entry is shared (`/loader` → "Cache
+Key").
 
 ### Producer (handler, layout, or middleware)
 

package/skills/use-cache/SKILL.md

@@ -142,6 +142,11 @@ Different functions always produce different cache keys, even for the same route
 This is important for intercepted routes -- the path handler and intercept handler
 each have their own `functionId` and therefore their own cache entries.
 
+The key is only what the function declares: its id and arguments. A call made
+inside a route `cache()` with a `key()` does not inherit that key, so a value
+the route partitions by (a tier header, a session) must be passed in as an
+argument. The same holds for a loader's own `cache()` (`/loader` → "Cache Key").
+
 ### Route context is folded into the key
 
 The tainted `ctx` object is excluded from arg serialization (see below), but
@@ -261,7 +266,10 @@ into the shared cache entry like any other computed data. (`cookies()` and
 `headers()` still throw there: that guard follows the cached body's whole
 async chain, loaders included.) Same rule across `cache()` and the PPR shell:
 handler/cached-scope consumption = baked copy, client-side `useLoader` = live
-(the consumption-lane rule, `/rango` → Invariants).
+(the consumption-lane rule, `/rango` → Invariants). The PPR shell is stricter
+about the loader's own reads: during a capture, `cookies()`, `headers()`, and a
+`{ cache: false }` variable read inside a handler-consumed loader refuse the
+capture.
 
 ### Side-Effect Guards
 
@@ -504,20 +512,31 @@ built into the server bundle, see `/prerender`.)
 Entries are tagged by the profile's `tags` plus any runtime `cacheTag(...tags)`
 calls in the function body. `cacheTag` has two forms: inside a `"use cache"`
 function it tags that entry; called during a request render outside
-`"use cache"` it tags the request's `ppr` shell / document-cache entry instead
-(see `/caching` → "Tag-Based Invalidation"). All built-in stores
-(`MemorySegmentCacheStore`, `CFCacheStore`, `VercelCacheStore`) index by tag.
-Invalidate on demand with `updateTag(...tags)` (awaitable,
-read-your-own-writes; for server actions) or `revalidateTag(...tags)`
-(background, non-blocking; for route handlers/webhooks). Both hard-purge; the
-difference is awaitability, not stale-serving. For `CFCacheStore`, cross-colo
-invalidation needs a `kv` namespace (markers live in that same namespace) or
-`tagPurge`. The separate `revalidate()` export is the client-update axis (which
-segments re-render on a navigation or action), not a cache bust.
-
-A `"use cache"` entry's tags do not propagate to an enclosing `cache()` segment
-entry: invalidating them re-runs the function on the next miss of the outer
-boundary, not before (see `/cache-guide` → "Nesting rule").
+`"use cache"` it tags what the render stores: the enclosing route `cache()`
+entry, a cached loader's own entry when called in its body, and the `ppr`
+shell or document-cache entry built from them (on a `ppr` route, only when
+shell material calls it). See `/caching` → "Tag-Based Invalidation". All
+built-in stores (`MemorySegmentCacheStore`, `CFCacheStore`,
+`VercelCacheStore`) index by tag. Invalidate on demand with
+`updateTag(...tags)` (awaitable; for server actions) or
+`revalidateTag(...tags)` (background, non-blocking; for route
+handlers/webhooks). Both evict rather than mark stale, and the request that
+calls either reads its own writes; `updateTag()` also waits for the durable
+write. PPR shell reads on `CFCacheStore`/`VercelCacheStore` go through
+per-isolate memos, which the invalidating user skips via the fresh-reads
+cookie. For `CFCacheStore`, cross-colo invalidation needs a `kv` namespace
+(markers live in that same namespace) or `tagPurge`. The separate
+`revalidate()` export is the client-update control (which segments re-render
+on a navigation or action), not a cache bust.
+
+A route `cache()` entry stores the tags of the `"use cache"` reads inside it,
+so `updateTag()` of one evicts the enclosing entry and any `ppr` shell or
+document built from it. A loader's own `cache()` entry does the same for the
+reads in its body. The exception is a `"use cache"` function called inside
+another `"use cache"` function: its tags do not reach the enclosing entry, so
+invalidating one of them neither evicts the outer entry nor keeps this request
+from joining or storing an outer call that started before the invalidation
+([#980](https://github.com/rangojs/rango/issues/980)).
 
 ## Interaction with Other Caching
 
@@ -531,7 +550,11 @@ boundary, not before (see `/cache-guide` → "Nesting rule").
 | `Prerender()`    | Route segment tree | Build-time | Pre-render known params, optional live fallback       |
 
 Inside a `ppr` shell, a `"use cache"` value that renders as shell material is
-pinned at capture time for the life of that shell (see `/ppr` → Pitfalls).
+pinned at capture time for the life of that shell (see `/ppr` → Pitfalls). A
+hole's own read (in a loader without `ssr: false` under `loading()` or an
+inline `<Suspense>`) returns the current entry, not the shell's copy, unless a
+loader the capture ran (an `ssr: false` loader, or one a handler awaits) read
+the same entry.
 
 ## Dev Mode and tests
 

package/skills/vercel/SKILL.md

@@ -89,12 +89,24 @@ import { getCache, waitUntil } from "@vercel/functions";
 
 const defaults = { ttl: 60, swr: 300 };
 const memoryStore = new MemorySegmentCacheStore({ defaults });
+// One handle per process: getCache() resolves the platform cache on every
+// call, and VercelCacheStore keeps its PPR shell and tag-marker memos per
+// handle. After updateTag(), the same process misses at once, the rest of the
+// region once its marker memo refreshes (memo.markerMaxStaleMs, default 2000),
+// and the mutating user at once (the fresh-reads cookie skips the memos).
+// Another region serves a memoized shell until memo.shellMs (default 2000)
+// passes, since the tag markers are regional and only expireTag is global. A
+// platform expireTag issued outside rango writes no marker, so every memo
+// serves the shell until its window passes.
+const runtimeCache = process.env.VERCEL
+  ? getCache({ namespace: process.env.VERCEL_DEPLOYMENT_ID })
+  : undefined;
 
 function resolveCache() {
-  if (process.env.VERCEL) {
+  if (runtimeCache) {
     return {
       store: new VercelCacheStore({
-        cache: getCache({ namespace: process.env.VERCEL_DEPLOYMENT_ID }),
+        cache: runtimeCache,
         waitUntil,
         defaults,
       }),

package/skills/view-transitions/SKILL.md

@@ -245,7 +245,7 @@ interface TransitionConfig {
 Timing follows the route's rendering contract:
 
 - On an ordinary route it runs after the route handler during fresh resolution, so `get()` can read handler- and middleware-set context. Cache/prerender hits replay the stored decision.
-- On a `ppr` route it is automatically hoisted before route handlers and runs on every match, including runtime-cache, prerender, document-shell, and partial-navigation replay. It can read URL/params/action metadata, `env`, and middleware-set context, but not values set by route handlers. This is what keeps the handler-free PPR fast path available without a second API.
+- On a `ppr` route it is automatically hoisted before route handlers and runs on every match, including runtime-cache, prerender, document-shell, and partial-navigation replay. It can read URL/params/action metadata, `env`, and middleware-set context, but not values set by route handlers, because a shell HIT never runs a handler.
 
 Its context mirrors the `revalidate()` predicate args — the same navigation/action metadata — plus `get`/`env` for request-context reads:
 

package/src/browser/cookie-name.ts

@@ -14,6 +14,29 @@
 /** Default prefix when `stateCookiePrefix` is unset or empty after sanitization. */
 export const DEFAULT_STATE_COOKIE_PREFIX = "rango-state";
 
+/**
+ * The fresh-reads cookie: the state cookie PREFIX plus this suffix
+ * (`rango-state-fresh` by default). A response whose request ran
+ * updateTag()/revalidateTag() sets it (HttpOnly, SameSite=Lax, Path=/,
+ * Max-Age = the stores' longest memo staleness), and the same user's requests
+ * carrying it skip the stores' isolate memos (src/cache/isolate-tag-memo.ts).
+ * Keyed by prefix, not by router, so a mutation through one router also
+ * reaches the memos another router on the host reads (they often share a
+ * store); a router with its own `stateCookiePrefix` gets its own cookie.
+ */
+const FRESH_READS_COOKIE_SUFFIX = "-fresh";
+
+/**
+ * The fresh-reads cookie name for a router's resolved state cookie name
+ * (`{prefix}_{routerId}`; the prefix never contains `_`, see
+ * router/state-cookie-name.ts).
+ */
+export function freshReadsCookieName(stateCookieName: string): string {
+  const cut = stateCookieName.indexOf("_");
+  const prefix = cut < 0 ? stateCookieName : stateCookieName.slice(0, cut);
+  return `${prefix}${FRESH_READS_COOKIE_SUFFIX}`;
+}
+
 /** Internal response header carrying the keepClientCache() directive. */
 export const KEEP_CACHE_HEADER = "x-rango-keep-cache";
 

package/src/browser/history-state.ts

@@ -82,6 +82,29 @@ export function pushHistoryWithIdx(
   }
 }
 
+/**
+ * The forced-MISS reload marker (`SHELL_MISS_PARAM` in rsc/shell-serve.ts,
+ * which the browser bundle must not import): a degraded PPR shell HIT
+ * reloads the page with it, and the server renders a marked request like a
+ * cache miss.
+ */
+export const SHELL_MISS_MARKER: string = "_rsc_shell";
+
+/**
+ * Drop the forced-MISS marker from the address bar at boot, keeping the
+ * history entry's state (initBrowserApp calls it before any location read).
+ * Left in place, a refresh or a shared link would stay off the shell and the
+ * app's search params would carry it. The server strips the same marker from
+ * the request before rendering (shell-serve.ts withoutShellMissMarker), so
+ * the page was rendered for the clean URL and the hydrating client agrees.
+ */
+export function stripShellMissMarker(): void {
+  const url = new URL(window.location.href);
+  if (!url.searchParams.has(SHELL_MISS_MARKER)) return;
+  url.searchParams.delete(SHELL_MISS_MARKER);
+  window.history.replaceState(window.history.state, "", url.href);
+}
+
 /**
  * Merge server-set location state into the current history entry.
  * Replaces the current history state and dispatches notification event

package/src/browser/rsc-router.tsx

@@ -39,6 +39,7 @@ import {
 } from "./intercept-utils.js";
 import { createAppShellRef } from "./app-shell.js";
 import { bootLog, IS_BROWSER_DEBUG } from "./logging.js";
+import { stripShellMissMarker } from "./history-state.js";
 import { setActiveInterceptTargets } from "../client-urls/navigation.js";
 
 // Vite HMR types are provided by vite/client
@@ -169,6 +170,10 @@ export async function initBrowserApp(
   } = options;
 
   bootLog("initBrowserApp start");
+  // Before any location read (the history key, the navigation store, the
+  // event controller): the server rendered the marked request for the clean
+  // URL, so the client starts from the same one and hydration agrees.
+  stripShellMissMarker();
   bootLog("flight decode: awaiting initial payload from document stream");
   const initialPayload =
     await deps.createFromReadableStream<RscPayload>(rscStream);

package/src/cache/cache-key-utils.ts

@@ -2,8 +2,8 @@
  * Shared Cache Key Utilities
  *
  * Deterministic normalization of search params and route params
- * for cache key generation. Used by cache-runtime, cache-scope,
- * document-cache, and loader-cache.
+ * for cache key generation, and the composition of nested cache() keys.
+ * Used by cache-runtime, cache-scope, document-cache, and loader-cache.
  */
 
 import { encodeKV } from "../encode-kv.js";
@@ -95,3 +95,23 @@ export function cacheKeyBase(
   if (searchStr) key += `?${searchStr}`;
   return key;
 }
+
+/**
+ * The record key, or shell partition, of nested keyed cache() scopes (#970)
+ * from its parts, outermost first: the chain's `key()` results and, for an
+ * inner scope without its own `key()`, that scope's default key
+ * (CacheScope.resolveKeyFrom). One part is returned raw, so a single keyed
+ * scope keeps its key byte for byte. Two or more are joined by `|`, each
+ * URI-encoded (like partitionShellKey, rsc/shell-capture-constants.ts): an
+ * encoded part holds no `|`, so every tuple maps to its own key, of any
+ * depth. Raw, `("a|b", "c")` and `("a", "b|c")` named one record. A composed
+ * key holds no `:` either, so a single raw result with one (a prefixed
+ * `tier:...`, a `doc:` default key) never equals it; an unprefixed raw result
+ * can. Shared with the testing helper `shellCacheKey`, which composes a
+ * nested partition the same way.
+ */
+export function composeCacheKeys(parts: readonly string[]): string {
+  return parts.length === 1
+    ? parts[0]
+    : parts.map((part) => encodeURIComponent(part)).join("|");
+}

package/src/cache/cache-policy.ts

@@ -83,6 +83,28 @@ export function resolveSwrWindow(
   return 0;
 }
 
+/**
+ * Minimum age (ms) of a stale PPR shell before a HIT schedules its recapture.
+ * A shell capped to a route cache() record inside its swr window is stale
+ * from the start (rsc/shell-capture.ts capShellWindow), so without a floor
+ * every HIT of it recaptured, and a capture's store write is one KV write per
+ * key: Cloudflare KV accepts one per second per key. Inside the floor the
+ * stale shell is still served. Per isolate: each isolate's stale HIT past the
+ * floor can schedule one (stampede-guarded per isolate).
+ */
+export const SHELL_MIN_RECAPTURE_INTERVAL_MS = 1_000;
+
+/**
+ * Whether a stale shell HIT schedules its recapture (see the floor above).
+ * Fails open: an entry without a numeric `createdAt` recaptures.
+ */
+export function staleShellRecaptureDue(
+  entry: { readonly createdAt?: number },
+  now: number,
+): boolean {
+  return !(now - (entry.createdAt as number) < SHELL_MIN_RECAPTURE_INTERVAL_MS);
+}
+
 /**
  * Compute staleAt and expiresAt timestamps from TTL and SWR window.
  *