Fix preview navigation black screen when selecting routes from dropdown (#2610)

e2e-tests/refresh.spec.ts

@@ -153,3 +153,28 @@ testSkipIfWindows(
     ).toBeVisible({ timeout: Timeout.MEDIUM });
   },
 );
+
+testSkipIfWindows(
+  "spa navigation inside iframe does not change iframe src attribute",
+  async ({ po }) => {
+    await po.setUp({ autoApprove: true });
+    await po.sendPrompt("tc=multi-page");
+
+    await po.previewPanel.expectPreviewIframeIsVisible();
+
+    const iframe = po.previewPanel.getPreviewIframeElement();
+    await expect(
+      iframe.contentFrame().getByRole("heading", { name: "Home Page" }),
+    ).toBeVisible({ timeout: Timeout.LONG });
+
+    const srcBeforeNavigation = await iframe.getAttribute("src");
+
+    await iframe.contentFrame().getByText("Go to About Page").click();
+    await expect(
+      iframe.contentFrame().getByRole("heading", { name: "About Page" }),
+    ).toBeVisible({ timeout: Timeout.MEDIUM });
+
+    const srcAfterNavigation = await iframe.getAttribute("src");
+    expect(srcAfterNavigation).toBe(srcBeforeNavigation);
+  },
+);

src/components/preview_panel/PreviewIframe.tsx

@@ -6,7 +6,7 @@ import {
   previewCurrentUrlAtom,
 } from "@/atoms/appAtoms";
 import { useAtomValue, useSetAtom, useAtom } from "jotai";
-import { useEffect, useRef, useState } from "react";
+import { useEffect, useMemo, useRef, useState } from "react";
 import {
   ArrowLeft,
   ArrowRight,
@@ -936,10 +936,15 @@ export const PreviewIframe = ({ loading }: { loading: boolean }) => {
       const baseUrl = new URL(appUrl).origin;
       const newUrl = `${baseUrl}${path}`;
 
-      // Navigate to the URL
-      iframeRef.current.contentWindow.location.href = newUrl;
-
-      // iframeRef.current.src = newUrl;
+      // Use postMessage to navigate (same as back/forward) - this uses location.replace()
+      // which provides smooth navigation without the black screen flicker that location.href causes
+      iframeRef.current.contentWindow.postMessage(
+        {
+          type: "navigate",
+          payload: { url: newUrl },
+        },
+        "*",
+      );
 
       // Update navigation history
       const newHistory = [
@@ -950,9 +955,50 @@ export const PreviewIframe = ({ loading }: { loading: boolean }) => {
       setCurrentHistoryPosition(newHistory.length - 1);
       setCanGoBack(true);
       setCanGoForward(false);
+
+      // Update iframe URL ref to match
+      currentIframeUrlRef.current = newUrl;
+
+      // Update preservedUrls to match navigation (for HMR remounts)
+      if (selectedAppId) {
+        // Clear preserved URL if navigating to root, otherwise update it
+        if (path === "/" || path === "") {
+          setPreservedUrls((prev) => {
+            const newUrls = { ...prev };
+            delete newUrls[selectedAppId];
+            return newUrls;
+          });
+        } else {
+          setPreservedUrls((prev) => ({
+            ...prev,
+            [selectedAppId]: newUrl,
+          }));
+        }
+      }
     }
   };
 
+  // Freeze iframe src between remounts so in-iframe SPA navigation (pushState/replaceState)
+  // doesn't cause React to set a new src and trigger a second full navigation flicker.
+  const iframeSrc = useMemo(() => {
+    if (!appUrl) {
+      return undefined;
+    }
+
+    const currentUrl = currentIframeUrlRef.current;
+    if (!currentUrl) {
+      return appUrl;
+    }
+
+    try {
+      const currentOrigin = new URL(currentUrl).origin;
+      const appOrigin = new URL(appUrl).origin;
+      return currentOrigin === appOrigin ? currentUrl : appUrl;
+    } catch {
+      return appUrl;
+    }
+  }, [appUrl, reloadKey, selectedAppId]);
+
   // Display loading state
   if (loading) {
     return (
@@ -984,9 +1030,6 @@ export const PreviewIframe = ({ loading }: { loading: boolean }) => {
     restartApp();
   };
 
-  // Convert null to undefined for iframe src prop compatibility
-  const iframeSrc = currentIframeUrlRef.current ?? appUrl ?? undefined;
-
   return (
     <div className="flex flex-col h-full">
       {/* Browser-style header - hide when annotator is active */}