@rangojs/router 0.22.1 → 0.24.0

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

@@ -14,32 +14,34 @@ 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
 
 ### 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).                                                      |
+| 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[]; prefetch?: boolean; fill?: boolean }` | Serve the navigation request the browser sends instead of a document GET: from `from` (default the site root) with `segments` mounted (default none). `prefetch: true` sends it as a `<Link>` prefetch (`X-Rango-Prefetch`), so `prefetch: false` work is deferred. `fill: true` sends the follow-up request (`_rsc_fill=1`) the browser makes after adopting a prefetch; pass the prefetch's delivered ids, without the deferred ones, as `segments`, and the same URL as `from`. |
+| `action`     | `{ ref: Function; id: string; args?: unknown[]; segments?: string[] }`               | Send the request a JS server action call makes from the page at `url`: a POST of `args` (encoded as the browser encodes them) with `?_rsc_action`, the `rsc-action` header, `X-RSC-Router-Client-Path` and `_rsc_segments` (the page's mounted segment ids, default none). Registers `ref` under `id` (`<module id>#<export name>`). Not with `partial` or `form`.                                                                                                                 |
 
 ### 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. |
-| `readHandles`  | `() => Promise<ShellRequestHandles \| undefined>` | Decodes the response's handle data as the browser reads it: `{ hydration, late }` (see "Handles and loader data"). `undefined` when no Flight rendered.                             |
-| `response`     | `Response`                                        | Status and headers. Its body is already read.                                                                                                                                       |
-| `body`         | `string`                                          | The body text.                                                                                                                                                                      |
+| 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.         |
+| `readHandles`  | `() => Promise<ShellRequestHandles \| undefined>` | Decodes the response's handle data as the browser reads it: `{ hydration, late }` (see "Handles and loader data"). `undefined` when no Flight rendered.                                     |
+| `readDeferred` | `() => Promise<string[] \| undefined>`            | The ids of the segments the payload marks deferred (a prefetch skipped them; the fill renders them), in payload order. `[]` when nothing was deferred, `undefined` when no Flight rendered. |
+| `response`     | `Response`                                        | Status and headers. Its body is already read.                                                                                                                                               |
+| `body`         | `string`                                          | The body text.                                                                                                                                                                              |
 
 ### `resetShellTestState(): Promise<void>`
 
@@ -250,6 +252,53 @@ Loader data has no decoder: it rides the payload, so assert it as text in `prelu
 expect(hit.flight).toContain('"stock":"in stock"');
 ```
 
+## Testing `prefetch: false`
+
+Send the prefetch with `partial: { prefetch: true }` and read which segments it deferred, then send the fill the browser would send:
+
+```ts
+const prefetch = await serveShellRequest(router, "/product/1", {
+  cacheStore,
+  partial: { from: "/", prefetch: true },
+});
+// One id per skipped segment: here the flagged loader's. A flagged loading()
+// lists its entry, every entry and slot its fallback covers, and their loaders.
+expect(await prefetch.readDeferred()).toHaveLength(1);
+
+// The ids the prefetch delivered, minus the deferred ones: what the page holds.
+const held = deliveredIds.filter((id) => !deferredIds.includes(id));
+const fill = await serveShellRequest(router, "/product/1", {
+  cacheStore,
+  partial: { from: "/product/1", segments: held, fill: true },
+});
+expect(await fill.readDeferred()).toEqual([]); // a fill defers nothing
+```
+
+`deliveredIds` is the payload's `metadata.matched`, read from `prefetch.flight`. Count the loader's runs in your own fixture: the prefetch ran it zero times, the fill once.
+
+### `clientUrls()` routes
+
+A router that mounts a `clientUrls()` group serves its routes here as in your app. The group is the default export of a `"use client"` module, a client reference in this project, and `rangoUseClientTransform()` ([`./setup.md`](./setup.md)) installs its server projection as the rango plugin's discovery does. Mount the module itself:
+
+```tsx
+import shopUrls from "../src/shop/urls"; // "use client"; export default clientUrls(...)
+
+const router = createRouter().routes(
+  urls(({ include }) => [include("/shop", shopUrls, { name: "shop" })]),
+);
+
+// /shop/product/:id declares loader(PriceLoader) and
+// loader(ReviewsLoader, { prefetch: false }).
+const prefetch = await serveShellRequest(router, "/shop/product/1", {
+  partial: { from: "/shop", segments: held, prefetch: true },
+});
+expect(await prefetch.readDeferred()).toHaveLength(1); // ReviewsLoader's segment
+```
+
+`held` is the `metadata.matched` of a navigation to `/shop`. On a group route only a loader's own flag defers (the group's, and a server layout's above the group); a flagged `loading()` defers nothing there. Loaders inside the group's `intercept()` ignore the flag, as in `urls()`. `dispatch` matches the group's routes through the same projection.
+
+The transform also registers each group loader's `revalidate()` predicates, which Vitest leaves as plain functions in the module, so the server runs them as the hoisted predicates run in your app. A `partial` navigation, or an `action` with the page's `segments`, reaches them with the `urls()` arguments, `actionResult` and `formData` included.
+
 ## Warming a route: router.prerender()
 
 `router.prerender()` warms a route that is not `Prerender(..., { onDemand })`
@@ -322,6 +371,45 @@ expect(await result.readPayloadFormState()).toEqual(result.formState);
 - Request headers come from `headers`. No `Origin` is sent by default, which the origin guard allows.
 - Not with `partial`. The hydration itself (`hydrateRoot` taking the state, the hook not resetting) is e2e.
 
+## A server action called from the page
+
+`serveShellRequest(router, url, { action: { ref, id, args, segments } })` sends the request a JS server action call makes from the page at `url`, as `browser/server-action-bridge.ts` sends it: a POST of `args` with `?_rsc_action`, the `rsc-action` header, `X-RSC-Router-Client-Path` and `_rsc_segments`. `ref` is registered under `id` (`<module id>#<export name>`, any unique string of that shape in a test) so the handler loads it by id. The response is the action's Flight payload: its return value and the segments it re-rendered, `flight` as for any other request. Pass the segment ids the page holds as `segments`, so the request has segments to revalidate; without them the server holds none. Read them from the `metadata.matched` of a `partial` request's payload (`flight`), as in "Testing `prefetch: false`" above.
+
+```tsx
+const page = await serveShellRequest(router, "/shop", {
+  partial: { from: "/" },
+});
+const held: string[] = readMatched(page.flight); // your parse of metadata.matched
+const result = await serveShellRequest(router, "/shop", {
+  action: {
+    ref: checkout,
+    id: "src/actions/cart.ts#checkout",
+    args: [formData],
+    segments: held,
+  },
+});
+```
+
+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:
@@ -337,7 +425,7 @@ Other caveats:
 - 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, and one POST shape: a form submitted before hydration (see "A form submitted before hydration" above). Other server action requests are not served; test their effects with `runInRequestContext`.
+- GET, and two POST shapes: a form submitted before hydration (see "A form submitted before hydration" above) and a JS server action call (`action`, see "A server action called from the page" above). Test an action's own effects (cookies, headers) with `runInRequestContext`.
 - Same setup as every Flight test: the react-server condition and `rangoTestAliases()` (see [`./setup.md`](./setup.md)).
 
 ## See also

package/skills/testing/setup.md

@@ -19,7 +19,7 @@ Real machinery: Vite transpiles `@rangojs/router`'s shipped TS source and resolv
 | `rangoTestConfig(opts?)`    | `{ alias, server: { deps: { inline } } }` | Recommended. Spread into the node/DOM project's `test` block. Bundles the resolve aliases AND `server.deps.inline`.                                                                                                                        |
 | `rangoTestAliases(opts?)`   | `TestAlias[]` (`{ find, replacement }[]`) | Lower-level. The bare `@rangojs/router` -> `index.rsc.ts` alias plus the `:version` / `@vitejs/plugin-rsc/rsc` (`/rsc/server`, `/rsc/client`) stubs (and CF stubs under `preset:"cloudflare"`). Used in the rsc project's `resolve.alias`. |
 | `rangoInlineDeps`           | `RegExp[]` (`[/@rangojs[/\\]router/]`)    | The `server.deps.inline` patterns on their own. Use in the rsc project (`test.server.deps.inline`), or wherever you call `rangoTestAliases` directly instead of `rangoTestConfig`.                                                         |
-| `rangoUseClientTransform()` | a Vite plugin (`{ name, transform }`)     | Add to the rsc project `plugins`. Applies the `"use client"` transform so `renderServerTree` / `renderHandler` auto-discover client islands from the server tree's imports.                                                                |
+| `rangoUseClientTransform()` | a Vite plugin (`resolveId`, `transform`)  | Add to the rsc project `plugins`. Applies the `"use client"` transform so `renderServerTree` / `renderHandler` auto-discover client islands, and projects `"use client"` `clientUrls()` modules for `serveShellRequest` / `dispatch`.      |
 | `rangoUseCacheTransform()`  | a Vite plugin (`enforce: "post"`)         | Add to the rsc project `plugins`. Runs the rango plugin's `"use cache"` transform with dev ids (`<path>#<name>`, the path relative to the root its `configResolved` reads) so a directive function caches.                                 |
 
 ### Returns — `RangoTestConfig` (from `rangoTestConfig`)
@@ -117,7 +117,7 @@ Scripts:
 - The forked rsc worker (`pool: "forks"`) must force the condition via `execArgv: ["--conditions=react-server"]`, or React throws "the react-server condition must be enabled".
 - The `@rangojs/router:version` and `@vitejs/plugin-rsc/rsc` (`/rsc/server`, `/rsc/client`) virtuals must be stubbed; the preset does it. A bare router import without stubbing throws.
 - The rango fragment goes under `test` (`test.alias` + `test.server.deps.inline`, both returned by `rangoTestConfig`), NOT under top-level `resolve`.
-- Wire `rangoUseClientTransform()` into the rsc project `plugins` so islands auto-discover from the server tree imports (see `./server-tree.md`); without it, register islands explicitly with `clientComponents`. The transform's `registerClientReference` import is resolved from `@rangojs/router`'s `@vitejs/plugin-rsc` — the consumer does not need a direct plugin-rsc dependency.
+- Wire `rangoUseClientTransform()` into the rsc project `plugins` so islands auto-discover from the server tree imports (see `./server-tree.md`); without it, register islands explicitly with `clientComponents`. It also installs the server projection of every `"use client"` module whose default export is a `clientUrls()` definition, as the rango plugin's discovery does in your app, so `include("/shop", shopUrls)` and `.routes(shopUrls)` serve the group's routes through `serveShellRequest` and `dispatch`; without it the include throws `could not resolve the server projection`. The node project needs nothing: there the module's default export is the definition itself. The transform's `registerClientReference` import is resolved from `@rangojs/router`'s `@vitejs/plugin-rsc` — the consumer does not need a direct plugin-rsc dependency.
 - Wire `rangoUseCacheTransform()` into the rsc project `plugins` so a function written with `"use cache"` is wrapped as in dev. `rango()` runs that transform only in its `rsc` environment and Vitest transforms in `ssr`, so without it the directive is inert and the function runs on every call. See [`./render-handler.md`](./render-handler.md#a-use-cache-hit).
 
 ## See also

package/skills/typesafety/route-types.md

@@ -246,5 +246,5 @@ changes nothing, so narrow with the ternary above. Avoid a bare
 the reference the same way the router derives `actionId` (`$id ?? $$id`: the
 file-path `$id` injected in a production RSC build, otherwise React's `$$id`),
 so matching works in dev and production. `actionId` stays available for
-advanced cases. In `clientUrls()` groups the predicate runs in the browser,
-where `actionId` is the hashed form (see `/client-urls`).
+advanced cases. In `clientUrls()` groups the loader's predicate runs on the
+server too, with these same arguments (see `/client-urls`).

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/skills/view-transitions/SKILL.md

@@ -433,6 +433,8 @@ function ProductPage() {
 
 This is the rango analogue of the "router triggers, you place the names" model used by React Router / TanStack: rango guarantees navigations run inside a React transition; you own the boundaries.
 
+On a route with `loading()` and slow loaders, `viewTransition: false` is also what removes the view transition that changes nothing; see [A view transition that changes nothing under `loading()`](#a-view-transition-that-changes-nothing-under-loading).
+
 **App-wide default.** Flip the default for every `transition()` segment at the router level. A per-segment `viewTransition` still overrides it.
 
 ```ts
@@ -463,6 +465,30 @@ On React 19.2 (no `<ViewTransition>` export) the "VT" column is a no-op, so ever
 
 > On React 19.2 there is no `<ViewTransition>` at all, so `viewTransition: false` is visually a no-op there — but the startTransition driving and content-hold still apply, identical to `transition({})`.
 
+## A view transition that changes nothing under `loading()`
+
+On a cold click, a route with `transition()` and `loading()` can start a view transition that changes nothing on screen, and its content shows only after that transition ends ([#1078](https://github.com/rangojs/rango/issues/1078)). React causes it, not a router update, and the router does not steer or cancel it. Two shapes hit it:
+
+- **One loader slower than about 320 ms, on a navigation where the route's client component module is still loading when the navigation first renders.** In a production build that is the first navigation to that module; in dev it is every navigation, because the dev server resolves each response's client references asynchronously.
+- **Two or more loaders under one `loading()` whose data lands at different times, the last one later than about 320 ms.** Module state does not matter.
+
+Not affected: a fully prefetched click (it commits complete), and a loader that lands before the fallback has been up for 300 ms (the 100 ms and 280 ms cells in #1078 ran two view transitions, the navigation's and the reveal's).
+
+The cost is the browser's view-transition duration before the content shows: Chromium's default animation is 250 ms, and the idle transitions measured took 265 to 285 ms from `ready` to `finished`. The View Transitions guide on the docs site ("When a view transition changes nothing") has the start counts and content times per shape, in dev and in production.
+
+**Why.** When the first thing the route's `loading()` boundary waits on lands (the client module, or the first loader), React retries the boundary. The retry suspends again on the slower loader and commits with the fallback still in place, throttled to 300 ms after the fallback committed. That commit is view-transition eligible and the router's `<ViewTransition>` is on its path, so React calls `document.startViewTransition`; nothing changes on screen, the browser still runs its default animation, and the slower loader's reveal waits: React holds the next view-transition commit until the running transition's `finished` resolves. React 19.3.0 and the canary and experimental builds of 2026-10-06 behave the same.
+
+### Escape hatches
+
+Two options remove it, in dev and in production:
+
+- **`transition({ viewTransition: false })`** places no router `<ViewTransition>` for the segment that declares it, so React has nothing of that segment's to animate on the retry commit. The navigation still commits through `startTransition`, so same-route content is still held; what you give up is the router's cross-fade. It only covers the segment it is set on: a layout above that declares its own `transition()` still wraps the route's outlet content in a router `<ViewTransition>` (`wrapDefaultOutletContent` in [segment-system.tsx](../../src/segment-system.tsx)), and the idle transition stays. Set it on every segment in the matched chain that declares `transition()`, or app-wide with `createRouter({ viewTransition: false })`.
+- **`transition({ when })` returning `false`** commits the navigation urgently and renders every router `<ViewTransition>` of the navigation with every class `"none"` (`GATED_OFF_CLASSES` in [segment-system.tsx](../../src/segment-system.tsx)); React starts no transition for it. One `when` on one segment is enough, because a `false` gates the whole navigation off: on a same-route navigation the `loading()` skeleton streams instead of the previous content being held, and nothing animates. Use it when `kind`, `from` and `to` tell you which navigations hit the shape.
+
+### Your own `<ViewTransition>`
+
+A `<ViewTransition>` that you place and that stays on screen across the navigation (for example around a layout's `<Outlet />`) takes part in the same commits and starts the same idle transition, whichever router option is set. The router only controls its own boundaries, so this one is yours to configure. `update="none"` on it started no view transition for the click, but the boundary then no longer animates the real navigation's update either (no cross-fade of the outlet). Measured in Chromium only; other engines were not measured.
+
 ## Testing a transition() route
 
 On React 19.3+ a transition commit briefly keeps the exiting `<ViewTransition>`

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/defer.ts

@@ -0,0 +1,82 @@
+import { use } from "react";
+import { SETTLED_THENABLE } from "../thenable-status.js";
+
+/**
+ * One hole of a `prefetch: false` adoption (browser/partial-update.ts
+ * armHoles): the promise every reader of the hole waits on, and what the
+ * router knows of it. The router sets `status` and `value` here; it never
+ * writes React's thenable fields on `promise`.
+ *
+ * Resolve-only: a hole is filled or released (releaseHoles), never rejected.
+ * A failure arrives as a fulfilled value (a loader's error envelope, an
+ * error segment's node).
+ */
+export class Defer<T> {
+  status: "pending" | "fulfilled" = "pending";
+  value: T | undefined;
+  /** A reader has handed React `promise` (readDefer). */
+  read?: boolean;
+  /**
+   * Resolved with a value the router holds (a node), the hole is
+   * "fulfilled" at once. Resolved with a stream (a Flight chunk), its promise
+   * follows the stream, and so does the hole: "fulfilled" with the stream's
+   * value once it arrives, so a reader that mounts after that reads the value
+   * as it would read the chunk Flight marked. A rejected stream leaves the
+   * hole pending; its promise carries the rejection.
+   */
+  resolve!: (value: T) => void;
+  readonly promise: Promise<T> = new Promise<T>((settle) => {
+    this.resolve = (value) => {
+      settle(value);
+      if (value instanceof Promise) {
+        value.then(
+          (arrived: T) => {
+            this.status = "fulfilled";
+            this.value = arrived;
+          },
+          () => {},
+        );
+      } else {
+        this.status = "fulfilled";
+        this.value = value;
+      }
+    };
+  });
+}
+
+/**
+ * The read rule, for a component that reads a hole (Suspender, useLoader).
+ * A hole that has fulfilled and that no reader has handed React is its
+ * value: use() of a promise React has not seen suspends an urgent render
+ * once, and the boundary shows its fallback. Once a reader has handed React
+ * the promise, every read is use() of that promise: React has marked it and
+ * returns its value at once, and a replay of the reader must hand use() the
+ * thenable it read before ("A component was suspended by an uncached
+ * promise"). Either way use() is called once, as at every useLoader read.
+ */
+export function readDefer<T>(hole: Defer<T>): T {
+  if (hole.status === "fulfilled" && !hole.read) {
+    use(SETTLED_THENABLE);
+    return hole.value as T;
+  }
+  hole.read = true;
+  return use(hole.promise);
+}
+
+/**
+ * A hole as the loader-streams convention has it: its promise while pending,
+ * its value once fulfilled. Anything else is returned as it is. For an
+ * aggregate, the pending-stream registry, and a node React reads itself (a
+ * segment or slot with no `loading()`): a router component there would be a
+ * fiber the filled page's node does not have, and the next render from the
+ * filled entry would remount the segment. React suspends such a read on the
+ * component above it, which commits nothing until the hole fulfils, so the
+ * value can stand where React read the promise.
+ */
+export function asStream(value: unknown): unknown {
+  return value instanceof Defer
+    ? value.status === "fulfilled"
+      ? value.value
+      : value.promise
+    : value;
+}

package/src/browser/document-revealed.ts

@@ -0,0 +1,52 @@
+/** Poll interval; setTimeout so a tab hidden after first paint still settles. */
+const REVEAL_POLL_MS = 50;
+
+/**
+ * A Suspense boundary of the document React has not revealed yet: Fizz marks
+ * one `$?` while its content streams and `$~` once its reveal is queued.
+ */
+function isUnrevealed(node: Comment): boolean {
+  return node.isConnected && (node.data === "$?" || node.data === "$~");
+}
+
+function unrevealedBoundaries(): Comment[] {
+  const found: Comment[] = [];
+  const walker = document.createTreeWalker(document, NodeFilter.SHOW_COMMENT);
+  for (let node = walker.nextNode(); node; node = walker.nextNode()) {
+    if (isUnrevealed(node as Comment)) found.push(node as Comment);
+  }
+  return found;
+}
+
+/**
+ * Resolves once the document has finished parsing and no Suspense boundary of
+ * it is unrevealed.
+ *
+ * Parsing ends with the stream, but React reveals a streamed boundary in
+ * batches up to 300 ms later (Fizz's $RC marks it `$~` and reveals it from a
+ * timer), so the boundary is still pending at DOMContentLoaded. A transition
+ * then would make React client-render it over its server HTML.
+ *
+ * A reveal rewrites the same comment's data, or React removes the node; a
+ * boundary nested in revealed content joins the document only then, so it
+ * resolves only once a full walk finds none. Polls with setTimeout, not
+ * requestAnimationFrame: a hidden tab never runs rAF, which would hold late
+ * handle pushes and location state until the tab is shown again. A tab hidden
+ * from load still waits: Fizz reveals boundaries from a rAF-gated script.
+ */
+export function awaitDocumentRevealed(): Promise<void> {
+  return new Promise<void>((resolve) => {
+    const start = (): void => {
+      let pending = unrevealedBoundaries();
+      const check = (): void => {
+        pending = pending.filter(isUnrevealed);
+        if (pending.length === 0) pending = unrevealedBoundaries();
+        if (pending.length > 0) setTimeout(check, REVEAL_POLL_MS);
+        else resolve();
+      };
+      check();
+    };
+    if (document.readyState !== "loading") start();
+    else document.addEventListener("DOMContentLoaded", start, { once: true });
+  });
+}

package/src/browser/event-controller.ts

@@ -15,7 +15,7 @@ import {
   filterRouteSegmentIds,
 } from "./react/filter-segment-order.js";
 import { notifyListeners } from "./notify-listeners.js";
-import { cloneHandleData } from "./navigation-store.js";
+import { mergePartialHandleData } from "../handles/pushed-by.js";
 import {
   locationStateSnapshot,
   type LocationStateSnapshot,
@@ -223,7 +223,13 @@ export interface EventController {
     url: string,
     options?: NavigateOptionsInternal & { skipLoadingState?: boolean },
   ): NavigationHandle;
-  abortNavigation(): void;
+  /**
+   * Abort the pending navigation, and the committed one whose stream is
+   * still open. `pendingOnly` leaves the committed one alone: a page
+   * restored from the back/forward cache is not being left
+   * (navigation-bridge.ts handlePageShow).
+   */
+  abortNavigation(pendingOnly?: boolean): void;
 
   // Action operations
   startAction(
@@ -476,6 +482,14 @@ export function createEventController(
   config?: EventControllerConfig,
 ): EventController {
   let currentNavigation: NavigationEntry | null = null;
+  // The navigation that committed last, while its stream is still open. A
+  // newer navigation or a back/forward aborts it as it aborts one that has
+  // not committed: what a navigation does after its commit (the fill of a
+  // prefetch: false adoption, partial-update.ts fillHoles) reads its signal.
+  // The abort never cancels a response that has arrived (navigation-client.ts
+  // links a request to its signal only until then): the navigation stops
+  // reading it, and it streams to its end.
+  let streamingNavigation: AbortController | null = null;
 
   const inflightActions = new Map<string, ActionEntry>();
 
@@ -698,6 +712,7 @@ export function createEventController(
     options?: NavigateOptionsInternal & { skipLoadingState?: boolean },
   ): NavigationHandle {
     // Cancel existing navigation (switchMap semantics)
+    abortStreamingNavigation();
     if (currentNavigation) {
       currentNavigation.abort.abort();
       currentNavigation = null;
@@ -716,6 +731,7 @@ export function createEventController(
     notify();
 
     let completed = false;
+    let openStreams = 0;
 
     return {
       abort,
@@ -729,6 +745,7 @@ export function createEventController(
         let ended = false;
         entry.phase = "streaming";
         activeStreamCount++;
+        openStreams++;
         notify();
 
         return {
@@ -736,6 +753,9 @@ export function createEventController(
             if (ended) return;
             ended = true;
             activeStreamCount = Math.max(0, activeStreamCount - 1);
+            if (--openStreams === 0 && streamingNavigation === abort) {
+              streamingNavigation = null;
+            }
             notify();
           },
         };
@@ -746,6 +766,7 @@ export function createEventController(
           completed = true;
           location = newLocation;
           currentNavigation = null;
+          if (openStreams > 0) streamingNavigation = abort;
           notify();
         }
       },
@@ -764,7 +785,14 @@ export function createEventController(
     };
   }
 
-  function abortNavigation() {
+  function abortStreamingNavigation(): void {
+    const streaming = streamingNavigation;
+    streamingNavigation = null;
+    streaming?.abort();
+  }
+
+  function abortNavigation(pendingOnly?: boolean) {
+    if (!pendingOnly) abortStreamingNavigation();
     if (currentNavigation) {
       currentNavigation.abort.abort();
       currentNavigation = null;
@@ -1009,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();
         }
@@ -1061,35 +1092,18 @@ export function createEventController(
     const newRouteSegmentIds = filterRouteSegmentIds(rawMatched);
 
     if (isPartial && newSegmentOrder.length > 0) {
-      // Partial update: merge new data with existing, into a copy of the
-      // containers. The object a reader was handed is never written to: a
-      // history entry restored from the store's cache can be that object.
-      handleData = cloneHandleData(handleData);
-      for (const handleName of Object.keys(data)) {
-        if (!handleData[handleName]) {
-          handleData[handleName] = {};
-        }
-        for (const segmentId of Object.keys(data[handleName])) {
-          handleData[handleName][segmentId] = data[handleName][segmentId];
-        }
-      }
-      const resolvedIdSet =
-        resolvedIds && resolvedIds.length > 0 ? new Set(resolvedIds) : null;
-      // Cleanup pass:
-      //   a) segment dropped from the match list — delete its bucket.
-      //   b) segment was re-resolved this request but pushed nothing for
-      //      this handle — its previous bucket is stale.
-      // (a) is the existing behavior; (b) requires resolvedIds.
-      for (const handleName of Object.keys(handleData)) {
-        for (const segmentId of Object.keys(handleData[handleName])) {
-          const droppedFromMatch = !newSegmentOrder.includes(segmentId);
-          const reresolvedWithoutPush =
-            resolvedIdSet?.has(segmentId) && !data[handleName]?.[segmentId];
-          if (droppedFromMatch || reresolvedWithoutPush) {
-            delete handleData[handleName][segmentId];
-          }
-        }
-      }
+      // Partial update: a segment dropped from the match loses its buckets,
+      // and in each other bucket only the handler and loaders that ran for
+      // the response replace their pushes (#1103). Into new containers: a
+      // history entry restored from the store's cache can be the object a
+      // reader was handed.
+      handleData = mergePartialHandleData(
+        handleData,
+        data,
+        newSegmentOrder,
+        rawMatched,
+        resolvedIds,
+      );
     } else {
       // Full update: replace all data
       handleData = data;