From 014527bd2079b39586e0557c87051e2bce90fdad Mon Sep 17 00:00:00 2001
From: gimenes <tlgimenes@gmail.com>
Date: Tue, 10 Nov 2026 13:25:58 -0300
Subject: [PATCH 1/3] feat(nextjs,tanstack): let Studio's HTML swap re-render
 the page through its router

After a save, Studio's HTML swap replaced the whole document. React kept the
old nodes and the new HTML's scripts never ran, so every client component
stopped at its server markup: a footer revealed on scroll stayed hidden, a
carousel stopped.

The protocol now names a window hook, STUDIO_PAGE_REFRESH, that a binding
sets so Studio shows a save through the page's router instead:

- @decocms/nextjs: StudioBridge renders StudioRefresh ("use client"), which
  calls router.refresh() for the page's URL, or router.replace() for a moved
  draft pointer, and resolves when the transition is over.
- @decocms/tanstack: DecoDocument renders StudioRefresh, which reruns the
  loaders with router.invalidate(). A moved draft pointer is first fetched as
  a document, for the draft cookie the loaders' server functions carry.

A page without the hook keeps the document swap.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CLAUDE.md                                     |  6 +-
 packages/blocks/src/protocol/channel.ts       | 18 +++++
 packages/blocks/src/protocol/index.ts         |  2 +
 packages/nextjs/src/StudioBridge.ts           |  6 ++
 packages/nextjs/src/StudioRefresh.test.tsx    | 72 +++++++++++++++++
 packages/nextjs/src/StudioRefresh.tsx         | 63 +++++++++++++++
 packages/nextjs/src/components.test.tsx       |  2 +
 packages/nextjs/src/studio.test.ts            |  9 +++
 packages/nextjs/src/studio.ts                 |  6 ++
 packages/tanstack/src/react/DecoDocument.tsx  |  5 ++
 .../tanstack/src/react/StudioRefresh.test.tsx | 79 +++++++++++++++++++
 packages/tanstack/src/react/StudioRefresh.ts  | 57 +++++++++++++
 packages/tanstack/src/studio.test.ts          |  9 +++
 packages/tanstack/src/studio.ts               |  6 ++
 tests/studio-shortcut.test.ts                 |  4 +
 15 files changed, 341 insertions(+), 3 deletions(-)
 create mode 100644 packages/nextjs/src/StudioRefresh.test.tsx
 create mode 100644 packages/nextjs/src/StudioRefresh.tsx
 create mode 100644 packages/tanstack/src/react/StudioRefresh.test.tsx
 create mode 100644 packages/tanstack/src/react/StudioRefresh.ts

diff --git a/CLAUDE.md b/CLAUDE.md
index 7cc66dfe..993aaa52 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -92,7 +92,7 @@ Each export is built from the source file below (`dist/<same path>.js`, see abov
 | `@decocms/blocks/metrics` | `src/v8/metrics.ts` — `recordServerRequest`, for the framework bindings (`createDecoWorker`, `@decocms/nextjs/instrumentation`): `http.server.request.duration` on the CMS's telemetry; sites don't import it. Resolves without calling the route function with telemetry off; never rejects |
 | `@decocms/blocks/preview` | `src/v8/preview/index.ts` — `DraftBadge` (the "Preview mode" badge: a `"use client"` component, renders nothing without a pointer or inside a frame) and `StudioBridge` (a hook-free inline `<script>`: answers v7's `scrollToComponent` and `editor::rerender` (same-origin navigation) only when framed and only for the `trustedOrigins` the binding passes in, and runs no script Studio sends; unframed, v7's "." edit shortcut is on unless `editShortcut={false}`, and sends the page's `pathTemplate` from its `page` prop or, winning, the last `StudioPage` marker the page rendered, read at the keypress); `StudioChannel` (`StudioChannel.ts`, `channel.test.tsx`; protocol `src/protocol/channel.ts`): the Studio channel: every page, production included, carries `StudioChannel` (a ~1.4 kB inline script, ~0.7 kB gzipped). It trusts the list of exact origins the binding passes (`studioOrigins`, `data-studio-origins`; no wildcard). Framed (`window.parent !== window`), it posts `{ type: "deco:ready" }` to the parent with each trusted origin as `targetOrigin` (the browser delivers it only to a parent at one of them; where `location.ancestorOrigins` names the parent, to that origin alone, if trusted); on `{ type: "deco:load", url }` from the parent whose `event.origin` is exactly one of them, with `url` on exactly the origin of that message, it `import()`s the module once per URL and calls its default export with `{ studioOrigin, url, send, on }` bound to that origin, answering `deco:loaded` or `deco:load-error` to it (a failed URL may be retried); every later message from that origin whose `type` doesn't start with `deco:` goes to the listeners of the modules it loaded. Not framed, framed by another origin, or any failed check: nothing. It is the only way Studio runs code in the page (the bridge has no `editor::inject`). No framework code, no Studio origin list and no environment read: the binding (`@decocms/tanstack`, `@decocms/nextjs`) owns Studio's origins (`studioOrigins()`: its option, else `DECO_STUDIO_ORIGIN` comma-separated, else production and staging) and adds the same list to the page's CSP `script-src` and `frame-ancestors` (`withStudioCsp`) |
 | `@decocms/blocks/cli` | `src/v8/cli/index.ts` — the `deco` CLI (`schema`, `content`, `check`, the remote commands, `skills install`), also the bin (`bin/deco.js`, which runs the compiled `dist/v8/cli/main.js` under Node or Bun). CLI-only: the runtime never imports it (`run.test.ts`), so it and the TypeScript compiler never reach an app bundle |
-| `@decocms/blocks/protocol` (+ `/keys`, `/server`, `/storage/fs`, `/conformance`) | `src/protocol/**` — the content protocol the site editor uses, plus the Studio channel's message and module types for Studio (`CHANNEL_MESSAGE`, `StudioChannelContext`, `StudioChannelModule`, `defineStudioModule`, `DEFAULT_STUDIO_ORIGIN`, `DEFAULT_STUDIO_ORIGINS`, `src/protocol/channel.ts`); browser-safe except `storage/fs` (conditional export: `node` → real, `default` → a stub that throws) |
+| `@decocms/blocks/protocol` (+ `/keys`, `/server`, `/storage/fs`, `/conformance`) | `src/protocol/**` — the content protocol the site editor uses, plus the Studio channel's message and module types for Studio (`CHANNEL_MESSAGE`, `StudioChannelContext`, `StudioChannelModule`, `defineStudioModule`, `DEFAULT_STUDIO_ORIGIN`, `DEFAULT_STUDIO_ORIGINS`, and `STUDIO_PAGE_REFRESH`/`StudioPageRefresh`: the `window` hook a binding sets so Studio's HTML swap re-renders the page through its router instead of replacing the document; `src/protocol/channel.ts`); browser-safe except `storage/fs` (conditional export: `node` → real, `default` → a stub that throws) |
 
 ### `@decocms/tanstack` exports
 
@@ -105,7 +105,7 @@ Opinionated by design: the behaviour every Deco TanStack site should have is fix
 | `@decocms/tanstack/server` | `src/server/index.ts` — `contentClient(cms, request?)` (`cms.client({ version, visitor, experiments, campaigns })` from the worker's `x-deco-version`, `x-deco-visitor` and `x-deco-assignments`: the page decides nothing again), `requestVersion`, `requestVisitor`, `requestAssignments`, `markPrivate`, `isServerFnCall`. Server only |
 | `@decocms/tanstack/start` | `src/start/index.ts` — `decoServerFnFetch` for `createStart({ serverFns: { fetch } })`. Browser-safe |
 | `@decocms/tanstack/router` | `src/router/index.ts` — `createDecoRouter`, `decoParseSearch`/`decoStringifySearch` (keep `?q=`, v7 #646), `PAGE_STATUS_HEADER`. Isomorphic |
-| `@decocms/tanstack/react` | `src/react/index.ts` — `DecoDocument` (mounts the "." shortcut (`src/studioShortcut.ts`, the same file as `@decocms/nextjs`'s; v8 only, no v7 framed handler, Cypress-safe: `tests/studio-shortcut.test.ts`), `StudioChannel` (its `studioOrigins` prop, else `studioOrigins()` of `src/studio.ts`: `DECO_STUDIO_ORIGIN` comma-separated, else `DEFAULT_STUDIO_ORIGINS`) and `DraftBadge` from `@decocms/blocks/preview`, publishes the `__cseg` token and the draft), `NavigationProgress`, `StableOutlet`; `Image`, `Picture`, `Source` (v7's props and markup) with `ImageUrlProvider` for the site's `ImageUrl` from `@decocms/blocks/image`; no platform knowledge (without a provider, `DECO_IMAGE_URL`: every source through the Deco CDN), the site lists its platform's helper (`@decocms/apps-vtex/image`, …) itself. `tests/tanstack-image-markup.golden.test.ts` holds v7's markup byte for byte (250 cases: no width and Nuvemshop images included, the latter with a store's own provider) with those helpers, outside the package since it depends on no `@decocms/apps-*`. Browser-safe |
+| `@decocms/tanstack/react` | `src/react/index.ts` — `DecoDocument` (mounts the "." shortcut (`src/studioShortcut.ts`, the same file as `@decocms/nextjs`'s; v8 only, no v7 framed handler, Cypress-safe: `tests/studio-shortcut.test.ts`), `StudioChannel` (its `studioOrigins` prop, else `studioOrigins()` of `src/studio.ts`: `DECO_STUDIO_ORIGIN` comma-separated, else `DEFAULT_STUDIO_ORIGINS`), `StudioRefresh` (`src/react/StudioRefresh.ts`: sets `window[STUDIO_PAGE_REFRESH]`, which shows a save with `router.invalidate()`; a moved draft pointer is first fetched as a document for its cookie, which the loaders' server functions carry) and `DraftBadge` from `@decocms/blocks/preview`, publishes the `__cseg` token and the draft), `NavigationProgress`, `StableOutlet`; `Image`, `Picture`, `Source` (v7's props and markup) with `ImageUrlProvider` for the site's `ImageUrl` from `@decocms/blocks/image`; no platform knowledge (without a provider, `DECO_IMAGE_URL`: every source through the Deco CDN), the site lists its platform's helper (`@decocms/apps-vtex/image`, …) itself. `tests/tanstack-image-markup.golden.test.ts` holds v7's markup byte for byte (250 cases: no width and Nuvemshop images included, the latter with a store's own provider) with those helpers, outside the package since it depends on no `@decocms/apps-*`. Browser-safe |
 | `@decocms/tanstack/vite` | `src/vite/index.ts` — `decoTanstack({ buildHash })` (= `decoContent()` from `@decocms/blocks/vite`, `__BUILD_HASH__`, a browser stub for `node:async_hooks`, `resolve.dedupe`), `gitBuildHash` |
 | `@decocms/tanstack/scope` | `src/scope/server.ts` / `browser.ts` — the request scope the worker hands the render (`AsyncLocalStorage`). Conditional export: `workerd` and `node` before `browser`, because a Workers build turns `browser` on too; `src/__tests__/exports.test.ts` resolves it under those conditions |
 
@@ -117,7 +117,7 @@ Small helpers for any Next.js App Router app, with no hosting assumptions (no CD
 |---|---|
 | `@decocms/nextjs/proxy` | `src/proxy/index.ts` — `decideDraft(cms, request)` (the CMS's preview hosts, `cms.readVersion`, `src/drafts.ts`), `draftRequestHeaders` (`x-deco-version`; forged `x-deco-version`/`x-deco-visitor`/`x-deco-assignments` removed), `rewriteToDraftRoute` (`/_draft`, with the visitor and the assignments when given), `applyDraft` (cookie, `draftResponseHeaders`), `isDraftRoutePath`, `decideVisitor` (`readVisitor`; the cookie on a first visit only, never from a preview; reads no content), `visitorRequestHeaders` (`x-deco-visitor`), `decideAssignments` (every test and campaign, decided once: `cms.client({ visitor, ...version })`), `assignmentsRequestHeaders` (`x-deco-assignments`), `applyVisitor`, the assignments route (`rewriteToAssignmentsRoute`, `assignmentsSegment`: every name with its state), `draftProxy` (all of it). `DraftDecision.version` is `cms.readVersion`'s shape (blocks' `parseVersion` after the binding's host check). No React, no `next/headers`, no block map (`src/__tests__/exports.test.ts`) |
 | `@decocms/nextjs/server` | `src/server/index.ts` — `bindDraft(cms, { searchParams })` (param, then `x-deco-version`, then cookie; the same host check), `activeDraftPointer`, `contentClient(cms)` (`cms.client({ version, experiments, campaigns })` with what the proxy decided), `assignedClient(cms, segment)` (async: the assignments route's fully decided client, a test at 0% kept off); `bindDraft` also binds the proxy's `x-deco-visitor` and `x-deco-assignments` (for a preview always; on the current release only when it saves an `experiments` or `campaigns` block, so a static page stays static, and then a test at 0% stays off whatever the header says). The draft lives in React's `cache()` (`server/slot.ts`), so no conditional export is needed |
-| `@decocms/nextjs` | `src/index.ts` — `DraftPreviewIndicator` (renders `DraftBadge` for the bound draft), `DraftBadge`, `StudioBridge` (`src/StudioBridge.ts`, v8 only: the "." shortcut, `src/studioShortcut.ts` (no v7 framed handler, so nothing a Cypress frame-busting rewrite matches: `tests/studio-shortcut.test.ts`), followed by blocks' `StudioChannel` for `studioOrigins(props.studioOrigins)`), `withStudioCsp` (`src/csp.ts`: the site's own CSP with Studio's origins in `script-src` and `frame-ancestors`; the binding sends no CSP itself), and the package's own draft names and Studio origins: `DRAFT_PARAM`/`DRAFT_COOKIE`/`VERSION_HEADER`, `draftResponseHeaders` (`src/draft.ts`), `VISITOR_HEADER` (`src/visitor.ts`), `ASSIGNMENTS_HEADER` (`src/assignments.ts`), `STUDIO_ORIGINS`/`STUDIO_FRAME_ANCESTORS`/`isStudioOrigin`/`STUDIO_ORIGIN`/`DEFAULT_STUDIO_ORIGINS`/`studioOrigins` (`src/studio.ts`). The same values as `@decocms/tanstack`'s, never imported from it (`exports.test.ts`) |
+| `@decocms/nextjs` | `src/index.ts` — `DraftPreviewIndicator` (renders `DraftBadge` for the bound draft), `DraftBadge`, `StudioBridge` (`src/StudioBridge.ts`, v8 only: the "." shortcut, `src/studioShortcut.ts` (no v7 framed handler, so nothing a Cypress frame-busting rewrite matches: `tests/studio-shortcut.test.ts`), followed by blocks' `StudioChannel` for `studioOrigins(props.studioOrigins)`, then `StudioRefresh` (`src/StudioRefresh.tsx`, `"use client"`: sets `window[STUDIO_PAGE_REFRESH]`, which shows a save with `router.refresh()`, or `router.replace()` for a moved draft pointer, so React stays attached)), `withStudioCsp` (`src/csp.ts`: the site's own CSP with Studio's origins in `script-src` and `frame-ancestors`; the binding sends no CSP itself), and the package's own draft names and Studio origins: `DRAFT_PARAM`/`DRAFT_COOKIE`/`VERSION_HEADER`, `draftResponseHeaders` (`src/draft.ts`), `VISITOR_HEADER` (`src/visitor.ts`), `ASSIGNMENTS_HEADER` (`src/assignments.ts`), `STUDIO_ORIGINS`/`STUDIO_FRAME_ANCESTORS`/`isStudioOrigin`/`STUDIO_ORIGIN`/`DEFAULT_STUDIO_ORIGINS`/`studioOrigins` (`src/studio.ts`). The same values as `@decocms/tanstack`'s, never imported from it (`exports.test.ts`) |
 | `@decocms/nextjs/config` | `src/config/index.cjs` (+ `index.d.cts`), plain CommonJS shipped from `src` — `withDeco(nextConfig, { draftHeaders, studioOrigins })`: v7's draft header rules first, `STUDIO_ORIGINS` in `allowedDevOrigins`; no rewrites, no image rules. It repeats the package's names (`src/draft.ts`, `src/studio.ts`), held equal by `config.test.ts` |
 | `@decocms/nextjs/instrumentation` | `src/instrumentation/index.ts` — `register()` (the site's `instrumentation.ts`: a minimal global tracer provider whose only job is Next's root `BaseServer.handleRequest` span, recorded with `recordServerRequest` from `@decocms/blocks/metrics`; exports no span, non-recording for every other span; skips the proxy's own bubbled `handleRequest`; no-op on Edge, without `@opentelemetry/api` (the app's, else Next's compiled copy) or when another provider is registered) and `serverRequestSpanProcessor()` for a site with its own OpenTelemetry SDK. `@opentelemetry/api` is an optional peer |
 | `@decocms/nextjs/image-loader` | `src/image-loader/index.ts` — `createDecoImageLoader(imageUrl, { fallback })`, `nextImageOptimizer`. Platform-neutral: the site composes its platform's helpers (`@decocms/apps-vtex/image`, …) into the `ImageUrl`; the package depends on no `@decocms/apps-*`. `tests/nextjs-image-loader.golden.test.ts` runs the next/image golden URLs of blocks and apps-vtex through that composition (no changed case but the PO-approved fix-2 ones, marked `before`/`reason` in the fixture) |
diff --git a/packages/blocks/src/protocol/channel.ts b/packages/blocks/src/protocol/channel.ts
index d7b6ebe0..eb3f2a67 100644
--- a/packages/blocks/src/protocol/channel.ts
+++ b/packages/blocks/src/protocol/channel.ts
@@ -118,6 +118,24 @@ export type StudioChannelModule<
   Out extends ModuleMessage = ModuleMessage,
 > = (context: StudioChannelContext<In, Out>) => void | Promise<void>;
 
+/**
+ * The `window` property a binding sets when its framework can show a save by
+ * re-rendering the page in place (Next.js: `router.refresh()`): a
+ * {@link StudioPageRefresh}. Studio's HTML swap calls it instead of replacing
+ * the document, whose new scripts never run, so the page's client components
+ * would stop at their server markup (a footer revealed on scroll, a carousel).
+ * A page without it gets the document swap.
+ */
+export const STUDIO_PAGE_REFRESH = "__decoStudioRefresh";
+
+/**
+ * Shows `url` (absolute, on the page's own origin: the page's URL, or a new one
+ * whose draft pointer moved) from the server without reloading, keeping the
+ * page's client state; resolves once the new content is on screen, rejects
+ * when it can't show it (Studio then reloads the frame).
+ */
+export type StudioPageRefresh = (url: string) => Promise<void>;
+
 /** Types a module's default export: `export default defineStudioModule<In, Out>((channel) => …)`. */
 export function defineStudioModule<
   In extends ModuleMessage = ModuleMessage,
diff --git a/packages/blocks/src/protocol/index.ts b/packages/blocks/src/protocol/index.ts
index d9fd5dd2..3e3a1870 100644
--- a/packages/blocks/src/protocol/index.ts
+++ b/packages/blocks/src/protocol/index.ts
@@ -61,9 +61,11 @@ export {
   defineStudioModule,
   type ModuleMessage,
   type PageChannelMessage,
+  STUDIO_PAGE_REFRESH,
   type StudioChannelContext,
   type StudioChannelMessage,
   type StudioChannelModule,
+  type StudioPageRefresh,
 } from "./channel.ts";
 export {
   assertSupportedEndpoint,
diff --git a/packages/nextjs/src/StudioBridge.ts b/packages/nextjs/src/StudioBridge.ts
index b1f1bc52..fea3789f 100644
--- a/packages/nextjs/src/StudioBridge.ts
+++ b/packages/nextjs/src/StudioBridge.ts
@@ -14,9 +14,14 @@
  * Components payload that carries the script). Two inline scripts and no
  * hooks, so a Server Component renders it as is. The site's CSP allows the
  * same origins with `withStudioCsp`.
+ *
+ * After a save, Studio shows the new content through the App Router
+ * (`StudioRefresh`, a client component, so React stays attached to the page)
+ * instead of replacing the document.
  */
 import { StudioChannel, type StudioPageInfo } from "@decocms/blocks/preview";
 import { createElement, Fragment, type ReactNode } from "react";
+import { StudioRefresh } from "./StudioRefresh.tsx";
 import { studioOrigins } from "./studio.ts";
 import { StudioShortcut } from "./studioShortcut.ts";
 
@@ -64,5 +69,6 @@ export function StudioBridge({
     null,
     createElement(StudioShortcut, { site, editShortcut, page, nonce }),
     createElement(StudioChannel, { studioOrigins: studioOrigins(origins), nonce }),
+    createElement(StudioRefresh),
   );
 }
diff --git a/packages/nextjs/src/StudioRefresh.test.tsx b/packages/nextjs/src/StudioRefresh.test.tsx
new file mode 100644
index 00000000..1d915aae
--- /dev/null
+++ b/packages/nextjs/src/StudioRefresh.test.tsx
@@ -0,0 +1,72 @@
+// @vitest-environment jsdom
+import { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const router = vi.hoisted(() => ({ refresh: vi.fn(), replace: vi.fn() }));
+vi.mock("next/navigation", () => ({ useRouter: () => router }));
+
+const { StudioRefresh } = await import("./StudioRefresh.tsx");
+const { STUDIO_PAGE_REFRESH } = await import("./studio.ts");
+
+(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+type Refresh = (url: string) => Promise<void>;
+const slot = () => (window as unknown as Record<string, Refresh | undefined>)[STUDIO_PAGE_REFRESH];
+
+let root: Root;
+beforeEach(async () => {
+  router.refresh.mockReset();
+  router.replace.mockReset();
+  window.history.replaceState(null, "", "/shoes?__draft=a");
+  root = createRoot(document.body.appendChild(document.createElement("div")));
+  await act(async () => root.render(<StudioRefresh />));
+});
+afterEach(async () => {
+  await act(async () => root.unmount());
+  document.body.innerHTML = "";
+});
+
+describe("StudioRefresh", () => {
+  it("puts the page's refresh where Studio's HTML swap looks for it", () => {
+    expect(typeof slot()).toBe("function");
+  });
+
+  it("refreshes the page's own URL in place, and resolves once the transition is over", async () => {
+    let done = false;
+    // React flushes the transition when act's callback returns, so the
+    // promise is awaited after it.
+    let refreshed!: Promise<void>;
+    await act(async () => {
+      refreshed = slot()!(window.location.href).then(() => {
+        done = true;
+      });
+    });
+    await refreshed;
+    expect(done).toBe(true);
+    expect(router.refresh).toHaveBeenCalledTimes(1);
+    expect(router.replace).not.toHaveBeenCalled();
+  });
+
+  it("navigates to a new URL of the page (a moved draft pointer) without scrolling", async () => {
+    let refreshed!: Promise<void>;
+    await act(async () => {
+      refreshed = slot()!(`${window.location.origin}/shoes?__draft=b#top`);
+    });
+    await refreshed;
+    expect(router.replace).toHaveBeenCalledWith("/shoes?__draft=b#top", { scroll: false });
+    expect(router.refresh).not.toHaveBeenCalled();
+  });
+
+  it("refuses another origin's URL", async () => {
+    await expect(slot()!("https://elsewhere.example/shoes")).rejects.toThrow(/origin/);
+    expect(router.refresh).not.toHaveBeenCalled();
+    expect(router.replace).not.toHaveBeenCalled();
+  });
+
+  it("takes it away when it unmounts", async () => {
+    await act(async () => root.unmount());
+    expect(slot()).toBeUndefined();
+    root = createRoot(document.body.appendChild(document.createElement("div")));
+  });
+});
diff --git a/packages/nextjs/src/StudioRefresh.tsx b/packages/nextjs/src/StudioRefresh.tsx
new file mode 100644
index 00000000..9eb9722d
--- /dev/null
+++ b/packages/nextjs/src/StudioRefresh.tsx
@@ -0,0 +1,63 @@
+"use client";
+/**
+ * The page's own refresh for Studio's HTML swap (`STUDIO_PAGE_REFRESH`): after
+ * a save, Studio asks the page to show its new content. Replacing the document
+ * would leave React holding the old nodes, so every client component (a footer
+ * revealed on scroll, a carousel, a popup) would stop at its server markup.
+ * Here the App Router does it instead: `router.refresh()` for the page's own
+ * URL, `router.replace()` for a new one (a save moved the draft pointer in
+ * `?__draft=`), both re-rendering the Server Components with React attached.
+ * The promise resolves when the transition is over, so Studio's progress bar
+ * runs as long as the refresh.
+ *
+ * Set on every page, framed or not: Studio's module is the only caller, and
+ * comparing the window with its parent here is what a test runner's
+ * frame-busting rewrite matches (see `StudioBridge.ts`).
+ */
+import { useRouter } from "next/navigation";
+import { useEffect, useRef, useTransition } from "react";
+import { STUDIO_PAGE_REFRESH } from "./studio.ts";
+
+type StudioPageRefresh = (url: string) => Promise<void>;
+
+export function StudioRefresh(): null {
+  const router = useRouter();
+  const [pending, startTransition] = useTransition();
+  // Each refresh waits for the transition it starts; a later one joins it.
+  const waiting = useRef<Array<() => void>>([]);
+
+  useEffect(() => {
+    if (pending) return;
+    for (const resolve of waiting.current.splice(0)) resolve();
+  }, [pending]);
+
+  useEffect(() => {
+    const refresh: StudioPageRefresh = (url) =>
+      new Promise<void>((resolve, reject) => {
+        let target: URL;
+        try {
+          target = new URL(url, location.href);
+        } catch (error) {
+          reject(error);
+          return;
+        }
+        if (target.origin !== location.origin) {
+          reject(new Error(`Not this page's origin: ${target.origin}`));
+          return;
+        }
+        waiting.current.push(resolve);
+        startTransition(() => {
+          if (target.href === location.href) router.refresh();
+          else
+            router.replace(`${target.pathname}${target.search}${target.hash}`, { scroll: false });
+        });
+      });
+    const slot = window as unknown as Record<string, unknown>;
+    slot[STUDIO_PAGE_REFRESH] = refresh;
+    return () => {
+      if (slot[STUDIO_PAGE_REFRESH] === refresh) delete slot[STUDIO_PAGE_REFRESH];
+    };
+  }, [router]);
+
+  return null;
+}
diff --git a/packages/nextjs/src/components.test.tsx b/packages/nextjs/src/components.test.tsx
index e4aad5a4..dd3e6e1d 100644
--- a/packages/nextjs/src/components.test.tsx
+++ b/packages/nextjs/src/components.test.tsx
@@ -9,6 +9,8 @@ vi.mock("./server/slot.ts", () => ({
   activeDraftPointer: () => slot.pointer,
   draftUnavailable: () => slot.unavailable,
 }));
+// StudioBridge renders StudioRefresh, which needs the App Router mounted.
+vi.mock("next/navigation", () => ({ useRouter: () => ({ refresh() {}, replace() {} }) }));
 
 const { DraftPreviewIndicator, StudioBridge, StudioPage } = await import("./index.ts");
 
diff --git a/packages/nextjs/src/studio.test.ts b/packages/nextjs/src/studio.test.ts
index 3d0b8086..51431ace 100644
--- a/packages/nextjs/src/studio.test.ts
+++ b/packages/nextjs/src/studio.test.ts
@@ -4,6 +4,7 @@
 import {
   DEFAULT_STUDIO_ORIGIN,
   DEFAULT_STUDIO_ORIGINS as PROTOCOL_ORIGINS,
+  STUDIO_PAGE_REFRESH as PROTOCOL_PAGE_REFRESH,
 } from "@decocms/blocks/protocol";
 import { afterEach, describe, expect, it } from "vitest";
 import {
@@ -12,6 +13,7 @@ import {
   STUDIO_FRAME_ANCESTORS,
   STUDIO_ORIGIN,
   STUDIO_ORIGINS,
+  STUDIO_PAGE_REFRESH,
   studioOrigins,
 } from "./studio";
 
@@ -137,3 +139,10 @@ describe("studioOrigins (the origins the Studio channel trusts and the CSP allow
     ).toEqual(["http://[::1]:3000", "http://a.com:8080"]);
   });
 });
+
+describe("STUDIO_PAGE_REFRESH", () => {
+  it("is the protocol's name, where Studio's HTML swap looks for the page's refresh", () => {
+    expect(STUDIO_PAGE_REFRESH).toBe(PROTOCOL_PAGE_REFRESH);
+    expect(STUDIO_PAGE_REFRESH).toBe("__decoStudioRefresh");
+  });
+});
diff --git a/packages/nextjs/src/studio.ts b/packages/nextjs/src/studio.ts
index 0909dda0..c35dd909 100644
--- a/packages/nextjs/src/studio.ts
+++ b/packages/nextjs/src/studio.ts
@@ -45,6 +45,12 @@ export const DEFAULT_STUDIO_ORIGINS: readonly string[] = Object.freeze([
   "https://studio-stg.decocms.com",
 ]);
 
+/**
+ * Where `StudioRefresh` puts the page's own refresh for Studio's HTML swap
+ * (`STUDIO_PAGE_REFRESH` of `@decocms/blocks/protocol`, held equal by a test).
+ */
+export const STUDIO_PAGE_REFRESH = "__decoStudioRefresh";
+
 /** `value` as an exact http(s) origin (`https://host[:port]`, a trailing `/` dropped; no wildcard), or `""`. */
 function asOrigin(value: unknown): string {
   if (typeof value !== "string") return "";
diff --git a/packages/tanstack/src/react/DecoDocument.tsx b/packages/tanstack/src/react/DecoDocument.tsx
index 2adc5c3c..78e84c15 100644
--- a/packages/tanstack/src/react/DecoDocument.tsx
+++ b/packages/tanstack/src/react/DecoDocument.tsx
@@ -15,6 +15,9 @@
  *   (only on a draft page outside Studio's frame), from
  *   `@decocms/blocks/preview`. The worker adds the same origins to the
  *   page's CSP `script-src` and `frame-ancestors`;
+ * - `StudioRefresh`: after a save, Studio shows the new content by rerunning
+ *   the loaders (`router.invalidate()`), with React still attached, instead
+ *   of replacing the document;
  * - v7's "." edit shortcut (`../studioShortcut.ts`: outside Studio's frame,
  *   "." opens the page in Studio's editor, with the page's `pathTemplate`
  *   from the route's loader data). v8 only: v7's framed handler
@@ -31,6 +34,7 @@ import { type ReactNode, useEffect, useRef, useState } from "react";
 import { studioOrigins } from "../studio.ts";
 import { StudioShortcut } from "../studioShortcut.ts";
 import { pageValues, publishScript } from "./pageValues.ts";
+import { StudioRefresh } from "./StudioRefresh.ts";
 import { DATA_EVENT_OBSERVER, eventsBootstrap, PROGRESS_CSS } from "./scripts.ts";
 
 declare global {
@@ -129,6 +133,7 @@ function StudioPieces({
         nonce={nonce}
       />
       <StudioChannel studioOrigins={studioOrigins(origins)} nonce={nonce} />
+      <StudioRefresh />
       <DraftBadge pointer={draft ?? null} unavailable={draftUnavailable} />
     </>
   );
diff --git a/packages/tanstack/src/react/StudioRefresh.test.tsx b/packages/tanstack/src/react/StudioRefresh.test.tsx
new file mode 100644
index 00000000..7575c518
--- /dev/null
+++ b/packages/tanstack/src/react/StudioRefresh.test.tsx
@@ -0,0 +1,79 @@
+// @vitest-environment jsdom
+import { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const calls = vi.hoisted(() => [] as string[]);
+const router = vi.hoisted(() => ({
+  navigate: vi.fn(async (opts: { href: string }) => {
+    calls.push(`navigate ${opts.href}`);
+  }),
+  invalidate: vi.fn(async () => {
+    calls.push("invalidate");
+  }),
+}));
+vi.mock("@tanstack/react-router", () => ({ useRouter: () => router }));
+
+const { StudioRefresh } = await import("./StudioRefresh.ts");
+const { STUDIO_PAGE_REFRESH } = await import("../studio.ts");
+
+(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+type Refresh = (url: string) => Promise<void>;
+const slot = () => (window as unknown as Record<string, Refresh | undefined>)[STUDIO_PAGE_REFRESH];
+const realFetch = globalThis.fetch;
+
+let root: Root;
+beforeEach(async () => {
+  calls.length = 0;
+  router.navigate.mockClear();
+  router.invalidate.mockClear();
+  globalThis.fetch = vi.fn(async (input: RequestInfo | URL) => {
+    calls.push(`fetch ${String(input)}`);
+    return new Response("<html></html>");
+  }) as typeof fetch;
+  window.history.replaceState(null, "", "/shoes?__draft=a");
+  root = createRoot(document.body.appendChild(document.createElement("div")));
+  await act(async () => root.render(<StudioRefresh />));
+});
+afterEach(async () => {
+  await act(async () => root.unmount());
+  globalThis.fetch = realFetch;
+  document.body.innerHTML = "";
+});
+
+describe("StudioRefresh", () => {
+  it("reruns the loaders for the page's own URL, fetching nothing else", async () => {
+    await slot()!(window.location.href);
+    expect(calls).toEqual(["invalidate"]);
+  });
+
+  it("a moved draft pointer: the link's cookie first, then the URL, then the loaders", async () => {
+    const next = `${window.location.origin}/shoes?__draft=b`;
+    await slot()!(next);
+    expect(calls).toEqual([`fetch ${next}`, "navigate /shoes?__draft=b", "invalidate"]);
+    expect(router.navigate).toHaveBeenCalledWith({
+      href: "/shoes?__draft=b",
+      replace: true,
+      resetScroll: false,
+    });
+  });
+
+  it("rejects when the new link fails, leaving the page as it is", async () => {
+    globalThis.fetch = vi.fn(async () => new Response("", { status: 500 })) as typeof fetch;
+    await expect(slot()!(`${window.location.origin}/shoes?__draft=b`)).rejects.toThrow(/500/);
+    expect(router.navigate).not.toHaveBeenCalled();
+    expect(router.invalidate).not.toHaveBeenCalled();
+  });
+
+  it("refuses another origin's URL", async () => {
+    await expect(slot()!("https://elsewhere.example/shoes")).rejects.toThrow(/origin/);
+    expect(calls).toEqual([]);
+  });
+
+  it("takes it away when it unmounts", async () => {
+    await act(async () => root.unmount());
+    expect(slot()).toBeUndefined();
+    root = createRoot(document.body.appendChild(document.createElement("div")));
+  });
+});
diff --git a/packages/tanstack/src/react/StudioRefresh.ts b/packages/tanstack/src/react/StudioRefresh.ts
new file mode 100644
index 00000000..c11bd232
--- /dev/null
+++ b/packages/tanstack/src/react/StudioRefresh.ts
@@ -0,0 +1,57 @@
+/**
+ * The page's own refresh for Studio's HTML swap (`STUDIO_PAGE_REFRESH` of
+ * `@decocms/blocks/protocol`): after a save, Studio asks the page to show its
+ * new content. Replacing the document would leave React holding the old nodes,
+ * so every client component would stop at its server markup. Here the router
+ * does it instead and stays attached: `router.invalidate()` reruns the loaders
+ * and resolves once the page shows their data.
+ *
+ * A new URL of the page (a save moved the draft pointer in `?__draft=`) first
+ * goes to the worker as a document request, only for its draft cookie: the
+ * loaders' server-function calls carry the cookie, not the page's query. Then
+ * the router moves to the URL and reruns the loaders.
+ *
+ * Set on every page, framed or not: Studio's module is the only caller, and
+ * comparing the window with its parent here is what a test runner's
+ * frame-busting rewrite matches (`tests/studio-shortcut.test.ts`).
+ */
+import { useRouter } from "@tanstack/react-router";
+import { useEffect } from "react";
+import { STUDIO_PAGE_REFRESH } from "../studio.ts";
+
+type StudioPageRefresh = (url: string) => Promise<void>;
+
+export function StudioRefresh(): null {
+  const router = useRouter();
+
+  useEffect(() => {
+    const refresh: StudioPageRefresh = async (url) => {
+      const target = new URL(url, location.href);
+      if (target.origin !== location.origin) {
+        throw new Error(`Not this page's origin: ${target.origin}`);
+      }
+      if (target.href !== location.href) {
+        const res = await fetch(target.href, {
+          headers: { accept: "text/html" },
+          credentials: "same-origin",
+          cache: "no-store",
+        });
+        await res.body?.cancel();
+        if (!res.ok) throw new Error(`The page answered ${res.status}`);
+        await router.navigate({
+          href: `${target.pathname}${target.search}${target.hash}`,
+          replace: true,
+          resetScroll: false,
+        });
+      }
+      await router.invalidate();
+    };
+    const slot = window as unknown as Record<string, unknown>;
+    slot[STUDIO_PAGE_REFRESH] = refresh;
+    return () => {
+      if (slot[STUDIO_PAGE_REFRESH] === refresh) delete slot[STUDIO_PAGE_REFRESH];
+    };
+  }, [router]);
+
+  return null;
+}
diff --git a/packages/tanstack/src/studio.test.ts b/packages/tanstack/src/studio.test.ts
index f8a5ff84..39fe4f7f 100644
--- a/packages/tanstack/src/studio.test.ts
+++ b/packages/tanstack/src/studio.test.ts
@@ -4,6 +4,7 @@
 import {
   DEFAULT_STUDIO_ORIGIN,
   DEFAULT_STUDIO_ORIGINS as PROTOCOL_ORIGINS,
+  STUDIO_PAGE_REFRESH as PROTOCOL_PAGE_REFRESH,
 } from "@decocms/blocks/protocol";
 import { afterEach, describe, expect, it } from "vitest";
 import {
@@ -12,6 +13,7 @@ import {
   STUDIO_FRAME_ANCESTORS,
   STUDIO_ORIGIN,
   STUDIO_ORIGINS,
+  STUDIO_PAGE_REFRESH,
   studioOrigins,
 } from "./studio";
 
@@ -137,3 +139,10 @@ describe("studioOrigins (the origins the Studio channel trusts and the CSP allow
     ).toEqual(["http://[::1]:3000", "http://a.com:8080"]);
   });
 });
+
+describe("STUDIO_PAGE_REFRESH", () => {
+  it("is the protocol's name, where Studio's HTML swap looks for the page's refresh", () => {
+    expect(STUDIO_PAGE_REFRESH).toBe(PROTOCOL_PAGE_REFRESH);
+    expect(STUDIO_PAGE_REFRESH).toBe("__decoStudioRefresh");
+  });
+});
diff --git a/packages/tanstack/src/studio.ts b/packages/tanstack/src/studio.ts
index a8fb657a..71eb58b3 100644
--- a/packages/tanstack/src/studio.ts
+++ b/packages/tanstack/src/studio.ts
@@ -43,6 +43,12 @@ export const DEFAULT_STUDIO_ORIGINS: readonly string[] = Object.freeze([
   "https://studio-stg.decocms.com",
 ]);
 
+/**
+ * Where `StudioRefresh` puts the page's own refresh for Studio's HTML swap
+ * (`STUDIO_PAGE_REFRESH` of `@decocms/blocks/protocol`, held equal by a test).
+ */
+export const STUDIO_PAGE_REFRESH = "__decoStudioRefresh";
+
 /** `value` as an exact http(s) origin (`https://host[:port]`, a trailing `/` dropped; no wildcard), or `""`. */
 function asOrigin(value: unknown): string {
   if (typeof value !== "string") return "";
diff --git a/tests/studio-shortcut.test.ts b/tests/studio-shortcut.test.ts
index 97309626..b5020d08 100644
--- a/tests/studio-shortcut.test.ts
+++ b/tests/studio-shortcut.test.ts
@@ -23,6 +23,10 @@ import { renderToStaticMarkup } from "react-dom/server";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { STUDIO_BRIDGE_SCRIPT } from "../packages/blocks/src/v8/preview/StudioBridge.ts";
 import * as nextShortcut from "../packages/nextjs/src/studioShortcut.ts";
+
+// StudioBridge renders StudioRefresh, which needs the App Router mounted.
+vi.mock("next/navigation", () => ({ useRouter: () => ({ refresh() {}, replace() {} }) }));
+
 import * as tanstackShortcut from "../packages/tanstack/src/studioShortcut.ts";
 
 // Cypress's regex rewriter (packages/rewriter/lib/regex-rewriter.ts).

From 2c60486aa46fe787eba858f3a25410698620ae3b Mon Sep 17 00:00:00 2001
From: gimenes <tlgimenes@gmail.com>
Date: Tue, 10 Nov 2026 13:49:53 -0300
Subject: [PATCH 2/3] fix(nextjs): import next/navigation.js, as the build's
 NodeNext resolution requires

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 packages/nextjs/src/StudioRefresh.test.tsx | 2 +-
 packages/nextjs/src/StudioRefresh.tsx      | 2 +-
 packages/nextjs/src/components.test.tsx    | 2 +-
 tests/studio-shortcut.test.ts              | 2 +-
 4 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/packages/nextjs/src/StudioRefresh.test.tsx b/packages/nextjs/src/StudioRefresh.test.tsx
index 1d915aae..14296ab5 100644
--- a/packages/nextjs/src/StudioRefresh.test.tsx
+++ b/packages/nextjs/src/StudioRefresh.test.tsx
@@ -4,7 +4,7 @@ import { createRoot, type Root } from "react-dom/client";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 const router = vi.hoisted(() => ({ refresh: vi.fn(), replace: vi.fn() }));
-vi.mock("next/navigation", () => ({ useRouter: () => router }));
+vi.mock("next/navigation.js", () => ({ useRouter: () => router }));
 
 const { StudioRefresh } = await import("./StudioRefresh.tsx");
 const { STUDIO_PAGE_REFRESH } = await import("./studio.ts");
diff --git a/packages/nextjs/src/StudioRefresh.tsx b/packages/nextjs/src/StudioRefresh.tsx
index 9eb9722d..3df7e008 100644
--- a/packages/nextjs/src/StudioRefresh.tsx
+++ b/packages/nextjs/src/StudioRefresh.tsx
@@ -14,7 +14,7 @@
  * comparing the window with its parent here is what a test runner's
  * frame-busting rewrite matches (see `StudioBridge.ts`).
  */
-import { useRouter } from "next/navigation";
+import { useRouter } from "next/navigation.js";
 import { useEffect, useRef, useTransition } from "react";
 import { STUDIO_PAGE_REFRESH } from "./studio.ts";
 
diff --git a/packages/nextjs/src/components.test.tsx b/packages/nextjs/src/components.test.tsx
index dd3e6e1d..dd019746 100644
--- a/packages/nextjs/src/components.test.tsx
+++ b/packages/nextjs/src/components.test.tsx
@@ -10,7 +10,7 @@ vi.mock("./server/slot.ts", () => ({
   draftUnavailable: () => slot.unavailable,
 }));
 // StudioBridge renders StudioRefresh, which needs the App Router mounted.
-vi.mock("next/navigation", () => ({ useRouter: () => ({ refresh() {}, replace() {} }) }));
+vi.mock("next/navigation.js", () => ({ useRouter: () => ({ refresh() {}, replace() {} }) }));
 
 const { DraftPreviewIndicator, StudioBridge, StudioPage } = await import("./index.ts");
 
diff --git a/tests/studio-shortcut.test.ts b/tests/studio-shortcut.test.ts
index b5020d08..ef40ab9f 100644
--- a/tests/studio-shortcut.test.ts
+++ b/tests/studio-shortcut.test.ts
@@ -25,7 +25,7 @@ import { STUDIO_BRIDGE_SCRIPT } from "../packages/blocks/src/v8/preview/StudioBr
 import * as nextShortcut from "../packages/nextjs/src/studioShortcut.ts";
 
 // StudioBridge renders StudioRefresh, which needs the App Router mounted.
-vi.mock("next/navigation", () => ({ useRouter: () => ({ refresh() {}, replace() {} }) }));
+vi.mock("next/navigation.js", () => ({ useRouter: () => ({ refresh() {}, replace() {} }) }));
 
 import * as tanstackShortcut from "../packages/tanstack/src/studioShortcut.ts";
 

From 7affbf8e3949f8a4756c14a92e0dc38df43f9f50 Mon Sep 17 00:00:00 2001
From: gimenes <tlgimenes@gmail.com>
Date: Tue, 10 Nov 2026 14:56:39 -0300
Subject: [PATCH 3/3] fix(tanstack): load a save once when the loaders depend
 on the draft pointer

A route whose loader deps include `__draft` already loads on the move to
the save's URL; invalidating every match after it loaded the page a second
time, and the preview rendered the save twice. Only matches the navigation
didn't load are invalidated now.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../tanstack/src/react/StudioRefresh.test.tsx | 53 +++++++++++++++----
 packages/tanstack/src/react/StudioRefresh.ts  | 13 ++++-
 2 files changed, 54 insertions(+), 12 deletions(-)

diff --git a/packages/tanstack/src/react/StudioRefresh.test.tsx b/packages/tanstack/src/react/StudioRefresh.test.tsx
index 7575c518..5c456e50 100644
--- a/packages/tanstack/src/react/StudioRefresh.test.tsx
+++ b/packages/tanstack/src/react/StudioRefresh.test.tsx
@@ -4,14 +4,26 @@ import { createRoot, type Root } from "react-dom/client";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 const calls = vi.hoisted(() => [] as string[]);
-const router = vi.hoisted(() => ({
-  navigate: vi.fn(async (opts: { href: string }) => {
-    calls.push(`navigate ${opts.href}`);
-  }),
-  invalidate: vi.fn(async () => {
-    calls.push("invalidate");
-  }),
-}));
+type Match = { id: string; updatedAt: number };
+const router = vi.hoisted(() => {
+  const r = {
+    state: { matches: [] as Match[] },
+    /** What a navigation loads: the ids it gives a fresh `updatedAt`. */
+    reloads: [] as string[],
+    navigate: vi.fn(async (opts: { href: string }) => {
+      calls.push(`navigate ${opts.href}`);
+      const now = Date.now();
+      r.state.matches = r.state.matches.map((m) =>
+        r.reloads.includes(m.id) ? { ...m, updatedAt: now } : m,
+      );
+    }),
+    invalidate: vi.fn(async (opts?: { filter?: (m: Match) => boolean }) => {
+      const ids = opts?.filter ? r.state.matches.filter(opts.filter).map((m) => m.id) : ["*"];
+      calls.push(`invalidate ${ids.join(",")}`);
+    }),
+  };
+  return r;
+});
 vi.mock("@tanstack/react-router", () => ({ useRouter: () => router }));
 
 const { StudioRefresh } = await import("./StudioRefresh.ts");
@@ -28,6 +40,11 @@ beforeEach(async () => {
   calls.length = 0;
   router.navigate.mockClear();
   router.invalidate.mockClear();
+  router.state.matches = [
+    { id: "__root__", updatedAt: 0 },
+    { id: "/shoes", updatedAt: 0 },
+  ];
+  router.reloads = [];
   globalThis.fetch = vi.fn(async (input: RequestInfo | URL) => {
     calls.push(`fetch ${String(input)}`);
     return new Response("<html></html>");
@@ -45,13 +62,17 @@ afterEach(async () => {
 describe("StudioRefresh", () => {
   it("reruns the loaders for the page's own URL, fetching nothing else", async () => {
     await slot()!(window.location.href);
-    expect(calls).toEqual(["invalidate"]);
+    expect(calls).toEqual(["invalidate *"]);
   });
 
   it("a moved draft pointer: the link's cookie first, then the URL, then the loaders", async () => {
     const next = `${window.location.origin}/shoes?__draft=b`;
     await slot()!(next);
-    expect(calls).toEqual([`fetch ${next}`, "navigate /shoes?__draft=b", "invalidate"]);
+    expect(calls).toEqual([
+      `fetch ${next}`,
+      "navigate /shoes?__draft=b",
+      "invalidate __root__,/shoes",
+    ]);
     expect(router.navigate).toHaveBeenCalledWith({
       href: "/shoes?__draft=b",
       replace: true,
@@ -59,6 +80,18 @@ describe("StudioRefresh", () => {
     });
   });
 
+  it("a moved draft pointer the loaders depend on: the navigation's load is the only one", async () => {
+    router.reloads = ["__root__", "/shoes"];
+    await slot()!(`${window.location.origin}/shoes?__draft=b`);
+    expect(router.invalidate).not.toHaveBeenCalled();
+  });
+
+  it("a moved draft pointer only the page depends on: the rest is invalidated, not the page", async () => {
+    router.reloads = ["/shoes"];
+    await slot()!(`${window.location.origin}/shoes?__draft=b`);
+    expect(calls.at(-1)).toBe("invalidate __root__");
+  });
+
   it("rejects when the new link fails, leaving the page as it is", async () => {
     globalThis.fetch = vi.fn(async () => new Response("", { status: 500 })) as typeof fetch;
     await expect(slot()!(`${window.location.origin}/shoes?__draft=b`)).rejects.toThrow(/500/);
diff --git a/packages/tanstack/src/react/StudioRefresh.ts b/packages/tanstack/src/react/StudioRefresh.ts
index c11bd232..5c9864ee 100644
--- a/packages/tanstack/src/react/StudioRefresh.ts
+++ b/packages/tanstack/src/react/StudioRefresh.ts
@@ -9,7 +9,9 @@
  * A new URL of the page (a save moved the draft pointer in `?__draft=`) first
  * goes to the worker as a document request, only for its draft cookie: the
  * loaders' server-function calls carry the cookie, not the page's query. Then
- * the router moves to the URL and reruns the loaders.
+ * the router moves to the URL. A route whose loader deps include `__draft`
+ * loads again on that move; only the matches it didn't load are invalidated,
+ * so the page renders the save once.
  *
  * Set on every page, framed or not: Studio's module is the only caller, and
  * comparing the window with its parent here is what a test runner's
@@ -30,6 +32,7 @@ export function StudioRefresh(): null {
       if (target.origin !== location.origin) {
         throw new Error(`Not this page's origin: ${target.origin}`);
       }
+      let loadedSince: number | null = null;
       if (target.href !== location.href) {
         const res = await fetch(target.href, {
           headers: { accept: "text/html" },
@@ -38,13 +41,19 @@ export function StudioRefresh(): null {
         });
         await res.body?.cancel();
         if (!res.ok) throw new Error(`The page answered ${res.status}`);
+        loadedSince = Date.now();
         await router.navigate({
           href: `${target.pathname}${target.search}${target.hash}`,
           replace: true,
           resetScroll: false,
         });
       }
-      await router.invalidate();
+      if (loadedSince === null) return router.invalidate();
+      const since = loadedSince;
+      const stale = router.state.matches.filter((m) => m.updatedAt < since);
+      if (stale.length === 0) return;
+      const ids = new Set(stale.map((m) => m.id));
+      await router.invalidate({ filter: (m) => ids.has(m.id) });
     };
     const slot = window as unknown as Record<string, unknown>;
     slot[STUDIO_PAGE_REFRESH] = refresh;