@rangojs/router 0.23.0 → 0.24.0

package/skills/loader/SKILL.md

@@ -285,7 +285,9 @@ See `/route` for the full handler-context contract (shared with loaders) and
 
 - `ctx.params` — merged route params + explicit loader params. For fetchable
   loaders called with `load(Loader, { params: { ... } })`, explicit params
-  override route-matched params.
+  override route-matched params. Explicit params are string values; a request
+  with another value or a `__proto__`, `constructor` or `prototype` key is
+  rejected (400, `load()` fails with `Invalid loader params`).
 - `ctx.routeParams` — server-trusted route params from URL pattern matching.
   Cannot be overridden by client-provided params.
 
@@ -333,6 +335,10 @@ path("/product/:slug", ProductPage, { name: "product" }, () => [
 ]);
 ```
 
+In a `clientUrls()` group the same `loader(Def, () => [revalidate(fn)])` form
+runs on the server with these arguments; the build moves the predicate out of
+the `"use client"` module (`/client-urls` → "Revalidation runs on the server").
+
 ### `revalidate()` return shapes
 
 > **Scope: `revalidate()` is a partial-render concern, not a cache concern.**

package/skills/middleware/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: middleware
-description: Define global (router.use) and route (middleware()) middleware in @rangojs/router — auth gates, logging, response headers, context variables, redirects. Use when gating routes behind auth checks, logging requests, setting headers or ctx variables before a handler runs, or deciding whether middleware wraps server actions.
+description: Define global (router.use) and route (middleware()) middleware in @rangojs/router — auth gates, logging, response headers, context variables, redirects, rewrites (throw rewrite() renders another route at the same URL). Use when gating routes behind auth checks, logging requests, setting headers or ctx variables before a handler runs, showing a maintenance page at the visitor's URL, or deciding whether middleware wraps server actions.
 argument-hint: [middleware-name]
 ---
 
@@ -19,7 +19,7 @@ There are two levels of middleware with different execution scopes:
 
 ### Global middleware (`router.use()`)
 
-Registered on the router instance. Wraps the **entire request**, including server actions, rendering, and progressive enhancement (PE) re-renders.
+Registered on the router instance. Wraps the **entire request**, including server actions, rendering, and progressive enhancement (PE) re-renders. A request a middleware rewrites (`throw rewrite()`, below) runs the chain again for the target: once per pass.
 
 ```typescript
 const router = createRouter<AppEnv>({})
@@ -257,6 +257,8 @@ export const myMiddleware: Middleware = async (ctx, next) => {
   ctx.headers; // response Headers (stub before next(), the real response after)
   ctx.setLocationState(FlashMessage({ text: "Saved" })); // history state for the client
   ctx.reverse("home"); // URL for a global route name (no ".name", no param auto-fill)
+  ctx.rewrittenFrom; // the visitor's URL when this request was rewritten, else undefined
+  ctx.isRewrite(error); // true for a thrown rewrite() (rethrow it from a try/catch)
 
   // Opt the current request out of PPR shell lookup/capture.
   ctx.dynamic();
@@ -428,6 +430,185 @@ Read the flash on the target page with `useLocationState(FlashMessage)`. The `{
 
 A redirect is followed on a link click, `router.push()`, and Back/Forward to an entry the client has to fetch. On Back/Forward the redirect replaces the history entry it was triggered from: Back from the target lands on the entry before the redirecting one, not on the redirecting one again. The client follows at most 20 redirects in one navigation; a loop (two pages redirecting to each other) stops there with the error boundary and a `[rango] Server redirect loop` console error.
 
+## Rewrite: another route at the same URL
+
+`throw rewrite(target)` renders another route while the address bar keeps the
+visitor's URL: a maintenance or lock page, a deploy migration, a URL override,
+an A/B or geo split. A redirect changes the URL; a rewrite does not.
+
+```typescript
+import { getRequestContext, rewrite } from "@rangojs/router";
+import type { Middleware } from "@rangojs/router";
+
+export const maintenance: Middleware = async (ctx, next) => {
+  if (!locked || ctx.pathname === "/maintenance") return next();
+  // Mutations get a Response: a rewrite cannot answer a server action or a form post.
+  if (ctx.request.method !== "GET") {
+    return new Response("Maintenance", {
+      status: 503,
+      headers: { "Retry-After": "600" },
+    });
+  }
+  ctx.set(Lock, { until });
+  throw rewrite("maintenance");
+};
+
+// urls.tsx — the target sets its own status
+path("/maintenance", MaintenancePage, { name: "maintenance" }, () => [
+  middleware(async (ctx, next) => {
+    getRequestContext().setStatus(503);
+    ctx.header("Retry-After", "600");
+    await next();
+  }),
+]);
+```
+
+Targets, like `ctx.reverse` with a path form:
+
+```typescript
+throw rewrite("/maintenance"); // a path (basename-prefixed like redirect())
+throw rewrite("/maintenance?from=shop"); // a path with search
+throw rewrite("maintenance"); // a global route name without params
+throw rewrite("product", { slug }); // with params
+throw rewrite("product", { slug }, { tab: "reviews" }); // and search
+```
+
+**How it runs.** The throw unwinds the request to the router, which runs it
+again as the target, from the top, as a direct visit would: global middleware
+matched on the target's path (a `.use("/admin/*", guard)` or an inline
+`ctx.pathname` check decides on the rendered route), the target's route
+middleware, its render. Code after `await next()` in the pass that rewrote
+never runs, and global middleware runs once per pass.
+
+**Never skip a guard on a rewritten pass.** Authorization, auth and
+rate-limit checks run on every pass, as written: the target's guards
+deciding on the rendered route is what keeps a rewrite from becoming a way
+around them. `if (!ctx.rewrittenFrom)` is only for side effects you want
+once per request, such as a counter or a log line:
+
+```typescript
+export const countVisit: Middleware = async (ctx, next) => {
+  if (!ctx.rewrittenFrom) visits.increment(); // once per request
+  return next();
+};
+```
+
+**Throw it before `await next()`.** Once your `next()` ran the route, the
+page has rendered: a `throw rewrite()` after it (a "rewrite on 404" after
+`const res = await next()`) is an error, "throw rewrite() before await
+next()". Decide before calling `next()`. A rewrite thrown further down
+passes through your `await next()` as usual, and in a `catch` around it you
+may throw another rewrite in its place; after any other failure of `next()`
+(the route may have rendered before it failed) a rewrite is an error too.
+
+**Same request context.** Values you `ctx.set()` before the throw are
+readable in the target's middleware, handlers and loaders; cookies, headers
+and the status you set stay on the response; location state, theme and
+`ctx.dynamic()` carry over. The request, URLs, params and route name are the
+target's.
+
+**Old and new URL.** `ctx.url`, `ctx.pathname` and `ctx.searchParams` are
+the target's; `ctx.rewrittenFrom` is the visitor's URL (search included; the
+first URL after several rewrites; `undefined` when nothing rewrote).
+`usePathname()` and `useSearchParams()` show the visitor's URL in the server
+HTML and after hydration, except in a render other visitors are served (see
+Caches); `useParams()` and the route name are the target's. The response
+carries `x-rango-rewrite: <target pathname>`.
+
+**`ctx.rewrittenFrom` is request identity**, like `cookies()`: reading it
+inside a `cache()` boundary or a `"use cache"` function throws (pass what
+you need in from middleware), and a render other visitors may be served (a
+PPR shell capture, a page the document cache stores) reads `undefined`, as a
+direct visit does.
+
+**Middleware only, by design.** `rewrite()` is a middleware tool. A route
+handler or a loader (any loader, `ssr: false` included) cannot rewrite: its
+throw is an error whose message points you to route middleware. A rewrite
+that depends on data goes in the route's middleware, reading the data
+through a cached function the loader shares, so the lookup runs once:
+
+```typescript
+path("/product/:slug", ProductPage, { name: "product" }, () => [
+  middleware(async (ctx, next) => {
+    const product = await getProduct(ctx.params.slug); // cached, shared with the loader
+    if (product.discontinued) {
+      throw rewrite("discontinued", { slug: ctx.params.slug });
+    }
+    await next();
+  }),
+  loader(productLoader), // calls getProduct(slug): a cache hit
+]);
+```
+
+**Throw it, don't return it.** A returned rewrite is an error. Where a
+rewrite cannot be honored it is an error that names the rule: a route
+handler or a loader (see above), a server action (use `redirect()`),
+intercept middleware, a loader fetch (`useFetchLoader`, `load()`: it
+rejects with the rule) or its middleware, and middleware handling a non-GET
+request (a JS action or a no-JS form post: return a `Response`).
+
+**try/catch around next().** A thrown rewrite passes through your
+middleware's `catch`. Rethrow it:
+
+```typescript
+export const errorPage: Middleware = async (ctx, next) => {
+  try {
+    return await next();
+  } catch (error) {
+    if (ctx.isRewrite(error)) throw error;
+    return new Response("Something went wrong", { status: 500 });
+  }
+};
+```
+
+**Loops.** More than 5 rewrites in one request, or a rewrite to the URL the
+request is on, answers 508 and reports a `RewriteLoopError` (its message has
+the trail, `/a -> /b -> /a`) through `onError` with phase `"routing"`.
+
+**Caches.**
+
+- The document cache keys a rewritten request by the target's URL, as a
+  direct visit. Register the rewriting middleware **before**
+  `createDocumentCacheMiddleware()`: a cache hit for the visitor's URL would
+  be served before your middleware runs. A page the document cache stores,
+  and a PPR shell of the target, are rendered as a direct visit to the
+  target: they carry the target's pathname and `ctx.rewrittenFrom` is
+  `undefined` there, so a component that renders `usePathname()` can
+  mismatch on hydration at the visitor's URL when such a page is served to
+  a rewritten request.
+- The client's prefetch and history caches keep a rewritten page under the
+  visitor's URL, and nothing tells them about the rewrite: a page prefetched
+  during a lock shows the lock page for up to `prefetchCacheTTL` after the
+  lock lifts. `invalidateClientCache()` drops a client's caches, for the
+  client that receives the response; mark the clients that saw the lock and
+  call it on their first response after it lifts:
+
+  ```typescript
+  import { cookies, invalidateClientCache, rewrite } from "@rangojs/router";
+
+  export const maintenance: Middleware = async (ctx, next) => {
+    if (!locked) {
+      if (cookies().get("saw-lock")) {
+        cookies().delete("saw-lock");
+        invalidateClientCache();
+      }
+      return next();
+    }
+    cookies().set("saw-lock", "1", { path: "/" });
+    // ...the lock as above
+    throw rewrite("maintenance");
+  };
+  ```
+
+**Testing.** `runMiddleware` reports a thrown rewrite as `result.rewrite`
+(`{ pathname, search, routeName? }`). `serveShellRequest` takes a rewritten
+page request through the full production pipeline (document or `partial`
+navigation): the target's middleware, render, status and `x-rango-rewrite`.
+`dispatch` re-dispatches too, for response routes only: it matches the
+visitor's URL first and throws on a component (RSC) route.
+`renderRoute(..., { request: "/shop", rewrite: "/maintenance" })` renders
+the target's route at the visitor's URL. See `/testing`.
+
 ## Authentication Middleware
 
 ```typescript

package/skills/ppr/SKILL.md

@@ -149,6 +149,15 @@ material is shared per host+URL and request partition. `cache(false)`, or a
 `condition()` that returns false, on a ppr route now renders the request like a
 cache miss (no shell).
 
+### A request middleware rewrote
+
+A request middleware rewrote (`throw rewrite()`, `/middleware`) to a `ppr`
+route is served the target's shell under the target's key. The capture
+renders the target as a direct visit: `ctx.rewrittenFrom` reads `undefined`
+there and the payload carries the target's pathname, so the shell is the
+same for direct and rewritten visitors (a component that renders
+`usePathname()` shows the target's URL to a rewritten visitor on a HIT).
+
 ### Request-partitioned shells
 
 A route whose `cache()` record is partitioned by the request partitions its

package/skills/rango/SKILL.md

@@ -311,7 +311,7 @@ Grouped by concern — read when you need to…
 | `/layout`                 | Layouts that wrap child routes                                             |
 | `/parallel`               | Multi-column layouts and sidebars                                          |
 | `/intercept`              | Modal/slide-over patterns for soft navigation                              |
-| `/middleware`             | Request processing and authentication                                      |
+| `/middleware`             | Request processing, authentication, `throw rewrite()` (same-URL rewrites)  |
 | `/host-router`            | Multi-app host routing with domain/subdomain patterns                      |
 | `/links`                  | URL generation: ctx.reverse, href, useHref, useMount, scopedReverse        |
 | `/response-routes`        | JSON/text/HTML/XML/stream endpoints with `path.json()`, `path.text()`      |

package/skills/server-actions/SKILL.md

@@ -492,6 +492,11 @@ file-path-based revalidation predicates, define the action in a module-level
 `"use server"` file rather than inline. See `/loader` for the full revalidation
 contract (deferred returns, soft suggestions).
 
+A loader in a `clientUrls()` group takes the same predicate with the same
+arguments, `actionResult` and `formData` included: the build moves it out of
+the `"use client"` module and the server runs it (`/client-urls` →
+"Revalidation runs on the server").
+
 ### Cross-segment dependencies
 
 If a loader reads `ctx.get()` data set by an outer layout/handler, that
@@ -680,6 +685,28 @@ export async function deletePost(id: string): Promise<void> {
 For a recoverable "already gone" case, return a result the form can show
 (`{ error: "Post not found" }`) instead of throwing.
 
+### A loader that fails on the revalidation render
+
+A loader that throws while it reruns after the action does not undo the
+action, which has already run and returned. What follows depends on the route:
+
+- **No `loading()` on the route (and any `clientUrls()` route):** the action
+  call rejects with the loader's error, nothing of that revalidation commits,
+  and the page keeps its data and its React state. A `<form action>`,
+  `useActionState` or `useTransition` call hands that rejection to the nearest
+  React error boundary above the form.
+- **A `urls()` route with `loading()`:** the call resolves with the action's
+  result, the page renders, and the loader's read throws to the nearest React
+  error boundary.
+- **An `errorBoundary()` above the route:** its fallback replaces the route.
+
+For a failure the user can retry, return it from the loader as data
+(`{ ok: false, reason }`) and render it where the data goes. A failure returned
+as data is a value like any other, so a `cache()` on the loader (or a `ppr`
+bake, or a prerender) stores and serves it; a thrown error is never stored.
+See `/client-urls` → "A loader that fails on its rerun" for the table and an
+example.
+
 ### Authorization in actions
 
 Route middleware does **not** wrap action execution — only global

package/skills/testing/client-components.md

@@ -26,6 +26,7 @@
 | `nonce`           | `string`                                                               | CSP nonce to seed via `NonceContext`, so a component calling `useNonce()` (e.g. an analytics/GTM head script) sees it — mirroring SSR. Defaults to `undefined` (the browser default).                                                         |
 | `defaultPrefetch` | `PrefetchStrategy`                                                     | Router default for `<Link>` and eligible plain anchors. `data-prefetch="false"`/`"none"` opts out one anchor; ancestor `data-prefetch-scope="false"`/`"none"` hard-disables the subtree; `"true"` permits routed resource suffixes elsewhere. |
 | `hydrate`         | `boolean`                                                              | Render the same tree to HTML first (`renderToString`, no `window`/`document`), then hydrate that HTML instead of mounting fresh. The result gains `serverHtml` and `recoverableErrors`. See [Hydration](#hydration).                          |
+| `rewrite`         | `string`                                                               | The path middleware rewrote `request` to (`throw rewrite()`): the leaf is matched against it for params, while the location (`usePathname`, `useSearchParams`) stays `request`, as a rewritten document renders and hydrates.                 |
 
 `RenderRouteSpec = { path, Component, layout?, loaderIds?, name?, transition? }` — one node of the route definition. The array is the layout chain root-to-leaf; the LAST entry is the leaf route (its pattern is matched against `request` to extract params; layout patterns are informational). `loaderIds` attaches seeded loaders to THIS node's segment; `layout` on the leaf wraps it; `name` is informational. `transition` is the `transition()` config this node declares (`{}` for a bare `transition()`), attached to its segment exactly as the DSL does — see [Held navigation](#held-navigation).
 

package/skills/testing/middleware.md

@@ -44,16 +44,17 @@ The `ctx` your middleware reads. Notable fields:
 
 ### Returns — `RunMiddlewareResult<TEnv>`
 
-| Field             | Type                      | Meaning                                                                                                                                                                                                                                                      |
-| ----------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `response`        | `Response`                | The final Response: the downstream response, or a middleware short-circuit.                                                                                                                                                                                  |
-| `ctx`             | `RequestContext<TEnv>`    | The underlying RequestContext (NOT a per-middleware `MiddlewareContext`). Use `ctx.get(...)` for anything the envelope above doesn't surface.                                                                                                                |
-| `nextCalled`      | `number`                  | Times the terminal handler ran: `0` on short-circuit, `1` on pass-through.                                                                                                                                                                                   |
-| `dynamic`         | `boolean`                 | Whether the chain called `ctx.dynamic()` (the PPR shell opt-out).                                                                                                                                                                                            |
-| `cookies`         | `Record<string, string>`  | Effective cookie view: request cookies merged with chain sets/deletes (last-write-wins), as `{ name: value }`.                                                                                                                                               |
-| `headers`         | `Record<string, string>`  | Final response headers as `{ name: value }`, lowercased, EXCLUDING `set-cookie` (use `cookies`).                                                                                                                                                             |
-| `locationState`   | `Record<string, unknown>` | Flat `{ key: value }` state set via `setLocationState()` / `redirect({ state })` (empty when none).                                                                                                                                                          |
-| `stateCookieName` | `string`                  | The resolved rango state cookie name seeded for the run (default `rango-state_router_0`). Assert a middleware's `invalidateClientCache()` rotation against it without recomputing — parity with `runInRequestContext` / `runLoaderResult` / `renderHandler`. |
+| Field             | Type                      | Meaning                                                                                                                                                                                                                                                                     |
+| ----------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `response`        | `Response`                | The final Response: the downstream response, or a middleware short-circuit.                                                                                                                                                                                                 |
+| `ctx`             | `RequestContext<TEnv>`    | The underlying RequestContext (NOT a per-middleware `MiddlewareContext`). Use `ctx.get(...)` for anything the envelope above doesn't surface.                                                                                                                               |
+| `nextCalled`      | `number`                  | Times the terminal handler ran: `0` on short-circuit, `1` on pass-through.                                                                                                                                                                                                  |
+| `rewrite`         | `RunMiddlewareRewrite?`   | The target of a `throw rewrite(...)`: `{ pathname, search, routeName? }`, resolved as production resolves it (a path basename-prefixed, a name through `routeMap`). `undefined` when nothing rewrote. On a rewrite, `response` carries what the chain set before the throw. |
+| `dynamic`         | `boolean`                 | Whether the chain called `ctx.dynamic()` (the PPR shell opt-out).                                                                                                                                                                                                           |
+| `cookies`         | `Record<string, string>`  | Effective cookie view: request cookies merged with chain sets/deletes (last-write-wins), as `{ name: value }`.                                                                                                                                                              |
+| `headers`         | `Record<string, string>`  | Final response headers as `{ name: value }`, lowercased, EXCLUDING `set-cookie` (use `cookies`).                                                                                                                                                                            |
+| `locationState`   | `Record<string, unknown>` | Flat `{ key: value }` state set via `setLocationState()` / `redirect({ state })` (empty when none).                                                                                                                                                                         |
+| `stateCookieName` | `string`                  | The resolved rango state cookie name seeded for the run (default `rango-state_router_0`). Assert a middleware's `invalidateClientCache()` rotation against it without recomputing — parity with `runInRequestContext` / `runLoaderResult` / `renderHandler`.                |
 
 ## Recipe
 
@@ -89,6 +90,26 @@ describe("requireUser", () => {
 
 Pass an array to run several in order. Cookies set inside middleware via the standalone `cookies().set(...)` (imported from `@rangojs/router`, NOT a `ctx` method) surface on the result's `cookies` and on the merged response `Set-Cookie`.
 
+### A middleware that rewrites
+
+A `throw rewrite(target)` (see `/middleware` → "Rewrite") does not fail the run: `result.rewrite` names the target, and the values and cookies the chain set before the throw are on `result.ctx` and `result.cookies`, as production keeps them for the target. `runMiddleware` does not run the target. To test what a rewritten page renders, use `serveShellRequest` (`./serve-shell-request.md` → "A page middleware rewrites"): it takes the request through the full production pipeline, the target's middleware, render, status and `x-rango-rewrite` included. `dispatch` re-dispatches only between response routes: it matches the visitor's URL before middleware runs and throws on a component (RSC) route.
+
+```ts
+it("rewrites a locked page to the maintenance route", async () => {
+  const result = await runMiddleware(maintenance, {
+    request: "/shop",
+    routeMap: { maintenance: "/maintenance" },
+  });
+  expect(result.rewrite).toEqual({
+    pathname: "/maintenance",
+    search: "",
+    routeName: "maintenance",
+  });
+  expect(result.nextCalled).toBe(0);
+  expect(result.ctx.get(Lock)).toEqual({ until: "12:00" });
+});
+```
+
 ## Caveats
 
 - No `handles`/`rendered` option by design: the middleware context has no handle APIs in production — no push (`ctx.use(Handle)` is a handler/loader API) and no post-barrier read (`ctx.get(handle)` is loader-only, and middleware runs BEFORE the render barrier anyway). Read handle data in a loader and test it with `runLoader`; assert loader pushes via `runLoaderResult(...).handlePushes` (see `./handles.md`).

package/skills/testing/response-routes.md

@@ -91,6 +91,7 @@ describe("api routes via dispatch", () => {
 - 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 takes the error's status (`RouterError.status`, else 500, or a non-200 status already set upstream in the request pipeline). On a `path.json` route the body is an RFC 9457 problem+json object `{ title, status, detail, code }` (`application/problem+json;charset=utf-8`), where `code` is the `RouterError.code`, else `"INTERNAL"`, and the `type` member is omitted. On text/html/xml/md routes the body is `text/plain`: the `RouterError` message, the error message in dev, or `"Internal Server Error"` in production. 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 `throw rewrite(target)` from global or route middleware re-dispatches as the router does: global middleware matched on the target's path, the target's route middleware and handler, the same request context, `x-rango-rewrite` on the response, 508 on a loop. The visitor's URL is matched before middleware runs, so it must be a response route (or a redirect or 404) too; a rewrite target that is a component route throws the same error as a direct request.
 - 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.
 - `dispatch` does NOT execute server actions (`?_rsc_action`), but it DOES run the global middleware chain on an action request — middleware can still 401/redirect it, and any 3xx redirect on a partial OR action request becomes a `204` + `X-RSC-Redirect` (fetch-safe interception), the raw `Location` dropped. Location state carried on such a redirect is dropped too (production embeds it in a Flight payload); cover that at e2e.
 - `createRouter({ onError })` is NOT invoked for a thrown non-Response HANDLER error here (the typed error Response still matches production), and `cache.decision` / `loader.*` telemetry never fires (no RSC render runs). Cover both at e2e.

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

@@ -14,7 +14,7 @@ The one stub is the HTML step (the SSR module), because `react-dom/server` does
 
 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.
 
-A `Prerender` route is served as in production: from the artifact `router.matchForPrerender` bakes for the URL (on its first request, kept until `resetShellTestState()`), through the production prerender store, so its handler runs once, at the bake, and never on a request. Its first `ppr` request is a MISS with a runtime capture, as a URL without a build-time shell is in production. The shell `vite build` bakes (served first in production for a URL without a query string) is not reproduced: keep that in e2e. The `env` option doubles as the bake's `buildEnv`. An on-demand route (`Prerender(..., { onDemand })`) is baked only when it is wrapped in `Passthrough()` and its `getParams()` lists the param, as a build bakes it; a plain on-demand route is not baked here, so its pages come from the prerender store alone (`router.prerender()`), and "a removed page the build baked" is a case for a `Passthrough` route or for e2e.
+A `Prerender` route is served as in production: from the artifact `router.matchForPrerender` bakes for the URL (on its first request, kept until `resetShellTestState()`), through the production prerender store, so its handler runs once, at the bake, and never on a request. A partial navigation an `intercept()` of the route answers is served from the intercept variant the same bake keeps, as the build writes it: the intercept's handler output is the bake's, its loaders run per request. Its first `ppr` request is a MISS with a runtime capture, as a URL without a build-time shell is in production. The shell `vite build` bakes (served first in production for a URL without a query string) is not reproduced: keep that in e2e. The `env` option doubles as the bake's `buildEnv`. An on-demand route (`Prerender(..., { onDemand })`) is baked only when it is wrapped in `Passthrough()` and its `getParams()` lists the param, as a build bakes it; a plain on-demand route is not baked here, so its pages come from the prerender store alone (`router.prerender()`), and "a removed page the build baked" is a case for a `Passthrough` route or for e2e.
 
 ## API
 
@@ -392,6 +392,24 @@ const result = await serveShellRequest(router, "/shop", {
 
 This is the request a `clientUrls()` group's `revalidate()` sees on an action: the action's return value as `actionResult`, its last `FormData` argument as `formData`. The pinned example is `src/testing/__tests__/client-urls-revalidate.rsc-test.tsx`. Not with `partial` or `form`.
 
+## A page middleware rewrites
+
+A request a middleware rewrites (`throw rewrite()`, see `/middleware`) runs through the same production handler: the visitor's pass, then the target's, with one request context. Assert what the visitor gets: the target's body and status, `x-rango-rewrite`, the visitor's pathname in the payload, and on a `ppr` target the target's shell key.
+
+```ts
+it("a locked page renders the maintenance route at its own URL", async () => {
+  const result = await serveShellRequest(router, "/shop?lock=on");
+  expect(result.response.status).toBe(503); // set by the target's middleware
+  expect(result.response.headers.get("x-rango-rewrite")).toBe("/maintenance");
+  expect(result.body).toContain("Down for maintenance");
+
+  const nav = await serveShellRequest(router, "/shop?lock=on", {
+    partial: { from: "/" },
+  });
+  expect(nav.flight).toContain("Down for maintenance"); // the target's segments
+});
+```
+
 ## Caveats
 
 What the HTML stub cannot reproduce, so keep it in e2e:

package/skills/use-cache/SKILL.md

@@ -236,8 +236,10 @@ this guard, one user's data would be served to another.
 The raw reads throw the same way: `ctx.request.headers` on any `ctx` passed in
 (handler, loader, middleware; it is one `Request` object, also
 `getRequestContext().request`), and `getRequestContext().cookie()` /
-`.cookies()`. A `ctx` or a `Request` argument keys the entry by its route and
-URL only, never by its headers.
+`.cookies()`. `ctx.rewrittenFrom` (the visitor's URL of a request middleware
+rewrote) throws too, on a request nothing rewrote as well: it is not in the
+key. A `ctx` or a `Request` argument keys the entry by its route and URL
+only, never by its headers.
 
 Extract the value before the cached function and pass it as an argument:
 

package/src/__augment-tests__/augmented.check.ts

@@ -19,6 +19,7 @@ import type {
 import type { DefaultRouteName } from "../types/global-namespace.js";
 import type { InterceptWhenFn } from "../server/context.js";
 import { href } from "../href-client.js";
+import { rewrite, type Rewrite } from "../route-definition/rewrite.js";
 import type { Money, TestBindings } from "./augment.js";
 
 type Expect<T extends true> = T;
@@ -68,6 +69,25 @@ function middlewareReverse(ctx: MiddlewareContext): void {
 }
 void middlewareReverse;
 
+// rewrite() takes a path, or a global name with the params and search
+// ctx.reverse takes; ctx.isRewrite narrows a caught value to a Rewrite.
+function middlewareRewrite(ctx: MiddlewareContext, caught: unknown): void {
+  void rewrite("/maintenance?from=shop");
+  void rewrite("home");
+  void rewrite("blog.post", { slug: "hello" });
+  void rewrite("search", {}, { q: "hats" });
+  // @ts-expect-error - a route with params needs them
+  void rewrite("blog.post");
+  // @ts-expect-error - unknown global name is rejected
+  void rewrite("nope");
+  // @ts-expect-error - dot-local name; a rewrite resolves global names only
+  void rewrite(".home");
+  if (ctx.isRewrite(caught)) {
+    type _narrowed = Expect<Equal<typeof caught, Rewrite>>;
+  }
+}
+void middlewareRewrite;
+
 // routeName narrows to the generated route names.
 type _routeName = Expect<
   Equal<DefaultRouteName, "home" | "blog.post" | "search">

package/src/browser/event-controller.ts

@@ -1037,6 +1037,9 @@ export function createEventController(
         // If not settled and not completed, this is an error case - force finalize
         if (!settled && inflightActions.has(id)) {
           actionCompleted = true;
+          // Done, as complete()/fail() would mark it: an action started in its
+          // settle window is sequential, not concurrent (#675).
+          entry.completed = true;
           streamingEnded = true;
           tryFinalize();
         }

package/src/browser/merge-segment-loaders.ts

@@ -1,12 +1,16 @@
 import type { ResolvedSegment } from "./types.js";
 import { debugLog, IS_BROWSER_DEBUG } from "./logging.js";
+import { settledValue } from "../thenable-status.js";
 
 /**
  * Merge partial loader data from server with cached loader data.
  *
  * During partial revalidation (stale or action), the server may return only
- * some loaders that pass the revalidation check. The component still needs
- * all loader data, so we merge fresh data with cached data.
+ * some loaders that pass the revalidation check, none when every one is held.
+ * The component still needs all loader data, so we merge fresh data with
+ * cached data. Two settled aggregates merge into the array itself: a fresh
+ * Promise.all over settled parts is a promise React has not read, and content
+ * on screen handed one suspends (docs/internal/suspense-contract.md, rule 2).
  *
  * @param fromServer - Segment returned from server with partial loaders
  * @param fromCache - Cached segment with full loader data
@@ -25,24 +29,33 @@ export function mergeSegmentLoaders(
     );
   }
 
+  // Fresh data for the loaders the server re-ran, cached data for the rest.
+  const merge = (newData: any[], cachedData: any[]): any[] =>
+    cachedLoaderIds.map((id: string, i: number) => {
+      const newIndex = serverLoaderIds.indexOf(id);
+      return newIndex !== -1 ? newData[newIndex] : cachedData[i];
+    });
+  const settledNew = settledValue(fromServer.loaderDataPromise!);
+  const settledCached = settledValue(fromCache.loaderDataPromise!);
+
   return {
     ...fromCache,
-    // Keep cached component (server's might be a fresh Promise that needs the loaders)
-    component: fromCache.component,
-    // Merge loader data - await both and combine
-    loaderDataPromise: Promise.all([
-      fromServer.loaderDataPromise!,
-      fromCache.loaderDataPromise!,
-    ]).then(([newData, cachedData]) => {
-      // Build merged array: use new data for updated loaders, cached for rest
-      return cachedLoaderIds.map((id: string, i: number) => {
-        const newIndex = serverLoaderIds.indexOf(id);
-        if (newIndex !== -1) {
-          return (newData as any[])[newIndex]; // Use fresh data
-        }
-        return (cachedData as any[])[i]; // Use cached data
-      });
-    }),
+    // The server re-ran the slot's handler and layout: their render applies,
+    // as it does when every loader re-runs. Only the loaders it held keep
+    // their cached data.
+    component: fromServer.component,
+    layout: fromServer.layout,
+    // Every loader held: the cached aggregate itself, so a boundary still
+    // waiting on it keeps its one thenable (suspense-contract.md, rule 1).
+    loaderDataPromise:
+      serverLoaderIds.length === 0
+        ? fromCache.loaderDataPromise
+        : settledNew && settledCached
+          ? merge(settledNew, settledCached)
+          : Promise.all([
+              fromServer.loaderDataPromise!,
+              fromCache.loaderDataPromise!,
+            ]).then(([newData, cachedData]) => merge(newData, cachedData)),
     // Keep all loader IDs from cache
     loaderIds: fromCache.loaderIds,
     // The rebuilt aggregate is the source of truth. Cached per-loader

package/src/browser/navigation-bridge.ts

@@ -21,6 +21,7 @@ import {
   pushHistoryWithIdx,
 } from "./history-state.js";
 import { consumeHandles } from "./react/NavigationProvider.js";
+import { withSegmentHandles } from "../handles/pushed-by.js";
 import {
   handleNavigationStart,
   handleNavigationEnd,
@@ -386,7 +387,9 @@ export function createNavigationBridge(
       // since it may have fresher data after an action revalidation.
       // This avoids unnecessary server round-trips for shared layout loaders.
       let cachedSegments = cached?.segments;
-      const cachedHandleData = cached?.handleData;
+      // The segments taken from the page on screen: their pushes come from
+      // it too (targetCacheHandleData below).
+      const fromSource = new Set<string>();
       if (cachedSegments && sourceCached?.segments) {
         const sourceSegmentMap = new Map(
           sourceCached.segments.map((s) => [s.id, s]),
@@ -396,7 +399,9 @@ export function createNavigationBridge(
           // Use source (current page) version for shared segments - it's
           // fresher. A placeholder waiting for its fill (prefetch: false) is
           // not a copy of the segment: the target keeps its own.
-          return sourceSeg && !isPlaceholder(sourceSeg) ? sourceSeg : targetSeg;
+          if (!sourceSeg || isPlaceholder(sourceSeg)) return targetSeg;
+          fromSource.add(targetSeg.id);
+          return sourceSeg;
         });
       }
 
@@ -498,7 +503,18 @@ export function createNavigationBridge(
                 ...(hasUsableCache
                   ? {
                       targetCacheSegments: cachedSegments,
-                      targetCacheHandleData: cachedHandleData,
+                      // Read at commit: a push the page on screen gets while
+                      // the request is in flight is in it.
+                      targetCacheHandleData: () =>
+                        withSegmentHandles(
+                          cached?.handleData ?? {},
+                          liveHandleDataForCache(
+                            eventController,
+                            store,
+                            sourceHistoryKey,
+                          ),
+                          fromSource,
+                        ),
                     }
                   : {}),
                 ...(clientUrlPresentation && {