@decocms/tanstack 8.0.0 → 8.1.0-next.0

package/src/hooks/DecoRootLayout.tsx

@@ -1,19 +1,28 @@
-import { useEffect, type ReactNode } from "react";
-import { HeadContent, Scripts, ScriptOnce } from "@tanstack/react-router";
-import { LiveControls } from "@decocms/blocks/hooks";
-import { ANALYTICS_SCRIPT } from "@decocms/blocks/sdk/analytics";
+import { LiveControls, Stats } from "@decocms/blocks/hooks";
+import { ANALYTICS_SCRIPT, SPECULATION_DEV_WARN_SCRIPT } from "@decocms/blocks/sdk/analytics";
+import { isDevMode } from "@decocms/blocks/sdk/env";
+import { getRequestNonce } from "@decocms/blocks/sdk/nonce";
+import { HeadContent, ScriptOnce, Scripts, useRouterState } from "@tanstack/react-router";
+import { type ReactNode, useEffect } from "react";
+import {
+  buildSpeculationRules,
+  getSpeculationRules,
+  type SpeculationRulesConfig,
+} from "../sdk/speculationRules";
+import { CdnSegmentMarker } from "./CdnSegmentMarker";
+import { DraftPreviewIndicator } from "./DraftPreviewIndicator";
 import { NavigationProgress } from "./NavigationProgress";
 import { StableOutlet } from "./StableOutlet";
 
 declare global {
-	interface Window {
-		__deco_ready?: boolean;
-	}
+  interface Window {
+    __deco_ready?: boolean;
+  }
 }
 
 function buildDecoEventsBootstrap(account?: string): string {
-	const accountJson = JSON.stringify(account ?? "");
-	return `
+  const accountJson = JSON.stringify(account ?? "");
+  return `
 window.__RUNTIME__ = window.__RUNTIME__ || { account: ${accountJson} };
 window.DECO = window.DECO || {};
 window.DECO.events = window.DECO.events || {
@@ -37,23 +46,34 @@ window.dataLayer = window.dataLayer || [];
 }
 
 export interface DecoRootLayoutProps {
-	/** Language attribute for the <html> tag. Default: "en" */
-	lang?: string;
-	/** DaisyUI data-theme attribute. Default: "light" */
-	dataTheme?: string;
-	/** Site name for LiveControls (admin iframe communication). Required. */
-	siteName: string;
-	/** Commerce platform account name for analytics bootstrap (e.g. VTEX account). */
-	account?: string;
-	/** CSS class for <body>. Default: "bg-base-200 text-base-content" */
-	bodyClassName?: string;
-	/** Delay in ms before firing deco:ready event. Default: 500 */
-	decoReadyDelay?: number;
-	/**
-	 * Extra content rendered inside <body> after the main outlet
-	 * (e.g. Toast, custom analytics components).
-	 */
-	children?: ReactNode;
+  /** Language attribute for the <html> tag. Default: "en" */
+  lang?: string;
+  /** DaisyUI data-theme attribute. Default: "light" */
+  dataTheme?: string;
+  /** Site name for LiveControls (admin iframe communication). Required. */
+  siteName: string;
+  /** Commerce platform account name for analytics bootstrap (e.g. VTEX account). */
+  account?: string;
+  /** CSS class for <body>. Default: "bg-base-200 text-base-content" */
+  bodyClassName?: string;
+  /** Delay in ms before firing deco:ready event. Default: 500 */
+  decoReadyDelay?: number;
+  /**
+   * Opt-in Speculation Rules API config override. Normally activated site-wide
+   * via `createDecoWorkerEntry({ speculationRules })` (like `asJson` /
+   * `renderJson`) and read from that shared config; pass this prop only to
+   * override it for a specific root. When set, emits a
+   * `<script type="speculationrules">` in <head> so the browser prerenders/
+   * prefetches the next document on intent. Ships DISABLED — only activate on
+   * sites whose analytics/pixel loaders are prerender-guarded.
+   * @see buildSpeculationRules
+   */
+  speculationRules?: SpeculationRulesConfig;
+  /**
+   * Extra content rendered inside <body> after the main outlet
+   * (e.g. Toast, custom analytics components).
+   */
+  children?: ReactNode;
 }
 
 /**
@@ -74,38 +94,99 @@ export interface DecoRootLayoutProps {
  * pieces (NavigationProgress, StableOutlet, etc.) instead.
  */
 export function DecoRootLayout({
-	lang = "en",
-	dataTheme = "light",
-	siteName,
-	account,
-	bodyClassName = "bg-base-200 text-base-content",
-	decoReadyDelay = 500,
-	children,
+  lang = "en",
+  dataTheme = "light",
+  siteName,
+  account,
+  bodyClassName = "bg-base-200 text-base-content",
+  decoReadyDelay = 500,
+  speculationRules,
+  children,
 }: DecoRootLayoutProps) {
-	useEffect(() => {
-		const id = setTimeout(() => {
-			window.__deco_ready = true;
-			document.dispatchEvent(new Event("deco:ready"));
-		}, decoReadyDelay);
-		return () => clearTimeout(id);
-	}, [decoReadyDelay]);
+  useEffect(() => {
+    const id = setTimeout(() => {
+      window.__deco_ready = true;
+      document.dispatchEvent(new Event("deco:ready"));
+    }, decoReadyDelay);
+    return () => clearTimeout(id);
+  }, [decoReadyDelay]);
+
+  // Pull the resolved CMS page's route pattern (`path` = pathTemplate) and block
+  // id (`blockKey`) out of the current route's loader data so LiveControls sends
+  // the admin the page the user is actually on — not the hardcoded "/*" fallback.
+  // The CMS page loader (cmsRoute) spreads both fields onto its loader data;
+  // we scan matches deepest-first to find the one that carries them.
+  const page = useRouterState({
+    select: (state) => {
+      for (let i = state.matches.length - 1; i >= 0; i--) {
+        const data = state.matches[i]?.loaderData as
+          | { path?: unknown; blockKey?: unknown }
+          | undefined;
+        if (data && typeof data.path === "string") {
+          return {
+            id: typeof data.blockKey === "string" ? data.blockKey : undefined,
+            pathTemplate: data.path,
+          };
+        }
+      }
+      return undefined;
+    },
+  });
+
+  // Worker-entry option wins; prop is a per-root override. Undefined → disabled.
+  const speculation = speculationRules ?? getSpeculationRules();
 
-	return (
-		<html lang={lang} data-theme={dataTheme} suppressHydrationWarning>
-			<head>
-				<HeadContent />
-			</head>
-			<body className={bodyClassName} suppressHydrationWarning>
-				<ScriptOnce children={buildDecoEventsBootstrap(account)} />
-				<NavigationProgress />
-				<main>
-					<StableOutlet />
-				</main>
-				{children}
-				<LiveControls site={siteName} />
-				<ScriptOnce children={ANALYTICS_SCRIPT} />
-				<Scripts />
-			</body>
-		</html>
-	);
+  return (
+    <html lang={lang} data-theme={dataTheme} suppressHydrationWarning>
+      <head>
+        <HeadContent />
+        <CdnSegmentMarker />
+        {speculation && (
+          <script
+            type="speculationrules"
+            nonce={getRequestNonce()}
+            // JSON is inert; dangerouslySetInnerHTML avoids React escaping
+            // `>` in selectors (e.g. "nav > a"). Same pattern as JSON-LD.
+            dangerouslySetInnerHTML={{
+              __html: buildSpeculationRules(speculation),
+            }}
+          />
+        )}
+        {/* Dev-only: console.error when analytics fire during a prerender
+				    so the dev fixes unguarded loaders before shipping. */}
+        {speculation && isDevMode() && (
+          <script
+            nonce={getRequestNonce()}
+            dangerouslySetInnerHTML={{ __html: SPECULATION_DEV_WARN_SCRIPT }}
+          />
+        )}
+      </head>
+      <body className={bodyClassName} suppressHydrationWarning>
+        <ScriptOnce children={buildDecoEventsBootstrap(account)} />
+        {/*
+         * AFTER the bootstrap above, and in the body rather than the head. The collector's
+         * deco module subscribes with `window?.DECO?.events?.subscribe?.(…)` — once,
+         * optional-chained, with no retry. In the head it is an `async` script the parser
+         * can reach and run before the inline bootstrap below it has defined
+         * `DECO.events`, and the subscription would simply not happen: pageviews would
+         * still flow while every commerce event went nowhere, with no error. Here the
+         * parser has already executed the bootstrap.
+         *
+         * Rendering unconditionally is safe — the component returns null unless
+         * DECO_ANALYTICS_ENABLED is exactly "true", which is what makes this an env-var
+         * change for a site instead of a code change.
+         */}
+        <Stats />
+        <NavigationProgress />
+        <main>
+          <StableOutlet />
+        </main>
+        {children}
+        <DraftPreviewIndicator />
+        <LiveControls site={siteName} page={page} />
+        <ScriptOnce children={ANALYTICS_SCRIPT} />
+        <Scripts />
+      </body>
+    </html>
+  );
 }

package/src/hooks/DraftPreviewIndicator.test.tsx

@@ -0,0 +1,60 @@
+import { RequestContext } from "@decocms/blocks/sdk/requestContext";
+import { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { renderToString } from "react-dom/server";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import { DRAFT_POINTER_BAG_KEY, DRAFT_POINTER_GLOBAL } from "../sdk/draftShared";
+import { DraftPreviewIndicator } from "./DraftPreviewIndicator";
+
+const POINTER = "abc.preview-studio.decocms.com@v1";
+
+function renderInRequest(pointer: string | null): string {
+  return RequestContext.run(new Request("https://example.com/"), () => {
+    if (pointer) RequestContext.setBag(DRAFT_POINTER_BAG_KEY, pointer);
+    return renderToString(<DraftPreviewIndicator />);
+  });
+}
+
+describe("DraftPreviewIndicator — SSR", () => {
+  it("publishes the pointer on a global so client hydration matches", () => {
+    const html = renderInRequest(POINTER);
+    expect(html).toContain(`window.${DRAFT_POINTER_GLOBAL}=`);
+    expect(html).toContain(JSON.stringify(POINTER));
+    // The chip itself fails closed — nothing visible until the client effect.
+    expect(html).not.toContain("Preview mode");
+  });
+
+  it("renders nothing when the request is not drafting", () => {
+    expect(renderInRequest(null)).toBe("");
+  });
+});
+
+describe("DraftPreviewIndicator — client", () => {
+  let container: HTMLDivElement;
+  let root: Root;
+  const win = window as unknown as Record<string, string | undefined>;
+
+  beforeEach(() => {
+    container = document.createElement("div");
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(() => {
+    act(() => root.unmount());
+    container.remove();
+    win[DRAFT_POINTER_GLOBAL] = undefined;
+  });
+
+  it("mounts the badge from the published global (cookie-nav, no bag on the client)", () => {
+    win[DRAFT_POINTER_GLOBAL] = POINTER;
+    act(() => root.render(<DraftPreviewIndicator />));
+    expect(container.textContent).toContain("Preview mode");
+  });
+
+  it("renders nothing when no pointer is published", () => {
+    act(() => root.render(<DraftPreviewIndicator />));
+    expect(container.textContent).toBe("");
+  });
+});

package/src/hooks/DraftPreviewIndicator.tsx

@@ -0,0 +1,64 @@
+/**
+ * Preview-mode badge gate — the TanStack binding.
+ *
+ * Mounts the shared `DraftPreviewBadge` (`@decocms/blocks/preview`) only when
+ * the request is rendering a draft. `DecoRootLayout` renders it automatically,
+ * so sites get the badge on a package bump with no code change; it renders
+ * nothing at all on ordinary (published) traffic.
+ *
+ * ## Isomorphic pointer, hydration-safe
+ *
+ * TanStack Start renders this component on BOTH server and client (no RSC
+ * boundary). The pointer only exists server-side (the request bag), so:
+ *
+ *  - **Server:** read it from `RequestContext` and emit a tiny inline `<script>`
+ *    that publishes it on `window.<GLOBAL>`. Inline scripts execute during HTML
+ *    parse, before hydration.
+ *  - **Client:** `RequestContext` resolves to a no-op stub in the browser
+ *    bundle (the `browser` export condition), so the bag read returns
+ *    undefined and we fall back to `window.<GLOBAL>` — which the just-executed
+ *    inline script set to the server's value, so the hydration render computes
+ *    the SAME pointer and the `<script>` node reconciles cleanly.
+ *
+ * Reading the bag first (then the global) — rather than branching on
+ * `typeof window` — is also what makes this testable under jsdom, where
+ * `window` always exists.
+ *
+ * The badge itself starts hidden and reveals via a client effect (fails
+ * closed), so the visible chip never participates in the hydration diff.
+ */
+import { DraftPreviewBadge } from "@decocms/blocks/preview";
+import { getRequestNonce } from "@decocms/blocks/sdk/nonce";
+import { RequestContext } from "@decocms/blocks/sdk/requestContext";
+import { DRAFT_POINTER_BAG_KEY, DRAFT_POINTER_GLOBAL } from "../sdk/draftShared";
+
+/**
+ * The active draft pointer. Server: the request bag (set by `bindRequestDraft`).
+ * Client: the bag is a stub → undefined → fall back to the published global.
+ */
+function activePointer(): string | null {
+  const fromBag = RequestContext.getBag<string>(DRAFT_POINTER_BAG_KEY);
+  if (fromBag) return fromBag;
+  if (typeof window !== "undefined") {
+    return (window as unknown as Record<string, string | undefined>)[DRAFT_POINTER_GLOBAL] ?? null;
+  }
+  return null;
+}
+
+export function DraftPreviewIndicator() {
+  const pointer = activePointer();
+  if (!pointer) return null;
+  return (
+    <>
+      {/* Publishes a JSON-encoded pointer this server resolved (not user
+          input) so the client's hydration render matches. See the module doc. */}
+      <script
+        nonce={getRequestNonce()}
+        dangerouslySetInnerHTML={{
+          __html: `window.${DRAFT_POINTER_GLOBAL}=${JSON.stringify(pointer)}`,
+        }}
+      />
+      <DraftPreviewBadge pointer={pointer} />
+    </>
+  );
+}

package/src/hooks/NavigationProgress.test.tsx

@@ -0,0 +1,58 @@
+import { renderToStaticMarkup } from "react-dom/server";
+import { describe, expect, it, vi } from "vitest";
+
+// The component only needs the router's isLoading flag.
+let isLoading = true;
+vi.mock("@tanstack/react-router", () => ({
+  useRouterState: ({ select }: { select: (s: { isLoading: boolean }) => unknown }) =>
+    select({ isLoading }),
+}));
+
+const { NavigationProgress } = await import("./NavigationProgress");
+
+/**
+ * The bug this guards: the bar used to be painted with the Tailwind utility
+ * `bg-brand-primary-500`. That token is a *site* concern — framework code
+ * cannot assume it exists. On a Tailwind v4 theme that resets
+ * `--color-*: initial` the utility is never generated, so the class resolves to
+ * nothing and the bar is fully transparent: an invisible progress indicator, in
+ * production, with no build error and nothing in the console.
+ *
+ * The fix paints through an inline custom-property expression, which a CSS build
+ * cannot elide. It has to satisfy BOTH directions at once: sites that never
+ * defined the token must still see a bar, and sites that DID must keep their
+ * brand color rather than silently dropping to black — hence the var-with-
+ * fallback rather than a bare `currentColor`.
+ */
+describe("NavigationProgress — visibility does not depend on site color tokens", () => {
+  it("paints via inline style, never a site-defined Tailwind color utility", () => {
+    isLoading = true;
+    const html = renderToStaticMarkup(<NavigationProgress />);
+
+    expect(html).not.toMatch(/bg-brand-/);
+    expect(html).toMatch(/background-color:\s*currentColor/);
+  });
+
+  it("keeps the brand token when the site defines it, and falls back when it does not", () => {
+    isLoading = true;
+    const html = renderToStaticMarkup(<NavigationProgress />);
+
+    // Both halves matter: the var preserves branding for sites where the old
+    // utility worked, the fallback is what makes it visible for those where it
+    // silently did not.
+    expect(html).toContain("--color-brand-primary-500");
+    expect(html).toMatch(/var\(--color-brand-primary-500,\s*currentColor\)/);
+  });
+
+  it("accepts an explicit color so a site can brand it without that token name", () => {
+    isLoading = true;
+    const html = renderToStaticMarkup(<NavigationProgress color="#ff0080" />);
+    expect(html).toContain("#ff0080");
+    expect(html).not.toContain("--color-brand-primary-500");
+  });
+
+  it("renders nothing when the router is idle", () => {
+    isLoading = false;
+    expect(renderToStaticMarkup(<NavigationProgress />)).toBe("");
+  });
+});

package/src/hooks/NavigationProgress.tsx

@@ -5,17 +5,59 @@ const PROGRESS_CSS = `
 .nav-progress-bar { animation: progressSlide 1s ease-in-out infinite; }
 `;
 
+/**
+ * Brand token when the site defines it, inherited text color when it does not.
+ *
+ * The bar used to be painted with the Tailwind utility `bg-brand-primary-500`.
+ * That token is a *site* concern, and framework code cannot assume it exists: on
+ * a Tailwind v4 theme that resets `--color-*: initial` the utility is never
+ * generated, so the class resolved to nothing and the bar rendered fully
+ * transparent — an invisible progress indicator, in production, with no build
+ * error and nothing in the console.
+ *
+ * A CSS custom property with a fallback fixes that without regressing the sites
+ * where it already worked: they keep their brand color (Tailwind v4 emits
+ * `--color-brand-primary-500` for a `brand-primary` palette entry), and
+ * everyone else falls back to `currentColor` instead of nothing. Unlike a
+ * utility class, neither half can be dropped by a CSS build.
+ */
+const DEFAULT_COLOR = "var(--color-brand-primary-500, currentColor)";
+
+export interface NavigationProgressProps {
+	/**
+	 * Bar color. Any CSS color or custom-property expression. Defaults to
+	 * {@link DEFAULT_COLOR} — the site's `brand-primary-500` token when defined,
+	 * otherwise the inherited text color. Pass an explicit value to brand the bar
+	 * without relying on that token name.
+	 */
+	color?: string;
+}
+
 /**
  * Top-of-page loading bar that appears during SPA navigation.
  * Uses the router's isLoading state — no extra dependencies.
  */
-export function NavigationProgress() {
+export function NavigationProgress({ color = DEFAULT_COLOR }: NavigationProgressProps = {}) {
 	const isLoading = useRouterState({ select: (s) => s.isLoading });
 	if (!isLoading) return null;
 	return (
-		<div className="fixed top-0 left-0 right-0 z-[9999] h-1 bg-brand-primary-500/20 overflow-hidden">
+		<div
+			className="fixed top-0 left-0 right-0 z-[9999] h-1 overflow-hidden"
+			style={{ color }}
+			role="progressbar"
+			aria-label="Carregando página"
+		>
 			<style dangerouslySetInnerHTML={{ __html: PROGRESS_CSS }} />
-			<div className="nav-progress-bar h-full w-1/3 bg-brand-primary-500 rounded-full" />
+			{/* Track and bar are siblings so the track's 20% alpha does not
+			    inherit onto the bar (opacity applies to the whole subtree). */}
+			<div
+				className="absolute inset-0"
+				style={{ backgroundColor: "currentColor", opacity: 0.2 }}
+			/>
+			<div
+				className="nav-progress-bar absolute inset-y-0 left-0 w-1/3 rounded-full"
+				style={{ backgroundColor: "currentColor" }}
+			/>
 		</div>
 	);
 }

package/src/hooks/PreviewProviders.test.tsx

@@ -0,0 +1,42 @@
+import { useQuery } from "@tanstack/react-query";
+import { useRouter } from "@tanstack/react-router";
+import { renderToString } from "react-dom/server";
+import { describe, expect, it } from "vitest";
+
+import PreviewProviders from "./PreviewProviders";
+
+// A section that reads React Query at render time — the exact shape that made
+// the /live/previews in-place render throw "No QueryClient set" for commerce
+// sections (e.g. Carousel.tsx) before PreviewProviders provided a client.
+function SectionUsingQuery() {
+  const { data } = useQuery({ queryKey: ["preview-probe"], queryFn: () => "loaded" });
+  return <div data-testid="section">{data ?? "loading"}</div>;
+}
+
+function SectionUsingRouter() {
+  const router = useRouter();
+  return <div data-testid="router">{router ? "has-router" : "no-router"}</div>;
+}
+
+describe("PreviewProviders", () => {
+  it("renders a section that calls useQuery without throwing", () => {
+    const html = renderToString(
+      <PreviewProviders>
+        <SectionUsingQuery />
+      </PreviewProviders>,
+    );
+    // No QueryClient error, and the section renders its pending state (static
+    // preview render — the query never resolves during renderToString).
+    expect(html).toContain("loading");
+    expect(html).not.toContain("No QueryClient");
+  });
+
+  it("still provides the TanStack Router context", () => {
+    const html = renderToString(
+      <PreviewProviders>
+        <SectionUsingRouter />
+      </PreviewProviders>,
+    );
+    expect(html).toContain("has-router");
+  });
+});

package/src/hooks/PreviewProviders.tsx

@@ -1,3 +1,4 @@
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
 import {
   createMemoryHistory,
   createRootRoute,
@@ -16,11 +17,29 @@ const previewRouter = createRouter({
   history: createMemoryHistory({ initialEntries: ["/"] }),
 });
 
+// A dedicated QueryClient for preview renders. Sections that call useQuery /
+// useQueryClient at render time (e.g. commerce shelves, carousels) would
+// otherwise throw "No QueryClient set" during the admin's isolated
+// renderToString pass — the site's production QueryClientProvider (wired via
+// createDecoRouter's `Wrap`) is not in scope on the /live/previews path.
+// Retries are disabled so a preview render never hangs on a failing query;
+// this is a static content render (matches __decoFBT=0), so cached data is
+// not expected here.
+const previewQueryClient = new QueryClient({
+  defaultOptions: { queries: { retry: false } },
+});
+
 /**
  * Default preview wrapper for admin iframe rendering.
  * Provides a TanStack Router context with memory history so components
- * that depend on router hooks (Link, useNavigate, etc.) work in previews.
+ * that depend on router hooks (Link, useNavigate, etc.) work in previews,
+ * plus a QueryClientProvider so components that call React Query hooks at
+ * render time don't crash the preview.
  */
 export default function PreviewProviders({ children }: { children: ReactNode }) {
-  return <RouterContextProvider router={previewRouter as any}>{children}</RouterContextProvider>;
+  return (
+    <QueryClientProvider client={previewQueryClient}>
+      <RouterContextProvider router={previewRouter as any}>{children}</RouterContextProvider>
+    </QueryClientProvider>
+  );
 }

package/src/hooks/deferredObserverTiming.test.tsx

@@ -0,0 +1,91 @@
+import { act, useEffect, useLayoutEffect, useState } from "react";
+import { createRoot } from "react-dom/client";
+import { describe, expect, it } from "vitest";
+
+/**
+ * Guards the frame gate in `DeferredSectionWrapper`'s IntersectionObserver
+ * effect (`DecoPageRenderer.tsx`).
+ *
+ * Enabling deferral on client navigation made a latent ordering problem
+ * reachable. On a SPA transition the scroll position is still wherever the user
+ * left the previous page when the new page's skeletons mount. TanStack resets it
+ * from the `onRendered` event, emitted by a `useLayoutEffect` in react-router's
+ * `OnRendered` that depends on the `resolvedLocation` store — which is itself
+ * written from another `useLayoutEffect` (`Transitioner`). The reset therefore
+ * lands one commit AFTER the mount commit, and React flushes the mount commit's
+ * passive effects before starting that follow-up render.
+ *
+ * Net effect without a gate: the observer evaluates intersection against the
+ * stale offset, so a user navigating from the bottom of a long page has every
+ * skeleton in view simultaneously and every deferred section fires its serverFn
+ * POST at once — the thundering herd deferral exists to avoid.
+ *
+ * This models that exact effect topology rather than mounting the real router,
+ * because the ordering is a property of React's commit/flush sequence, not of
+ * TanStack. If React ever changes it so passive effects run after a
+ * layout-effect-triggered re-render, the first case flips and the gate can go.
+ */
+function runOrdering(gate: "none" | "raf") {
+  const order: string[] = [];
+
+  /** Stands in for TanStack's Transitioner writing `resolvedLocation`. */
+  function Transitioner({ setResolved }: { setResolved: (n: number) => void }) {
+    useLayoutEffect(() => setResolved(1), [setResolved]);
+    return null;
+  }
+
+  /** Stands in for `OnRendered` → `onRendered` → scroll-restoration reset. */
+  function OnRendered({ resolved }: { resolved: number }) {
+    useLayoutEffect(() => {
+      if (resolved > 0) order.push("SCROLL_RESET");
+    }, [resolved]);
+    return null;
+  }
+
+  /** Stands in for DeferredSectionWrapper's observer effect. */
+  function DeferredWrapper() {
+    useEffect(() => {
+      const observe = () => order.push("OBSERVE");
+      if (gate === "none") {
+        observe();
+        return;
+      }
+      const raf = requestAnimationFrame(observe);
+      return () => cancelAnimationFrame(raf);
+    }, []);
+    return null;
+  }
+
+  function App() {
+    const [resolved, setResolved] = useState(0);
+    return (
+      <>
+        {/* Deliberately first: children flush before the root's own effects. */}
+        <DeferredWrapper />
+        <Transitioner setResolved={setResolved} />
+        <OnRendered resolved={resolved} />
+      </>
+    );
+  }
+
+  const el = document.createElement("div");
+  document.body.appendChild(el);
+  act(() => {
+    createRoot(el).render(<App />);
+  });
+  return order;
+}
+
+describe("deferred observer vs router scroll reset", () => {
+  it("observing synchronously loses the race — this is why the gate exists", () => {
+    // If this ever reports SCROLL_RESET first, React's flush order changed and
+    // the requestAnimationFrame gate in DecoPageRenderer is dead weight.
+    expect(runOrdering("none")).toEqual(["OBSERVE", "SCROLL_RESET"]);
+  });
+
+  it("one frame is enough for the scroll reset to land first", () => {
+    // rAF does not run inside act(), so the reset is the only thing recorded —
+    // i.e. observation is strictly after it, which is the point.
+    expect(runOrdering("raf")).toEqual(["SCROLL_RESET"]);
+  });
+});

package/src/hooks/index.ts

@@ -4,6 +4,7 @@ export {
   SectionRenderer,
 } from "./DecoPageRenderer";
 export { DecoRootLayout, type DecoRootLayoutProps } from "./DecoRootLayout";
+export { DraftPreviewIndicator } from "./DraftPreviewIndicator";
 export { NavigationProgress } from "./NavigationProgress";
 export { StableOutlet } from "./StableOutlet";
 export { default as PreviewProviders } from "./PreviewProviders";