@decocms/nextjs 7.31.2 → 7.31.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/nextjs",
-  "version": "7.31.2",
+  "version": "7.31.3",
   "type": "module",
   "engines": {
     "node": ">=24"
@@ -29,8 +29,8 @@
     "lint:unused": "knip"
   },
   "dependencies": {
-    "@decocms/blocks": "7.31.2",
-    "@decocms/blocks-admin": "7.31.2"
+    "@decocms/blocks": "7.31.3",
+    "@decocms/blocks-admin": "7.31.3"
   },
   "peerDependencies": {
     "next": ">=15.0.0",

package/src/DraftPreviewBadge.render.test.tsx

@@ -1,32 +1,67 @@
+import { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
 import { renderToString } from "react-dom/server";
-import { afterEach, describe, expect, it } from "vitest";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
 
 import { DraftPreviewBadge } from "./DraftPreviewBadge";
 
 describe("DraftPreviewBadge (render)", () => {
-  it("surfaces the preview-mode label so a reviewer can't mistake a draft for live", () => {
+  // Raw SSR (react-dom/server) never runs effects — this is what a consumer
+  // site that never hydrates this component, or the server's own render
+  // pass, actually ships. The badge fails closed: nothing here, by design
+  // (see the module doc for why render-then-hide is worse).
+  it("renders nothing without a client to run the reveal effect", () => {
     const html = renderToString(<DraftPreviewBadge pointer="fila.vtex.app@v1" />);
-    expect(html).toContain("Preview mode");
+    expect(html).toBe("");
   });
 
-  it("embeds the deco mark inline (no external asset that could 404 on a consumer site)", () => {
-    const html = renderToString(<DraftPreviewBadge pointer="fila.vtex.app@v1" />);
-    expect(html).toContain("data:image/png;base64,");
-  });
+  describe("mounted in a browser", () => {
+    let container: HTMLDivElement;
+    let root: Root;
+
+    beforeEach(() => {
+      container = document.createElement("div");
+      document.body.appendChild(container);
+      root = createRoot(container);
+    });
 
-  describe("embedded in an iframe", () => {
-    const realTop = window.top;
     afterEach(() => {
-      Object.defineProperty(window, "top", {
-        value: realTop,
-        configurable: true,
+      act(() => {
+        root.unmount();
+      });
+      container.remove();
+    });
+
+    it("reveals the preview-mode label after mount, once confirmed unframed", () => {
+      act(() => {
+        root.render(<DraftPreviewBadge pointer="fila.vtex.app@v1" />);
       });
+      expect(container.textContent).toContain("Preview mode");
     });
 
-    it("renders nothing — Studio's own preview surface already has its own chrome", () => {
-      Object.defineProperty(window, "top", { value: {}, configurable: true });
-      const html = renderToString(<DraftPreviewBadge pointer="fila.vtex.app@v1" />);
-      expect(html).toBe("");
+    it("embeds the deco mark inline (no external asset that could 404 on a consumer site)", () => {
+      act(() => {
+        root.render(<DraftPreviewBadge pointer="fila.vtex.app@v1" />);
+      });
+      expect(container.innerHTML).toContain("data:image/png;base64,");
+    });
+
+    describe("embedded in an iframe", () => {
+      const realTop = window.top;
+      afterEach(() => {
+        Object.defineProperty(window, "top", {
+          value: realTop,
+          configurable: true,
+        });
+      });
+
+      it("stays hidden — Studio's own preview surface already has its own chrome", () => {
+        Object.defineProperty(window, "top", { value: {}, configurable: true });
+        act(() => {
+          root.render(<DraftPreviewBadge pointer="fila.vtex.app@v1" />);
+        });
+        expect(container.textContent).toBe("");
+      });
     });
   });
 });

package/src/DraftPreviewBadge.tsx

@@ -22,6 +22,15 @@
  * inside that frame would be redundant clutter, not a signal a reviewer
  * needs. A reviewer following a shared preview link in their own top-level
  * tab still sees it; only the embedded case is suppressed.
+ *
+ * Renders NOTHING until a client-side effect confirms it's safe to show —
+ * fails closed, not open. `isFramed()` needs `window`, so it can only ever
+ * be evaluated in the browser; rendering the badge by default and hiding it
+ * once framing is detected would flash it for a beat inside Studio's own
+ * iframe before it disappeared, and would hydration-mismatch (server has no
+ * `window`, so it would always render the "unframed" branch). Starting
+ * hidden on both the server and the client's matching first render, then
+ * revealing via `useEffect` only when confirmed unframed, avoids both.
  */
 import { type ReactNode, useCallback, useEffect, useRef, useState } from "react";
 import { DECO_MARK_DATA_URI } from "./decoMark";
@@ -60,10 +69,10 @@ export function buildExitUrl(href: string): string {
  * Whether this render is embedded in another page's iframe — Studio's own
  * preview surface, primarily. `window.top !== window` is a same-origin
  * reference comparison, so it never throws cross-origin (unlike reading a
- * cross-origin frame's properties). No `window` (SSR, or a consumer site
- * that never hydrates this component) reports not-framed — fails open,
- * matching the badge's "renders the same on any consumer site" guarantee.
- * Pure and exported for tests.
+ * cross-origin frame's properties). No `window` reports not-framed — a safe
+ * default for the function itself, though the badge only ever calls this
+ * from a `useEffect`, where `window` always exists. Pure and exported for
+ * tests.
  */
 export function isFramed(win: typeof window | undefined = globalThis.window): boolean {
   return typeof win !== "undefined" && win.top !== win;
@@ -119,8 +128,18 @@ function ShareIcon() {
 export function DraftPreviewBadge({ pointer }: DraftPreviewBadgeProps) {
   const [open, setOpen] = useState(false);
   const [copied, setCopied] = useState(false);
+  const [visible, setVisible] = useState(false);
   const rootRef = useRef<HTMLDivElement>(null);
 
+  // Reveal only after mount, and only when confirmed unframed — fails
+  // closed. Server and client's matching first render both start at this
+  // same `false`, so there's no hydration mismatch; this effect (client
+  // only, runs once) is the sole place `isFramed()` is ever evaluated. See
+  // the module doc for why the alternative (render then hide) is worse.
+  useEffect(() => {
+    if (!isFramed()) setVisible(true);
+  }, []);
+
   // Dismiss on outside click or Escape — standard popover behaviour, and it
   // keeps the badge from trapping focus on a reviewer's own page.
   useEffect(() => {
@@ -157,11 +176,7 @@ export function DraftPreviewBadge({ pointer }: DraftPreviewBadgeProps) {
     }
   }, [pointer]);
 
-  // Checked inline, not cached in state behind an effect: it's a free
-  // reference compare, and computing it during render means the client's
-  // first (hydration) pass already agrees with what it will show — no
-  // post-hydration flash for the common (unframed) case.
-  if (isFramed()) return null;
+  if (!visible) return null;
 
   return (
     <div