@rangojs/router 0.33.0 → 0.33.2

package/dist/bin/{chunk-TTXC2U3G.js → chunk-YP4HENIU.js}

@@ -488,12 +488,15 @@ import {
 } from "react";
 
 // src/loader-store.ts
+var NO_ROUTE_DATA = /* @__PURE__ */ new Set();
 var EMPTY_SNAPSHOT = Object.freeze({
   value: void 0,
   hasValue: false,
   error: null,
   isLoading: false,
-  requestId: 0
+  requestId: 0,
+  valueFor: NO_ROUTE_DATA,
+  requestFor: NO_ROUTE_DATA
 });
 
 // src/client-urls/hoisted-revalidate.ts

package/dist/bin/{client-urls-projection-DQLWPDAT.js → client-urls-projection-J2BGDKQ4.js}

@@ -10,7 +10,7 @@ import {
   refreshRecordedClientUrlProjections,
   resolveClientUrlsSource,
   scanForClientUrlModules
-} from "./chunk-TTXC2U3G.js";
+} from "./chunk-YP4HENIU.js";
 import "./chunk-3B7CKBRO.js";
 import "./chunk-LD7UBHT4.js";
 export {

package/dist/bin/rango.js

@@ -229,7 +229,7 @@ ${formatNestedRouterConflictError(nestedRouterConflict, "[rango]")}
   }
   let discoverAndWriteRouteTypes;
   try {
-    const mod = await import("./runtime-discovery-CZ2QHT4Q.js");
+    const mod = await import("./runtime-discovery-O6KQ5KO2.js");
     discoverAndWriteRouteTypes = mod.discoverAndWriteRouteTypes;
   } catch (err) {
     if (err.code === "ERR_MODULE_NOT_FOUND" || err.code === "MODULE_NOT_FOUND") {

package/dist/bin/{runtime-discovery-CZ2QHT4Q.js → runtime-discovery-O6KQ5KO2.js}

@@ -163,9 +163,9 @@ async function discoverAndWriteRouteTypes(opts) {
       "Runtime discovery requires '@vitejs/plugin-rsc'. Install it with: pnpm add -D @vitejs/plugin-rsc"
     );
   }
-  const { createTempRscServer } = await import("./temp-rsc-server-QRR6HD6T.js");
+  const { createTempRscServer } = await import("./temp-rsc-server-BOHXBOR7.js");
   const { createDiscoveryState } = await import("./state-ACD2MGKJ.js");
-  const { discoverClientUrlProjections } = await import("./client-urls-projection-DQLWPDAT.js");
+  const { discoverClientUrlProjections } = await import("./client-urls-projection-J2BGDKQ4.js");
   const {
     isFrameworkPlugin,
     pickForwardedRunnerConfig,

package/dist/bin/{temp-rsc-server-QRR6HD6T.js → temp-rsc-server-BOHXBOR7.js}

@@ -27,7 +27,7 @@ import {
   propertyKeyIs,
   recordClientUrlsModule,
   unwrapExpression
-} from "./chunk-TTXC2U3G.js";
+} from "./chunk-YP4HENIU.js";
 import "./chunk-3B7CKBRO.js";
 import {
   codeMatchIndices,
@@ -47,7 +47,7 @@ var DEFAULT_ROUTER_VERSIONS_KEY = "*";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.33.0",
+  version: "0.33.2",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",

package/dist/testing/vitest.js

@@ -296,6 +296,11 @@ function rangoTestAliases(opts = {}) {
     {
       find: /^@vitejs\/plugin-rsc\/rsc(\/(server|client))?$/,
       replacement: here("src/testing/vitest-stubs/plugin-rsc.ts")
+    },
+    // useLoader().load() decodes renderRoute's loader answers through it.
+    {
+      find: /^@vitejs\/plugin-rsc\/browser$/,
+      replacement: here("src/testing/vitest-stubs/plugin-rsc-browser.ts")
     }
   ];
   if (rsdServerEdgePath) {

package/dist/types/browser/history-state.d.ts

@@ -1,3 +1,4 @@
+import { type LocationStateSnapshot } from "./react/location-state-shared.js";
 /**
  * Resolve navigation state - handles both LocationStateEntry[] and plain formats
  */
@@ -11,6 +12,26 @@ export declare function buildHistoryState(userState: unknown, routerState?: {
     intercept?: boolean;
     sourceUrl?: string;
 }, serverState?: Record<string, unknown>): Record<string, unknown> | null;
+/**
+ * The entry a commit onto the entry on screen writes (router.refresh(), the
+ * cross-tab refresh): `entryState`, read when the commit lands, keeps its
+ * location state. Its scroll key and idx go (pushHistoryWithIdx and
+ * ensureHistoryKey write them again), and its intercept marks are this
+ * commit's: a refresh renders the URL's full page. Server-set state merges
+ * over the kept state. A flash a reader already cleared from the entry stays
+ * cleared: the entry is copied, never rebuilt from what readers show.
+ */
+export declare function keptEntryState(entryState: unknown, routerState?: {
+    intercept?: boolean;
+    sourceUrl?: string;
+}, serverState?: Record<string, unknown>): Record<string, unknown> | null;
+/**
+ * What readers get from a commit onto the entry on screen: the state they
+ * show, plus the server's, recorded under the client's version. Not re-read
+ * from the entry, so a flash value on screen stays until the next navigation
+ * or back/forward.
+ */
+export declare function shownLocationState(shown: LocationStateSnapshot, serverState?: Record<string, unknown>): Record<string, unknown>;
 /** Check if a history state object contains location state keys. */
 export declare function hasLocationState(state: unknown): boolean;
 /**

package/dist/types/browser/navigation-transaction.d.ts

@@ -41,6 +41,8 @@ interface CommitOptions {
      * screen stays (EventController.commitLocationState).
      */
     treeless?: boolean;
+    /** Commits onto the entry on screen, keeping its location state (see keptEntryState). */
+    sameEntry?: boolean;
 }
 /**
  * Options that can override the pre-configured commit settings

package/dist/types/loader-store.d.ts

@@ -53,6 +53,14 @@ export interface LoaderEntry<T = unknown> {
     readonly isLoading: boolean;
     /** Identifies the request that produced this snapshot. 0 means "no request". */
     readonly requestId: number;
+    /**
+     * Route data (a route reader's `contextData`, by identity) of the readers on
+     * screen when `value` was requested. A route reader shows `value` only while
+     * its own route data is in this set.
+     */
+    readonly valueFor: ReadonlySet<unknown>;
+    /** The same for the latest request: `isLoading` and `error`. */
+    readonly requestFor: ReadonlySet<unknown>;
 }
 /**
  * Options for `subscribe`.
@@ -92,6 +100,8 @@ export interface SubscribeOptions {
      * its own lifecycle.
      */
     onStreamPending?: () => void;
+    /** The subscriber's committed route data. Route-context readers only. */
+    routeData?: () => unknown;
 }
 export declare class LoaderStore {
     private readonly entries;
@@ -172,7 +182,7 @@ export declare class LoaderStore {
      * error during the new request. Gated on `requestId === latestRequestId`
      * for symmetry with the other mutators.
      */
-    beginRequest(bucketKey: string, requestId: number): void;
+    beginRequest(bucketKey: string, requestId: number, initiatorRouteData?: () => unknown): void;
     /**
      * Commit a successful result. No-op if `requestId` is not the latest
      * (a newer `load()` was issued or `clear()` ran). Clearing `error` is

package/dist/types/testing/render-route.d.ts

@@ -45,6 +45,13 @@
  *     lane production's Back uses (useNavigation() idle), with the loader
  *     data current then. The prefetch request, its decode and the HTTP cache
  *     are e2e territory.
+ *   - useLoader().load() and a refreshGroup refresh reach the loader endpoint:
+ *     renderRoute answers a GET for `_rsc_loader=<id>` with the last value the
+ *     test gave that loader (the render seeds or respondToLoads()),
+ *     unencoded; a pending Promise holds the answer until it settles, and a
+ *     rejection is the loader's error. Needs the testing kit's
+ *     `@vitejs/plugin-rsc/browser` alias (rangoTestAliases). A load() with params
+ *     is answered with a loaderError; a body and non-GET loads are not answered.
  *   - A spec's transition({ when }) decides every commit with production's
  *     browser decision: navigate() and useRouter().push model kind "push",
  *     useRouter().replace kind "replace", refresh() kind "revalidate", and a
@@ -428,8 +435,10 @@ export interface TestRouterHandle {
     /**
      * Re-render the current location, as router.refresh() does: a spec's
      * transition({ when }) decides it with kind "revalidate" (`to` is `from`).
+     * `options.loaders` is the loader data the response carries, merged over
+     * the render-time seeds as in navigate().
      */
-    refresh(): Promise<void>;
+    refresh(options?: Pick<RenderRouteOptions, "loaders">): Promise<void>;
     /**
      * Prefetch `url`, as a `<Link>` hover or viewport trigger does: the page is
      * kept with the loader data its response would carry now (the render-time
@@ -469,6 +478,17 @@ export interface TestRouterHandle {
     action(options?: Pick<RenderRouteOptions, "loaders"> & {
         keepClientCache?: boolean;
     }): Promise<void>;
+    /**
+     * Set what the loader endpoint answers from now on: a later
+     * `useLoader().load()` or refreshGroup refresh of each loader resolves to
+     * its value (a pending Promise holds the answer, a rejection is the
+     * loader's error). Renders nothing; the page on screen keeps its data.
+     *
+     * @example
+     * router.respondToLoads({ loaders: [[CartLoader, { count: 3 }]] });
+     * fireEvent.click(getByText("Refresh")); // load(): count 3
+     */
+    respondToLoads(options: Pick<RenderRouteOptions, "loaders">): void;
     /**
      * The background revalidations a click on a stale prefetch started, in
      * order: the page's pathname and search, and the segment ids the request

package/dist/types/testing/vitest-stubs/plugin-rsc-browser.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Stub for `@vitejs/plugin-rsc/browser`, shipped so consumers do not have to
+ * write a per-file `vi.mock(...)`. The real entry imports the
+ * `virtual:vite-rsc/client-references` Vite virtual at the top level, which a
+ * bare Vitest process cannot resolve.
+ *
+ * The router reaches this module from `useLoader().load()` and a
+ * `refreshGroup` refresh (use-loader.tsx imports deps/browser.ts lazily).
+ * renderRoute answers those requests (render-route.tsx), and a DOM test has
+ * no Flight server to encode an answer: renderRoute's seeds are client values
+ * already. So the answer travels with its Response object, and
+ * `createFromFetch` hands it back unchanged, as a decoded payload. Any other
+ * response is rejected. The remaining exports exist for the re-export in
+ * deps/browser.ts; navigations, actions and the document are not decoded
+ * here.
+ */
+/**
+ * A loader endpoint Response whose decoded payload is `payload`
+ * (`{ loaderResult }` or `{ loaderResult: null, loaderError }`, as
+ * rsc/loader-fetch.ts answers).
+ */
+export declare function loaderAnswerResponse(payload: {
+    loaderResult: unknown;
+    loaderError?: {
+        message: string;
+        name: string;
+    };
+}): Response;
+export declare function createFromFetch<T>(response: Promise<Response> | Response): Promise<T>;
+export declare const createFromReadableStream: () => Promise<never>;
+export declare const encodeReply: () => Promise<never>;
+export declare const setServerCallback: () => void;
+export declare const createTemporaryReferenceSet: () => unknown;

package/dist/vite/index.js

@@ -5203,12 +5203,15 @@ import {
 } from "react";
 
 // src/loader-store.ts
+var NO_ROUTE_DATA = /* @__PURE__ */ new Set();
 var EMPTY_SNAPSHOT = Object.freeze({
   value: void 0,
   hasValue: false,
   error: null,
   isLoading: false,
-  requestId: 0
+  requestId: 0,
+  valueFor: NO_ROUTE_DATA,
+  requestFor: NO_ROUTE_DATA
 });
 
 // src/router/route-trie-builder.ts
@@ -7327,7 +7330,7 @@ function resolveVersionsFrom(table, routerId2) {
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.33.0",
+  version: "0.33.2",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.33.0",
+  "version": "0.33.2",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",

package/skills/app-structure/SKILL.md

@@ -120,6 +120,13 @@ here for the rules they share.
    by name, keep page-specific blocks in their route, and write such a rule
    for chrome that shows a param's data
    ([Prefetches are shared](#prefetches-are-shared)).
+10. **A layout keeps its `<Outlet />` in one place.** Branch inside one shape
+    (`<>{promo ? <Banner /> : null}<Outlet /></>`), never between a bare
+    `return <Outlet />` and a wrapped one: the outlet moves, and every page
+    below remounts when the branch flips, its state reset and its mount
+    effects run again. When an early return is unavoidable and the other
+    branch is only a fragment, give the outlet the same `key` in both
+    (`/layout`, "Moving the Outlet remounts its children").
 
 ## A small app: one module
 

package/skills/app-structure/large-app.md

@@ -893,6 +893,9 @@ stay inside the project module can come from `useReverse(routes)` in
   user's name): the capture is refused and the page never serves a shell.
 - **`prefetch: false` on every loader**: each click then waits for a fill.
   Flag the expensive, rarely-clicked ones.
+- **A layout that moves its `<Outlet />` between branches** (a bare
+  `return <Outlet />` on one, a wrapped one on another): every page below it
+  remounts when the branch flips. Keep one shape (`/layout`).
 - **A bare `isAction(refs)` predicate**: it is a hard `false` on navigation
   too, so the loader stops following param changes. Use
   `isAction() ? isAction(refs) : undefined` (`/loader`).

package/skills/client-urls/SKILL.md

@@ -745,6 +745,17 @@ a hard load of the target URL renders the full route.
   throwers in the client `ErrorBoundary`; `useFetchLoader` works unchanged
   (route-independent lane; `revalidate()` deliberately not consulted).
   Pinned in the router repo's client-urls hook-probe e2e.
+- **An action called on the optimistic frame runs against the committed
+  page.** The destination mounts at the click, before the navigation
+  commits, so an action its mount effect calls is sent from the page the URL
+  bar still shows: the server runs it with that page's request context
+  (`ctx.url`, `ctx.params`, its middleware) and re-renders that page, not
+  the destination. Nothing of that render reaches the destination, and a
+  write still refreshes the destination once it commits (unless the action
+  called `keepClientCache()`). Pass what the action needs as arguments
+  instead of reading the request's URL or params. A link prefetched before
+  the click (the production default, `viewport`) usually commits before the
+  effect runs.
 - **Location state follows the same split as the route hooks.** Inside the
   optimistic branch (the destination and the group's client layouts)
   `useLocationState` reads the state the navigation carries (`<Link state>`,

package/skills/hooks/data.md

@@ -200,6 +200,11 @@ shared value lives as long as at least one component using that key is mounted.
 A persistent component (e.g. a header) keeps the value across navigations; a
 route-scoped component's value is reclaimed when it unmounts. Registered-loader
 reads (keyed or not) reset on navigation from fresh route data, as before.
+A refreshed value belongs to the route data of the readers on screen when
+`load()` was called: a reader that mounts on another page or on a new visit,
+or that a navigation brings new route data, shows that route data from its
+first frame, and a `load()` still in flight when you leave lands on no other
+page; Back onto the refreshed page shows the refresh again.
 
 **Refreshing multiple loaders together (`refreshGroup` + `useRefreshLoaders`)**:
 

package/skills/hooks/outlets.md

@@ -28,6 +28,10 @@ function DashboardLayout() {
 `ParallelOutlet` requires the name and reads clearer at the call site. See
 `/layout` and `/parallel` for the server side.
 
+An outlet that moves between a layout's branches (bare in one, wrapped in
+another) remounts its children; see `/layout`, "Moving the Outlet remounts its
+children".
+
 ### useOutlet()
 
 Access outlet content and its client-route presentation state programmatically:

package/skills/hooks/state.md

@@ -96,16 +96,17 @@ reads the entry on screen, not the one `history.state` already holds.
 Back/forward and state the server sets on a navigation
 (`ctx.setLocationState()`, `redirect(url, { state })`) follow the same rule.
 
-| What changes the state                                       | A reader gets it                                                 |
-| ------------------------------------------------------------ | ---------------------------------------------------------------- |
-| `<Link state>`, `router.push()` / `router.replace()`         | in the commit that shows the destination                         |
-| back/forward                                                 | in the commit that restores the entry (cached or refetched)      |
-| the server, on a navigation (`setLocationState`, a redirect) | in the commit that shows the destination                         |
-| the server, on a document load (a page load, a no-JS post)   | once the page has hydrated, as stored state                      |
-| a navigation the server answers with nothing to re-render    | with the new location: the page on screen is the entry's         |
-| `router.push(url, { revalidate: false })` (no server fetch)  | with the new location: the page does not change                  |
-| a server action's `setLocationState` (no navigation)         | when the action's response arrives, added to what readers show   |
-| `Def.write()` / `Def.delete()`                               | when the entry is next restored: back/forward to it, or a reload |
+| What changes the state                                          | A reader gets it                                                                         |
+| --------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| `<Link state>`, `router.push()` / `router.replace()`            | in the commit that shows the destination                                                 |
+| back/forward                                                    | in the commit that restores the entry (cached or refetched)                              |
+| the server, on a navigation (`setLocationState`, a redirect)    | in the commit that shows the destination                                                 |
+| the server, on a document load (a page load, a no-JS post)      | once the page has hydrated, as stored state                                              |
+| a navigation the server answers with nothing to re-render       | with the new location: the page on screen is the entry's                                 |
+| `router.push(url, { revalidate: false })` (no server fetch)     | with the new location: the page does not change                                          |
+| a server action's `setLocationState` (no navigation)            | when the action's response arrives, added to what readers show                           |
+| `router.refresh()`, or another tab's action refreshing this one | in the commit that shows the refreshed page: what readers show, plus what the server set |
+| `Def.write()` / `Def.delete()`                                  | when the entry is next restored: back/forward to it, or a reload                         |
 
 Three consequences:
 
@@ -260,7 +261,8 @@ and hydrating, so SSR and hydration agree), then clears it from `history.state`
 `replaceState` in a `useEffect`. Every component reading the same flash
 definition sees the value, whenever it mounts, until the next navigation or
 back/forward commits its entry's state: an entry that carries no flash shows
-none. A server action's state does not end it. Pressing back/forward will not
+none. A server action's state does not end it, nor a refresh, which keeps it
+on screen without writing it back to the entry. Pressing back/forward will not
 re-show the flash since it was cleared.
 
 Set flash state from the server via `redirect()` with state (from a handler,

package/skills/layout/SKILL.md

@@ -12,6 +12,12 @@ layout stays mounted while you navigate between the routes it wraps. This skill
 covers layout forms, outlets, orphan layouts (a layout inside a `path()`), and
 layout revalidation.
 
+**Rule: a layout keeps its `<Outlet />` in one place on every branch.** Branch
+around the outlet, never around it and the outlet together: an early
+`return <Outlet />` beside a wrapped one remounts every child segment each time
+the branch flips (state resets, mount effects and the actions they call run
+again). See [Moving the Outlet remounts its children](#moving-the-outlet-remounts-its-children).
+
 Related skills: `/parallel` (named slots rendered by a layout), `/intercept`
 (modal slots), `/route` (the routes a layout wraps), `/router-setup` (the
 `document` shell that renders `<html>`).
@@ -131,6 +137,49 @@ function ShopLayout() {
 
 A layout's `transition()` config wraps the content that flows through `<Outlet />` — not the layout chrome itself, and not sibling `<ParallelOutlet />` slots. Stacking transitions across nested layouts collapses around the deepest default outlet content. See [skills/view-transitions](../view-transitions/SKILL.md) for the full wrap rules and intercept-modal interaction.
 
+### Moving the Outlet remounts its children
+
+React keeps a subtree mounted only while each element on its path keeps the
+same type at the same position. A layout that returns a bare `<Outlet />` on
+one branch and wraps it on another (a fragment, a `<div>`) moves the outlet,
+so when the branch flips, every child segment unmounts and mounts again:
+client state resets, mount effects run again (an action they call is sent
+again), and the content flashes. Prefer one shape with the branch inside it:
+
+```tsx
+// Remounts the children whenever `promo` flips
+function CategoryLayout({ promo }: { promo: boolean }) {
+  if (!promo) return <Outlet />;
+  return (
+    <>
+      <PromoBanner />
+      <Outlet />
+    </>
+  );
+}
+
+// Keeps them mounted: the outlet keeps its position
+function CategoryLayout({ promo }: { promo: boolean }) {
+  return (
+    <>
+      {promo ? <PromoBanner /> : null}
+      <Outlet />
+    </>
+  );
+}
+```
+
+A stable `key` on the outlet (`<Outlet key="outlet" />` in both branches)
+also keeps the children mounted when the only difference is a top-level
+fragment: React reads a component's unkeyed top-level fragment as a list of
+siblings and matches the keyed outlet across it. It does not help when one
+branch wraps the outlet in an element (a `<div>`, a provider): the outlet then
+sits one level deeper, and keys match only among siblings.
+
+All of this applies to `<ParallelOutlet />` too. To reset the children on
+purpose, change a `key` on a stable wrapper rather than relying on a shape
+change.
+
 ## Named Outlets
 
 For parallel routes, use named outlets (`<Outlet name="@sidebar" />` is

package/skills/testing/SKILL.md

@@ -101,6 +101,7 @@ Each primitive links to its sub-file (API + recipe + caveats).
 | a handle's `collect`/accumulator, a seeded handle read, or a loader handle write                                                   | unit         | [`collectHandle` / seeded `handles` / `handlePushes`](./handles.md)                                                   | `@rangojs/router/testing`        |
 | a CLIENT component reading router context (`useParams`/`useReverse`/`Outlet`/`useNavigation`/`useLoader`)                          | unit (DOM)   | [`renderRoute`](./client-components.md)                                                                               | `@rangojs/router/testing/dom`    |
 | a stale indicator from `useLoader().isLoading` while a `transition()` navigation re-runs the loader                                | unit (DOM)   | [`renderRoute` + `navigate(url, { loaders })`](./client-components.md#held-navigation)                                | `@rangojs/router/testing/dom`    |
+| a component that refreshes with `useLoader().load()` or `useRefreshLoaders()`, and the readers that show the answer                | unit (DOM)   | [`renderRoute` + `router.respondToLoads`](./client-components.md#load-and-refresh-groups)                             | `@rangojs/router/testing/dom`    |
 | a component reading `useLocationState(Def)` after `router.push(url, { state: [Def(value)] })`                                      | unit (DOM)   | [`renderRoute` + `withLocationStateKey`](./client-components.md#location-state)                                       | `@rangojs/router/testing[/dom]`  |
 | location state while a navigation is pending (a loader the test holds), or after a back/forward                                    | unit (DOM)   | [`navigate(url, { state, loaders })`, a `popstate` event](./client-components.md#state-while-a-navigation-is-pending) | `@rangojs/router/testing[/dom]`  |
 | a CLIENT component's hydration: its first client render against its own server HTML (`typeof window`, a late `<Suspense>`)         | unit (DOM)   | [`renderRoute` + `hydrate: true`](./client-components.md#hydration)                                                   | `@rangojs/router/testing/dom`    |

package/skills/testing/client-components.md

@@ -33,23 +33,23 @@
 
 ### Context — client hooks it makes resolve (what your code receives)
 
-| Hook                           | Meaning                                                                                       |
-| ------------------------------ | --------------------------------------------------------------------------------------------- |
-| `useParams`                    | Params from the matched leaf pattern, with `options.params` merged over.                      |
-| `useReverse`                   | Reverse a name->pattern map to a URL; merges `useParams()` and the `mount`/`basename` prefix. |
-| `useHref`                      | Resolve an href against the mount/basename.                                                   |
-| `useMount`                     | The `include()` mount prefix (`options.mount`), else `"/"`.                                   |
-| `useNavigation`                | Navigation controller state: `loading` from a `navigate()` call to its commit, else `idle`.   |
-| `useRouter`                    | The router handle, including `.basename`.                                                     |
-| `usePathname`                  | Current committed pathname.                                                                   |
-| `useSearchParams`              | Search params from the `request` URL.                                                         |
-| `useNonce`                     | SEEDED CSP nonce (`options.nonce`), else `undefined` (the browser default).                   |
-| `useLoader` / `useFetchLoader` | SEEDED loader data (read path, not run path). Held-navigation `isLoading` is modeled (below). |
-| `useLocationState`             | SEEDED `history.state` value, or the `state` a navigation or a `popstate` brought (below).    |
-| `useHandle`                    | SEEDED handle output (globally accumulated).                                                  |
-| `Outlet`                       | Renders the next segment in the chain (layout nesting).                                       |
-| `useOutlet`                    | Next-segment `content` plus SEEDED `options.outletPending`.                                   |
-| `useTheme`                     | Theme; throws without `options.theme` (see caveat).                                           |
+| Hook                           | Meaning                                                                                                                                                                       |
+| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `useParams`                    | Params from the matched leaf pattern, with `options.params` merged over.                                                                                                      |
+| `useReverse`                   | Reverse a name->pattern map to a URL; merges `useParams()` and the `mount`/`basename` prefix.                                                                                 |
+| `useHref`                      | Resolve an href against the mount/basename.                                                                                                                                   |
+| `useMount`                     | The `include()` mount prefix (`options.mount`), else `"/"`.                                                                                                                   |
+| `useNavigation`                | Navigation controller state: `loading` from a `navigate()` call to its commit, else `idle`.                                                                                   |
+| `useRouter`                    | The router handle, including `.basename`.                                                                                                                                     |
+| `usePathname`                  | Current committed pathname.                                                                                                                                                   |
+| `useSearchParams`              | Search params from the `request` URL.                                                                                                                                         |
+| `useNonce`                     | SEEDED CSP nonce (`options.nonce`), else `undefined` (the browser default).                                                                                                   |
+| `useLoader` / `useFetchLoader` | SEEDED loader data (read path, not run path). Held-navigation `isLoading` is modeled (below), and `load()` is answered from the seeds ([`load()`](#load-and-refresh-groups)). |
+| `useLocationState`             | SEEDED `history.state` value, or the `state` a navigation or a `popstate` brought (below).                                                                                    |
+| `useHandle`                    | SEEDED handle output (globally accumulated).                                                                                                                                  |
+| `Outlet`                       | Renders the next segment in the chain (layout nesting).                                                                                                                       |
+| `useOutlet`                    | Next-segment `content` plus SEEDED `options.outletPending`.                                                                                                                   |
+| `useTheme`                     | Theme; throws without `options.theme` (see caveat).                                                                                                                           |
 
 ### Returns — `RenderRouteResult`
 
@@ -77,8 +77,11 @@ type RenderRouteResult = RenderResult & {
       },
     ): Promise<void>;
     // re-render the current location, as router.refresh() does:
-    // a spec's when gets kind "revalidate" (`to` is `from`)
-    refresh(): Promise<void>;
+    // a spec's when gets kind "revalidate" (`to` is `from`); `loaders` is the
+    // data the response carries
+    refresh(options?: {
+      loaders?: ReadonlyArray<readonly [LoaderDefinition<any>, unknown]>;
+    }): Promise<void>;
     // keep `url` as a prefetch made now carries it (the seeds then, `loaders`
     // over them); a later navigate(url) without `loaders` commits that data
     prefetch(
@@ -94,6 +97,11 @@ type RenderRouteResult = RenderResult & {
       loaders?: ReadonlyArray<readonly [LoaderDefinition<any>, unknown]>;
       keepClientCache?: boolean;
     }): Promise<void>;
+    // what a later useLoader().load() (or refreshGroup refresh) of each
+    // loader resolves to; renders nothing
+    respondToLoads(options: {
+      loaders?: ReadonlyArray<readonly [LoaderDefinition<any>, unknown]>;
+    }): void;
     pathname(): string;
     params(): Record<string, string>;
     store: NavigationStore; // advanced
@@ -454,6 +462,46 @@ it("dims the held price while the next product streams", async () => {
 - Pass settled data as a plain value, not `Promise.resolve(value)`: React has not observed a plain promise yet, so it counts as pending and renders one `stale` frame. (A Flight chunk that has already settled carries its status and is skipped, which a plain value mirrors.)
 - `loading()` is not a spec field: a `<Suspense>` in your layout component stands in for it.
 
+## `load()` and refresh groups
+
+`useLoader().load()`, `useFetchLoader().load()` and a `useRefreshLoaders()` refresh reach renderRoute's loader endpoint, so a refresh button, a polling component, or a value one reader refreshes and another shows is unit-testable without a server or a `fetch` stub. The endpoint answers a GET for a loader with the last value the test gave it: the render-time `loaders`/`loaderData`, or `router.respondToLoads({ loaders })`, which only sets the answer (a `navigate()`, `prefetch()`, `action()` or `refresh()` seeds the page it commits, not the answer). A `load({ params })` is answered with a `loaderError`. The value is read when `load()` sends its request. A pending Promise holds the answer until it settles (`isLoading` stays `true`), and a rejected one arrives as the loader's error. The value reaches the component as given, never serialized.
+
+The answer decodes through `@vitejs/plugin-rsc/browser`, which `rangoTestAliases()` (and `rangoTestConfig()`) alias to the testing kit's stub; remove any `vi.mock("@vitejs/plugin-rsc/browser")` you wrote for it.
+
+```tsx
+import { fireEvent, waitFor } from "@testing-library/react";
+import { renderRoute } from "@rangojs/router/testing/dom";
+import { useLoader } from "@rangojs/router/client";
+import { CartLoader } from "../src/loaders"; // createLoader(fn, true)
+
+function CartBadge() {
+  const { data, load, isLoading } = useLoader(CartLoader);
+  return (
+    <button data-testid="cart" onClick={() => load()}>
+      {isLoading ? "..." : data.count}
+    </button>
+  );
+}
+
+it("refreshes the count from the server", async () => {
+  const { getByTestId, router } = await renderRoute(
+    [{ path: "/cart", Component: CartBadge }],
+    { request: "/cart", loaders: [[CartLoader, { count: 1 }]] },
+  );
+  router.respondToLoads({ loaders: [[CartLoader, { count: 3 }]] });
+  fireEvent.click(getByTestId("cart"));
+  // load() loads its decoder lazily: wait for the answer, not one act()
+  await waitFor(() => expect(getByTestId("cart").textContent).toBe("3"));
+});
+```
+
+| `load()` call                                                 | Under `renderRoute`                                                                                                                                                                                                    |
+| ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `load()` with no options, a `key`, or a `refreshGroup`        | Answered. Readers of a registered loader converge on the value; a reader that mounts later, or that a navigation brings new route data, shows that route data instead, as in production.                               |
+| `load({ params })`, `load({ method: "POST", body })`          | NOT answered: the request goes to the `fetch` your test environment has. Test the loader body with `runLoader`, and the round trip at e2e.                                                                             |
+| A loader the test never gave a value                          | Answered with an error naming the loader (`error` set; `throwOnError` throws it).                                                                                                                                      |
+| Any other request (a navigation's or action's Flight payload) | Passed through to the `fetch` installed before the mount. renderRoute never decodes one: a `navigate()` or `action()` seeds its data directly. A `fetch` stub the test installs after the mount replaces the endpoint. |
+
 ## Caveats
 
 - Client tree ONLY. Does NOT catch server/client boundary reference-identity remount bugs, real Flight serialization errors, loader execution, middleware, or handler ordering — those are `renderServerTree` / `renderHandler` / e2e territory. Loader data is SEEDED, never run. `hydrate: true` adds an HTML pass of this same client tree ([Hydration](#hydration)), not a render of your routes on a server.

package/skills/ux-architecture/SKILL.md

@@ -941,7 +941,9 @@ Each entry: what the user sees, why, the fix.
 8. **Shared chrome in a route component.** It remounts on every navigation to
    another route: its state resets and its own fallbacks show again. Fix: move
    it into a `layout()` (a group `layout()` keeps its instance across its
-   routes; a server layout across everything below it).
+   routes; a server layout across everything below it). A layout that moves
+   its `<Outlet />` between branches remounts the children the same way; see
+   `/layout`, "Moving the Outlet remounts its children".
 9. **`useEffect` fetching.** A spinner after the page has shown, nothing
    prefetched or server-rendered, no re-run after an action, races on fast
    navigations. Fix: a loader read with `useLoader`; `useFetchLoader` for

package/src/browser/history-state.ts

@@ -8,6 +8,7 @@ import {
   replaceCurrentHistoryState,
   resolveLocationStateEntries,
   stampLocationState,
+  type LocationStateSnapshot,
 } from "./react/location-state-shared.js";
 import { WIRE } from "../wire-params.js";
 
@@ -110,6 +111,53 @@ export function buildHistoryState(
   return Object.keys(result).length > 0 ? result : null;
 }
 
+/**
+ * The entry a commit onto the entry on screen writes (router.refresh(), the
+ * cross-tab refresh): `entryState`, read when the commit lands, keeps its
+ * location state. Its scroll key and idx go (pushHistoryWithIdx and
+ * ensureHistoryKey write them again), and its intercept marks are this
+ * commit's: a refresh renders the URL's full page. Server-set state merges
+ * over the kept state. A flash a reader already cleared from the entry stays
+ * cleared: the entry is copied, never rebuilt from what readers show.
+ */
+export function keptEntryState(
+  entryState: unknown,
+  routerState?: { intercept?: boolean; sourceUrl?: string },
+  serverState?: Record<string, unknown>,
+): Record<string, unknown> | null {
+  let result: Record<string, unknown> =
+    entryState !== null && typeof entryState === "object"
+      ? { ...entryState }
+      : {};
+  delete result.key;
+  delete result.idx;
+  delete result.intercept;
+  delete result.sourceUrl;
+  if (routerState?.intercept) {
+    result.intercept = true;
+    if (routerState.sourceUrl) result.sourceUrl = routerState.sourceUrl;
+  }
+  if (serverState && Object.keys(serverState).length > 0) {
+    result = addLocationState(result, serverState);
+  }
+  return Object.keys(result).length > 0 ? result : null;
+}
+
+/**
+ * What readers get from a commit onto the entry on screen: the state they
+ * show, plus the server's, recorded under the client's version. Not re-read
+ * from the entry, so a flash value on screen stays until the next navigation
+ * or back/forward.
+ */
+export function shownLocationState(
+  shown: LocationStateSnapshot,
+  serverState?: Record<string, unknown>,
+): Record<string, unknown> {
+  const result: Record<string, unknown> = { ...shown, ...serverState };
+  stampLocationState(result);
+  return result;
+}
+
 /** Check if a history state object contains location state keys. */
 export function hasLocationState(state: unknown): boolean {
   if (!state || typeof state !== "object") return false;

package/src/browser/navigation-bridge.ts

@@ -769,7 +769,12 @@ export function createNavigationBridge(
           [],
           false,
           tx.handle.signal,
-          tx.with({ url: window.location.href, replace: true, scroll: false }),
+          tx.with({
+            url: window.location.href,
+            replace: true,
+            scroll: false,
+            sameEntry: true,
+          }),
           { type: "navigate", refresh: true, boundary: shown[at]?.id },
         );
       } catch (error) {

package/src/browser/navigation-transaction.ts

@@ -17,8 +17,10 @@ import type { EventController, NavigationHandle } from "./event-controller.js";
 import { debugLog } from "./logging.js";
 import {
   buildHistoryState,
+  keptEntryState,
   mergeLocationState,
   pushHistoryWithIdx,
+  shownLocationState,
 } from "./history-state.js";
 
 export { resolveNavigationState } from "./history-state.js";
@@ -67,6 +69,8 @@ interface CommitOptions {
    * screen stays (EventController.commitLocationState).
    */
   treeless?: boolean;
+  /** Commits onto the entry on screen, keeping its location state (see keptEntryState). */
+  sameEntry?: boolean;
 }
 
 /**
@@ -227,16 +231,20 @@ export function createNavigationTransaction(
       return { scroll: { enabled: scroll } };
     }
 
-    const historyState = buildHistoryState(
-      opts.state,
-      { intercept, sourceUrl: interceptSourceUrl },
-      serverState,
-    );
+    const marks = { intercept, sourceUrl: interceptSourceUrl };
+    const historyState = opts.sameEntry
+      ? keptEntryState(window.history.state, marks, serverState)
+      : buildHistoryState(opts.state, marks, serverState);
 
     pushHistoryWithIdx(historyState, url, replace ?? false);
     ensureHistoryKey();
     store.rememberDisplayedEntry(opts.metadata);
-    eventController.commitLocationState(historyState, opts.treeless);
+    eventController.commitLocationState(
+      opts.sameEntry
+        ? shownLocationState(eventController.getLocationState(), serverState)
+        : historyState,
+      opts.treeless,
+    );
 
     handle.complete(parsedUrl);
 

package/src/browser/server-action-bridge.ts

@@ -885,14 +885,19 @@ export function createServerActionBridge(
         throw new Error("No matched segments in response");
       }
 
-      // Reconcile server segments with cached segments (single source of truth)
-      const reconciled = reconcileSegments({
-        actor: "action",
-        matched,
-        diff: diff || [],
-        serverSegments: segments || [],
-        cachedSegments,
-      });
+      // Reconcile server segments with cached segments (single source of
+      // truth). A page that left commits nothing (navigated-away), and the
+      // cache on screen is another page's: reconciling would report missing
+      // segments.
+      const reconciled = navigatedSince()
+        ? { segments: [], mainSegments: [], interceptSegments: [] }
+        : reconcileSegments({
+            actor: "action",
+            matched,
+            diff: diff || [],
+            serverSegments: segments || [],
+            cachedSegments,
+          });
       const fullSegments = reconciled.segments;
 
       const returnData = returnValue?.data;

package/src/loader-store.ts

@@ -58,14 +58,26 @@ export interface LoaderEntry<T = unknown> {
   readonly isLoading: boolean;
   /** Identifies the request that produced this snapshot. 0 means "no request". */
   readonly requestId: number;
+  /**
+   * Route data (a route reader's `contextData`, by identity) of the readers on
+   * screen when `value` was requested. A route reader shows `value` only while
+   * its own route data is in this set.
+   */
+  readonly valueFor: ReadonlySet<unknown>;
+  /** The same for the latest request: `isLoading` and `error`. */
+  readonly requestFor: ReadonlySet<unknown>;
 }
 
+const NO_ROUTE_DATA: ReadonlySet<unknown> = new Set();
+
 const EMPTY_SNAPSHOT: LoaderEntry = Object.freeze({
   value: undefined,
   hasValue: false,
   error: null,
   isLoading: false,
   requestId: 0,
+  valueFor: NO_ROUTE_DATA,
+  requestFor: NO_ROUTE_DATA,
 });
 
 /**
@@ -106,6 +118,8 @@ export interface SubscribeOptions {
    * its own lifecycle.
    */
   onStreamPending?: () => void;
+  /** The subscriber's committed route data. Route-context readers only. */
+  routeData?: () => unknown;
 }
 
 interface InternalEntry {
@@ -139,6 +153,7 @@ interface InternalEntry {
   refetch: (() => Promise<void>) | undefined;
   /** Subscribers' `onStreamPending` callbacks (see SubscribeOptions). */
   streamPendingListeners: Set<() => void>;
+  routeDataSources: Set<() => unknown>;
 }
 
 /**
@@ -188,6 +203,7 @@ export class LoaderStore {
         groups: new Map(),
         refetch: undefined,
         streamPendingListeners: new Set(),
+        routeDataSources: new Set(),
       };
       this.entries.set(bucketKey, e);
     }
@@ -234,9 +250,12 @@ export class LoaderStore {
     e.listeners.add(cb);
     const onStreamPending = options?.onStreamPending;
     if (onStreamPending) e.streamPendingListeners.add(onStreamPending);
+    const routeData = options?.routeData;
+    if (routeData) e.routeDataSources.add(routeData);
     return () => {
       e.listeners.delete(cb);
       if (onStreamPending) e.streamPendingListeners.delete(onStreamPending);
+      if (routeData) e.routeDataSources.delete(routeData);
       // Group membership is refcounted per subscriber so refreshGroups() never
       // fetches for an unmounted reader, and a bucket shared by subscribers in
       // different groups stays in each group until ALL of that group's
@@ -414,16 +433,30 @@ export class LoaderStore {
    * error during the new request. Gated on `requestId === latestRequestId`
    * for symmetry with the other mutators.
    */
-  beginRequest(bucketKey: string, requestId: number): void {
+  beginRequest(
+    bucketKey: string,
+    requestId: number,
+    initiatorRouteData?: () => unknown,
+  ): void {
     const e = this.entries.get(bucketKey);
     if (!e || requestId !== e.latestRequestId) return;
-    if (e.snapshot.isLoading && e.snapshot.error === null) return;
+    const requestFor = new Set<unknown>();
+    if (initiatorRouteData) requestFor.add(initiatorRouteData());
+    for (const read of e.routeDataSources) requestFor.add(read());
+    const prev = e.snapshot;
+    if (
+      prev.isLoading &&
+      prev.error === null &&
+      [...requestFor].every((d) => prev.requestFor.has(d))
+    ) {
+      return;
+    }
     e.snapshot = Object.freeze({
-      value: e.snapshot.value,
-      hasValue: e.snapshot.hasValue,
+      ...prev,
       error: null,
       isLoading: true,
       requestId,
+      requestFor,
     });
     this.notify(e);
   }
@@ -442,6 +475,8 @@ export class LoaderStore {
       error: null,
       isLoading: false,
       requestId,
+      valueFor: e.snapshot.requestFor,
+      requestFor: e.snapshot.requestFor,
     });
     this.notify(e);
     this.dropIfSettled(bucketKey, e);
@@ -461,6 +496,8 @@ export class LoaderStore {
       error,
       isLoading: false,
       requestId,
+      valueFor: e.snapshot.valueFor,
+      requestFor: e.snapshot.requestFor,
     });
     this.notify(e);
     this.dropIfSettled(bucketKey, e);

package/src/testing/render-route.tsx

@@ -45,6 +45,13 @@
  *     lane production's Back uses (useNavigation() idle), with the loader
  *     data current then. The prefetch request, its decode and the HTTP cache
  *     are e2e territory.
+ *   - useLoader().load() and a refreshGroup refresh reach the loader endpoint:
+ *     renderRoute answers a GET for `_rsc_loader=<id>` with the last value the
+ *     test gave that loader (the render seeds or respondToLoads()),
+ *     unencoded; a pending Promise holds the answer until it settles, and a
+ *     rejection is the loader's error. Needs the testing kit's
+ *     `@vitejs/plugin-rsc/browser` alias (rangoTestAliases). A load() with params
+ *     is answered with a loaderError; a body and non-GET loads are not answered.
  *   - A spec's transition({ when }) decides every commit with production's
  *     browser decision: navigate() and useRouter().push model kind "push",
  *     useRouter().replace kind "replace", refresh() kind "revalidate", and a
@@ -128,14 +135,18 @@ import {
   buildHistoryState,
   applyDocumentLocationState,
   clearLocationStateOnDocumentLoad,
+  keptEntryState,
   pushHistoryWithIdx,
   resolveNavigationState,
+  shownLocationState,
 } from "../browser/history-state.js";
 import { withLocationStateKey } from "./location-state-key.js";
 import type { Handle } from "../handle.js";
 import type { ThemeConfig } from "../theme/types.js";
 import { resolveThemeConfig } from "../theme/constants.js";
 import { isUnderTestRunner } from "../runtime-env.js";
+import { loaderAnswerResponse } from "./vitest-stubs/plugin-rsc-browser.js";
+import { WIRE } from "../wire-params.js";
 import {
   scheduleStalePrefetchRevalidation,
   setupNavigationBridgeDelegatedPrefetch,
@@ -532,8 +543,10 @@ export interface TestRouterHandle {
   /**
    * Re-render the current location, as router.refresh() does: a spec's
    * transition({ when }) decides it with kind "revalidate" (`to` is `from`).
+   * `options.loaders` is the loader data the response carries, merged over
+   * the render-time seeds as in navigate().
    */
-  refresh(): Promise<void>;
+  refresh(options?: Pick<RenderRouteOptions, "loaders">): Promise<void>;
   /**
    * Prefetch `url`, as a `<Link>` hover or viewport trigger does: the page is
    * kept with the loader data its response would carry now (the render-time
@@ -575,6 +588,17 @@ export interface TestRouterHandle {
       keepClientCache?: boolean;
     },
   ): Promise<void>;
+  /**
+   * Set what the loader endpoint answers from now on: a later
+   * `useLoader().load()` or refreshGroup refresh of each loader resolves to
+   * its value (a pending Promise holds the answer, a rejection is the
+   * loader's error). Renders nothing; the page on screen keeps its data.
+   *
+   * @example
+   * router.respondToLoads({ loaders: [[CartLoader, { count: 3 }]] });
+   * fireEvent.click(getByText("Refresh")); // load(): count 3
+   */
+  respondToLoads(options: Pick<RenderRouteOptions, "loaders">): void;
   /**
    * The background revalidations a click on a stale prefetch started, in
    * order: the page's pathname and search, and the segment ids the request
@@ -689,6 +713,38 @@ function LinkInterceptionRegistration({
   return null;
 }
 
+/**
+ * The loader endpoint `useLoader().load()` fetches (`_rsc_loader=<id>`):
+ * installed on `fetch` while the tree is mounted, every other request passed
+ * through. A test that stubs `fetch` after the mount replaces it.
+ */
+function LoaderEndpoint({
+  answer,
+}: {
+  answer: (loaderId: string, hasParams: boolean) => Promise<Response>;
+}): null {
+  useEffect(() => {
+    const passThrough = globalThis.fetch;
+    // useLoader fetches with a URL string and an init.
+    const endpoint: typeof fetch = (input, init) => {
+      const url = new URL(String(input), TEST_ORIGIN);
+      const loaderId = url.searchParams.get(WIRE.loader);
+      if (
+        loaderId !== null &&
+        (init?.method ?? "GET").toUpperCase() === "GET"
+      ) {
+        return answer(loaderId, url.searchParams.has(WIRE.loaderParams));
+      }
+      return passThrough(input, init);
+    };
+    globalThis.fetch = endpoint;
+    return () => {
+      if (globalThis.fetch === endpoint) globalThis.fetch = passThrough;
+    };
+  }, [answer]);
+  return null;
+}
+
 /**
  * The marker production's root sets from its effect after hydration
  * (browser/rsc-router.tsx Rango), so a boundary that hydrates in a later pass
@@ -841,6 +897,43 @@ export async function renderRoute(
     return out;
   };
   const loaderData = seedLoaders(options.loaderData ?? {}, options.loaders);
+  // What the loader endpoint answers (LoaderEndpoint): the render seeds, then
+  // what respondToLoads() gave each loader.
+  const loadAnswers: Record<string, unknown> = { ...loaderData };
+  // The payload has rsc/loader-fetch.ts's shape; the value is taken when the
+  // request is made, as a server reads its data then.
+  const answerLoad = async (
+    loaderId: string,
+    hasParams: boolean,
+  ): Promise<Response> => {
+    type Answer = Parameters<typeof loaderAnswerResponse>[0];
+    const failure = (name: string, message: string): Answer => ({
+      loaderResult: null,
+      loaderError: { name, message },
+    });
+    let payload: Answer;
+    if (hasParams) {
+      payload = failure(
+        "Error",
+        `renderRoute does not answer parameterized load() calls (loader "${loaderId}"). Call load() without params, or stub fetch.`,
+      );
+    } else if (!(loaderId in loadAnswers)) {
+      payload = failure(
+        "Error",
+        `renderRoute: no value for loader "${loaderId}". Seed it with \`loaders\` or router.respondToLoads().`,
+      );
+    } else {
+      try {
+        payload = { loaderResult: await loadAnswers[loaderId] };
+      } catch (error) {
+        payload = failure(
+          error instanceof Error ? error.name : "Error",
+          error instanceof Error ? error.message : String(error),
+        );
+      }
+    }
+    return loaderAnswerResponse(payload);
+  };
 
   if (typeof window !== "undefined") {
     // The tree has no app version (its bridge reports none), so a seed needs
@@ -967,6 +1060,8 @@ export async function renderRoute(
     kind?: TransitionWhenKind;
     transition?: boolean;
     streamUntil?: Promise<unknown>;
+    /** refresh(): a commit onto the entry on screen. */
+    sameEntry?: boolean;
   };
 
   // The page each history entry shows, by the entry's `idx` stamp (the
@@ -1120,7 +1215,7 @@ export async function renderRoute(
     // on the event controller, which the provider takes with the payload.
     // The URL stays put: renderRoute tracks location on the event
     // controller, not window.location. router.navigate() without `state` or
-    // `replace: true`, and refresh(), leave history alone.
+    // `replace: true` leaves history alone.
     const history = navOptions?.history;
     const historyState = history
       ? buildHistoryState(
@@ -1199,6 +1294,18 @@ export async function renderRoute(
         history.replace ?? false,
       );
       eventController.commitLocationState(historyState);
+    } else if (navOptions?.sameEntry) {
+      // refresh() commits onto the entry on screen as production's does
+      // (navigation-transaction.ts sameEntry): the entry keeps its location
+      // state, readers keep what they show.
+      pushHistoryWithIdx(
+        keptEntryState(window.history.state),
+        window.location.href,
+        true,
+      );
+      eventController.commitLocationState(
+        shownLocationState(eventController.getLocationState()),
+      );
     }
     entryOnScreen = entryIndex();
     entries.set(entryOnScreen, {
@@ -1229,9 +1336,15 @@ export async function renderRoute(
     });
   };
 
-  const refresh = (): Promise<void> => {
+  const refresh = (
+    refreshOptions?: Pick<RenderRouteOptions, "loaders">,
+  ): Promise<void> => {
     const current = new URL(eventController.getLocation().href);
-    return navigate(current.pathname + current.search, { kind: "revalidate" });
+    return navigate(current.pathname + current.search, {
+      kind: "revalidate",
+      loaders: refreshOptions?.loaders,
+      sameEntry: true,
+    });
   };
 
   // prefetch(): the pages prefetched so far, by pathname and search, each with
@@ -1358,9 +1471,7 @@ export async function renderRoute(
       keepClientCache?: boolean;
     },
   ): Promise<void> => {
-    for (const [loader, data] of actionOptions?.loaders ?? []) {
-      loaderData[ensureSyntheticId(loader)] = data;
-    }
+    Object.assign(loaderData, seedLoaders({}, actionOptions?.loaders));
     const page = await renderPageAgain(
       new URL(eventController.getLocation().href),
       "action",
@@ -1508,6 +1619,7 @@ export async function renderRoute(
       />
       <DelegatedPrefetchRegistration bridge={bridge} />
       <LinkInterceptionRegistration bridge={bridge} />
+      <LoaderEndpoint answer={answerLoad} />
       {options.hydrate && <HydratedMarker />}
       {applyLateHandles && <AfterTree run={applyLateHandles} />}
       {resolveDocumentRevealed && <AfterTree run={resolveDocumentRevealed} />}
@@ -1587,6 +1699,9 @@ export async function renderRoute(
     refresh,
     prefetch,
     action,
+    respondToLoads: (respondOptions) => {
+      Object.assign(loadAnswers, seedLoaders({}, respondOptions.loaders));
+    },
     revalidations: () => [...revalidations],
     pathname: () => new URL(eventController.getLocation().href).pathname,
     params: () => eventController.getParams(),

package/src/testing/vitest-stubs/plugin-rsc-browser.ts

@@ -0,0 +1,61 @@
+/**
+ * Stub for `@vitejs/plugin-rsc/browser`, shipped so consumers do not have to
+ * write a per-file `vi.mock(...)`. The real entry imports the
+ * `virtual:vite-rsc/client-references` Vite virtual at the top level, which a
+ * bare Vitest process cannot resolve.
+ *
+ * The router reaches this module from `useLoader().load()` and a
+ * `refreshGroup` refresh (use-loader.tsx imports deps/browser.ts lazily).
+ * renderRoute answers those requests (render-route.tsx), and a DOM test has
+ * no Flight server to encode an answer: renderRoute's seeds are client values
+ * already. So the answer travels with its Response object, and
+ * `createFromFetch` hands it back unchanged, as a decoded payload. Any other
+ * response is rejected. The remaining exports exist for the re-export in
+ * deps/browser.ts; navigations, actions and the document are not decoded
+ * here.
+ */
+
+const answers = new WeakMap<object, unknown>();
+
+/**
+ * A loader endpoint Response whose decoded payload is `payload`
+ * (`{ loaderResult }` or `{ loaderResult: null, loaderError }`, as
+ * rsc/loader-fetch.ts answers).
+ */
+export function loaderAnswerResponse(payload: {
+  loaderResult: unknown;
+  loaderError?: { message: string; name: string };
+}): Response {
+  const response = new Response(null, {
+    headers: { "content-type": "text/x-component" },
+  });
+  answers.set(response, payload);
+  return response;
+}
+
+export async function createFromFetch<T>(
+  response: Promise<Response> | Response,
+): Promise<T> {
+  const settled = await response;
+  if (!answers.has(settled)) {
+    throw new Error(
+      "@vitejs/plugin-rsc/browser test stub: createFromFetch decodes only " +
+        "the loader answers renderRoute gives (useLoader().load(), a " +
+        "refreshGroup refresh). Real Flight responses are e2e territory.",
+    );
+  }
+  return answers.get(settled) as T;
+}
+
+function unavailable(name: string): never {
+  throw new Error(
+    `@vitejs/plugin-rsc/browser test stub: ${name} is not available in a ` +
+      "bare Vitest process. Real Flight responses are e2e territory.",
+  );
+}
+
+export const createFromReadableStream = (): Promise<never> =>
+  unavailable("createFromReadableStream");
+export const encodeReply = (): Promise<never> => unavailable("encodeReply");
+export const setServerCallback = (): void => {};
+export const createTemporaryReferenceSet = (): unknown => new Map();

package/src/testing/vitest.ts

@@ -229,6 +229,11 @@ export function rangoTestAliases(
       find: /^@vitejs\/plugin-rsc\/rsc(\/(server|client))?$/,
       replacement: here("src/testing/vitest-stubs/plugin-rsc.ts"),
     },
+    // useLoader().load() decodes renderRoute's loader answers through it.
+    {
+      find: /^@vitejs\/plugin-rsc\/browser$/,
+      replacement: here("src/testing/vitest-stubs/plugin-rsc-browser.ts"),
+    },
   ];
   if (rsdServerEdgePath) {
     aliases.push({

package/src/use-loader.tsx

@@ -270,10 +270,15 @@ function useLoaderInternal<T>(
   const loaders: LoaderStore | undefined = useContext(NavigationStoreContext)
     ?.store?.loaders;
 
+  // Committed route data (updated by the reset effect below), read by the
+  // store when a refresh begins: the snapshot it produces belongs to it.
+  const prevContextDataRef = useRef(contextData);
+  const routeDataOf = useCallback(() => prevContextDataRef.current, []);
+
   const groupRefetch = useCallback(async (): Promise<void> => {
     if (!loaderId || !loaders) return;
     const requestId = loaders.reserveRequestId(bucketKey);
-    loaders.beginRequest(bucketKey, requestId);
+    loaders.beginRequest(bucketKey, requestId, routeDataOf);
     try {
       const url = new URL(window.location.href);
       url.searchParams.set("_rsc_loader", loaderId);
@@ -316,6 +321,15 @@ function useLoaderInternal<T>(
     sharedState.bucketKey === bucketKey
       ? sharedState.snapshot
       : EMPTY_LOADER_SNAPSHOT;
+  // A route reader shows a refresh only when it was requested for this
+  // reader's route data: never another page's, nor one a navigation replaced
+  // (the rule the reset effect below applies when a mounted reader's data
+  // changes, here also for a reader that mounts).
+  const sharedValue =
+    sharedSnapshot.hasValue &&
+    (!hasContextData || sharedSnapshot.valueFor.has(contextData));
+  const sharedRequest =
+    !hasContextData || sharedSnapshot.requestFor.has(contextData);
   useEffect(() => {
     if (!loaders) return;
     const initial = loaders.getSnapshot(bucketKey);
@@ -343,6 +357,7 @@ function useLoaderInternal<T>(
         onStreamPending: hasContextData
           ? () => startTransition(() => setStreamPending(true))
           : undefined,
+        routeData: hasContextData ? routeDataOf : undefined,
       },
     );
     // eslint-disable-next-line react-hooks/exhaustive-deps -- intentional:
@@ -388,7 +403,6 @@ function useLoaderInternal<T>(
   // any pre-navigation load() promise that resolves later fails its gate
   // and is dropped — fixes the race where a stale fetch overwrites the
   // new route's context.
-  const prevContextDataRef = useRef(contextData);
   useEffect(() => {
     if (prevContextDataRef.current !== contextData) {
       setLocalFetchedData({ has: false, value: undefined });
@@ -407,11 +421,14 @@ function useLoaderInternal<T>(
   // `has`/`hasValue` gate each level so a committed falsy value is not skipped.
   const data = localFetchedData.has
     ? localFetchedData.value
-    : sharedSnapshot.hasValue
+    : sharedValue
       ? (sharedSnapshot.value as T | undefined)
       : contextData;
-  const isLoading = localIsLoading || sharedSnapshot.isLoading || streamPending;
-  const error = localError ?? sharedSnapshot.error;
+  const isLoading =
+    localIsLoading ||
+    (sharedRequest && sharedSnapshot.isLoading) ||
+    streamPending;
+  const error = localError ?? (sharedRequest ? sharedSnapshot.error : null);
 
   const throwOnError = options?.throwOnError ?? true;
 
@@ -446,7 +463,11 @@ function useLoaderInternal<T>(
       if (shared) {
         sharedRequestId = loaders.reserveRequestId(bucket);
         lastSharedRequestIdRef.current = sharedRequestId;
-        loaders.beginRequest(bucket, sharedRequestId);
+        loaders.beginRequest(
+          bucket,
+          sharedRequestId,
+          hasContextDataRef.current ? routeDataOf : undefined,
+        );
       } else {
         localRequestId = ++localRequestIdRef.current;
         setLocalIsLoading(true);
@@ -559,12 +580,13 @@ function useLoaderInternal<T>(
         }
       }
     },
-    [throwOnError, loaders],
+    [throwOnError, loaders, routeDataOf],
   );
 
   if (throwOnError) {
     if (localError) throw localError;
     if (
+      sharedRequest &&
       sharedSnapshot.error &&
       lastSharedRequestIdRef.current !== null &&
       sharedSnapshot.requestId === lastSharedRequestIdRef.current