feat(FN-2172): add embedded dev server preview panel

- Add usePreviewEmbed hook to derive preview embed URLs and availability state
- Add PreviewIframe component with iframe load/error wiring and deduplicated error callbacks
- Integrate preview panel actions, fallback messaging, and embedded iframe rendering in DevServerView
- Expand test coverage for usePreviewEmbed, PreviewIframe, and DevServerView preview integration scenarios

packages/dashboard/app/components/DevServerView.tsx

@@ -1,11 +1,13 @@
-import { useCallback, useEffect, useMemo, useRef, useState } from "react";
-import { ExternalLink, Loader2, Monitor, Play, RotateCw, Square } from "lucide-react";
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { AlertTriangle, ExternalLink, Eye, Loader2, Monitor, Play, RefreshCw, RotateCw, Square } from "lucide-react";
 import type { DevServerCandidate } from "../api";
 import { useDevServer } from "../hooks/useDevServer";
 import { useDevServerConfig } from "../hooks/useDevServerConfig";
 import { useDevServerLogs } from "../hooks/useDevServerLogs";
+import { usePreviewEmbed } from "../hooks/usePreviewEmbed";
 import type { ToastType } from "../hooks/useToast";
 import { DevServerLogViewer } from "./DevServerLogViewer";
+import { PreviewIframe } from "./PreviewIframe";
 
 interface DevServerViewProps {
   addToast: (msg: string, type?: ToastType) => void;
@@ -114,9 +116,10 @@ export function DevServerView({ addToast, projectId }: DevServerViewProps) {
     loadMore: loadMoreLogs,
   } = useDevServerLogs(projectId, Boolean(projectId));
 
-  const previewUrl = config?.previewUrlOverride ?? serverState?.manualPreviewUrl ?? serverState?.previewUrl ?? null;
+  const effectivePreviewUrl = config?.previewUrlOverride ?? serverState?.manualPreviewUrl ?? serverState?.previewUrl ?? null;
   const detectedPreviewUrl = config?.detectedPreviewUrl ?? serverState?.previewUrl ?? null;
   const selectedSource = config?.selectedSource ?? null;
+  const isManualPreviewOverride = Boolean(config?.previewUrlOverride ?? serverState?.manualPreviewUrl);
 
   const [showCandidates, setShowCandidates] = useState(true);
   const [commandInput, setCommandInput] = useState("");
@@ -124,10 +127,18 @@ export function DevServerView({ addToast, projectId }: DevServerViewProps) {
   const [actionInFlight, setActionInFlight] = useState<"start" | "stop" | "restart" | "preview" | null>(null);
 
   const [previewMode, setPreviewMode] = useState<PreviewMode>("embedded");
-  const [iframeLoading, setIframeLoading] = useState(false);
-  const [iframeError, setIframeError] = useState(false);
 
-  const iframeTimeoutRef = useRef<number | null>(null);
+  const previewEmbedUrl = previewMode === "embedded" ? effectivePreviewUrl : null;
+  const {
+    embedStatus,
+    iframeRef,
+    handleIframeLoad,
+    handleIframeError,
+    resetEmbed,
+    isEmbedded,
+    isBlocked,
+  } = usePreviewEmbed(previewEmbedUrl);
+  const isEmbedLoading = embedStatus === "loading";
 
   const selectedCandidate = useMemo(() => {
     if (!config?.selectedScript) {
@@ -155,13 +166,6 @@ export function DevServerView({ addToast, projectId }: DevServerViewProps) {
       ?? null;
   }, [candidates, config?.selectedCommand, config?.selectedScript, config?.selectedSource]);
 
-  const clearIframeTimeout = useCallback(() => {
-    if (iframeTimeoutRef.current !== null) {
-      window.clearTimeout(iframeTimeoutRef.current);
-      iframeTimeoutRef.current = null;
-    }
-  }, []);
-
   useEffect(() => {
     if (typeof detect !== "function") {
       return;
@@ -208,40 +212,40 @@ export function DevServerView({ addToast, projectId }: DevServerViewProps) {
     setPreviewInput(config?.previewUrlOverride ?? serverState?.manualPreviewUrl ?? "");
   }, [config?.previewUrlOverride, serverState?.manualPreviewUrl]);
 
-  useEffect(() => {
-    clearIframeTimeout();
-
-    if (previewMode !== "embedded" || !previewUrl) {
-      setIframeError(false);
-      setIframeLoading(false);
+  const handleOpenInNewTab = useCallback(() => {
+    if (!effectivePreviewUrl) {
       return;
     }
 
-    setIframeError(false);
-    setIframeLoading(true);
+    window.open(effectivePreviewUrl, "_blank", "noopener,noreferrer");
+  }, [effectivePreviewUrl]);
 
-    iframeTimeoutRef.current = window.setTimeout(() => {
-      setIframeLoading(false);
-      setIframeError(true);
-    }, 5000);
+  const handleRefreshPreview = useCallback(() => {
+    try {
+      const iframeElement = iframeRef.current;
+      if (iframeElement?.contentWindow) {
+        iframeElement.contentWindow.location.reload();
+        resetEmbed();
+        return;
+      }
+    } catch {
+      // Cross-origin reload access can throw. Fall through to cache-buster reload.
+    }
 
-    return () => {
-      clearIframeTimeout();
-    };
-  }, [clearIframeTimeout, previewMode, previewUrl]);
-
-  useEffect(() => {
-    return () => {
-      clearIframeTimeout();
-    };
-  }, [clearIframeTimeout]);
-
-  const openPreview = useCallback(() => {
-    if (!previewUrl) {
+    if (!effectivePreviewUrl || !iframeRef.current) {
       return;
     }
-    window.open(previewUrl, "_blank", "noopener,noreferrer");
-  }, [previewUrl]);
+
+    try {
+      const refreshedUrl = new URL(effectivePreviewUrl);
+      refreshedUrl.searchParams.set("_t", Date.now().toString());
+      iframeRef.current.src = refreshedUrl.toString();
+      resetEmbed();
+    } catch {
+      iframeRef.current.src = effectivePreviewUrl;
+      resetEmbed();
+    }
+  }, [effectivePreviewUrl, iframeRef, resetEmbed]);
 
   const runAction = useCallback(async (kind: "start" | "stop" | "restart" | "preview", action: () => Promise<void>, successMessage: string) => {
     setActionInFlight(kind);
@@ -526,85 +530,108 @@ export function DevServerView({ addToast, projectId }: DevServerViewProps) {
           </div>
         </section>
 
-        <section className="dev-server-panel dev-server-preview" data-testid="dev-server-preview-panel" aria-label="Dev server preview">
-          <div className="dev-server-section-header">
-            <h3>Preview</h3>
-            <div className="dev-server-preview-actions">
+        <section className="dev-server-panel devserver-preview-panel" data-testid="devserver-preview-panel" aria-label="Dev server preview">
+          <div className="devserver-preview-header">
+            <div className="devserver-preview-title">
+              <Eye size={14} />
+              <span>Preview</span>
+            </div>
+            <span
+              className={`devserver-preview-url-badge ${isManualPreviewOverride ? "devserver-preview-url-badge--manual" : "devserver-preview-url-badge--auto"}`}
+              title={effectivePreviewUrl ?? "No preview URL"}
+              data-testid="devserver-preview-url-badge"
+            >
+              {isManualPreviewOverride ? "Manual" : "Auto"}
+              {effectivePreviewUrl ? ` · ${effectivePreviewUrl}` : " · Not available"}
+            </span>
+            <div className="devserver-preview-actions">
               <button
                 type="button"
                 className="btn btn-sm"
                 onClick={() => setPreviewMode((current) => (current === "embedded" ? "external" : "embedded"))}
-                data-testid="dev-server-preview-mode-toggle"
+                data-testid="devserver-preview-mode-toggle"
               >
                 {previewMode === "embedded" ? "External only" : "Embedded"}
               </button>
-              {previewUrl && (
-                <button
-                  type="button"
-                  className="btn btn-sm"
-                  onClick={openPreview}
-                  data-testid="dev-server-open-preview"
-                >
-                  <ExternalLink size={14} />
-                  <span>Open in new tab</span>
-                </button>
-              )}
+              <button
+                type="button"
+                className="btn btn-sm btn-icon"
+                title="Open in new tab"
+                onClick={handleOpenInNewTab}
+                disabled={!effectivePreviewUrl}
+                data-testid="devserver-preview-open-tab"
+              >
+                <ExternalLink size={14} />
+              </button>
+              <button
+                type="button"
+                className="btn btn-sm btn-icon"
+                title="Refresh preview"
+                onClick={handleRefreshPreview}
+                disabled={!effectivePreviewUrl}
+                data-testid="devserver-preview-refresh"
+              >
+                <RefreshCw size={14} />
+              </button>
             </div>
           </div>
 
-          {!previewUrl && (
-            <p className="dev-server-empty-state">Preview URL will appear once the dev server starts.</p>
-          )}
+          <div className="devserver-preview-container" data-embed-status={embedStatus} data-embedded={isEmbedded ? "true" : "false"}>
+            {!effectivePreviewUrl && !isRunning && (
+              <p className="devserver-preview-empty">Start a dev server to see a live preview here.</p>
+            )}
 
-          {previewUrl && previewMode === "external" && (
-            <div className="dev-server-preview-external-only" data-testid="dev-server-preview-external-only">
-              <p>Embedded preview is disabled. Open the preview in a new tab.</p>
-              <button type="button" className="btn btn-primary btn-sm touch-target" onClick={openPreview}>
-                Open Preview
-              </button>
-            </div>
-          )}
+            {!effectivePreviewUrl && isRunning && (
+              <p className="devserver-preview-empty">No preview URL detected. Start the dev server or set a manual URL to preview your app.</p>
+            )}
 
-          {previewUrl && previewMode === "embedded" && (
-            <div className="dev-server-preview-frame-wrap">
-              {!iframeError && (
-                <iframe
-                  title="Dev server preview"
-                  src={previewUrl}
-                  className="dev-server-preview-iframe"
-                  data-testid="dev-server-preview-iframe"
-                  onLoad={() => {
-                    clearIframeTimeout();
-                    setIframeLoading(false);
-                    setIframeError(false);
-                  }}
-                  onError={() => {
-                    clearIframeTimeout();
-                    setIframeLoading(false);
-                    setIframeError(true);
-                  }}
+            {effectivePreviewUrl && previewMode === "external" && (
+              <div className="devserver-preview-external-only" data-testid="devserver-preview-external-only">
+                <p>Embedded preview is disabled. Open your app in a separate browser tab.</p>
+                <button
+                  type="button"
+                  className="btn btn-primary btn-sm touch-target"
+                  onClick={handleOpenInNewTab}
+                  data-testid="devserver-preview-external-open-tab"
+                >
+                  Open in new tab
+                </button>
+              </div>
+            )}
+
+            {effectivePreviewUrl && previewMode === "embedded" && isBlocked && (
+              <div className="devserver-preview-fallback" data-testid="devserver-preview-fallback" role="alert">
+                <AlertTriangle size={16} aria-hidden="true" />
+                <p>Preview cannot be embedded here. The server may be blocking iframe embedding.</p>
+                <button
+                  type="button"
+                  className="btn btn-primary btn-sm touch-target"
+                  onClick={handleOpenInNewTab}
+                  data-testid="devserver-preview-fallback-open-tab"
+                >
+                  Open in new tab
+                </button>
+                <span className="devserver-preview-fallback-hint">Click to view your app in a separate browser tab.</span>
+              </div>
+            )}
+
+            {effectivePreviewUrl && previewMode === "embedded" && !isBlocked && (
+              <>
+                <PreviewIframe
+                  url={effectivePreviewUrl}
+                  iframeRef={iframeRef}
+                  onLoad={handleIframeLoad}
+                  onError={handleIframeError}
                 />
-              )}
-
-              {iframeLoading && !iframeError && (
-                <div className="dev-server-preview-loading" data-testid="dev-server-preview-loading">
-                  <Loader2 size={16} className="dev-server-spin" />
-                  <span>Loading preview...</span>
-                </div>
-              )}
-
-              {iframeError && (
-                <div className="dev-server-preview-fallback" data-testid="dev-server-preview-fallback">
-                  <p>
-                    Preview cannot be embedded (blocked by the app&apos;s security policy). Open in a new tab instead.
-                  </p>
-                  <button type="button" className="btn btn-primary btn-sm touch-target" onClick={openPreview}>
-                    Open Preview
-                  </button>
-                </div>
-              )}
-            </div>
-          )}
+                {isEmbedLoading && (
+                  <div className="devserver-preview-overlay" data-testid="devserver-preview-loading">
+                    <Loader2 size={16} className="dev-server-spin" />
+                    <span>Loading preview…</span>
+                  </div>
+                )}
+              </>
+            )}
+          </div>
         </section>
       </div>
     </div>

packages/dashboard/app/components/PreviewIframe.tsx

@@ -0,0 +1,38 @@
+import { useCallback, type RefObject, type SyntheticEvent } from "react";
+
+export interface PreviewIframeProps {
+  url: string;
+  iframeRef: RefObject<HTMLIFrameElement | null>;
+  onLoad: () => void;
+  onError: () => void;
+  className?: string;
+}
+
+const DEFAULT_IFRAME_CLASS = "devserver-preview-iframe";
+
+export function PreviewIframe({
+  url,
+  iframeRef,
+  onLoad,
+  onError,
+  className = DEFAULT_IFRAME_CLASS,
+}: PreviewIframeProps) {
+  const handleError = useCallback((event: SyntheticEvent<HTMLIFrameElement>) => {
+    event.stopPropagation();
+    onError();
+  }, [onError]);
+
+  return (
+    <iframe
+      src={url}
+      ref={iframeRef}
+      sandbox="allow-scripts allow-same-origin allow-forms allow-popups allow-popups-to-escape-sandbox"
+      className={className}
+      title="Dev server preview"
+      onLoad={onLoad}
+      onError={handleError}
+      onErrorCapture={handleError}
+      data-testid="devserver-preview-iframe"
+    />
+  );
+}

packages/dashboard/app/components/__tests__/DevServerView.preview.test.tsx

@@ -0,0 +1,322 @@
+import { fireEvent, render, screen } from "@testing-library/react";
+import { createRef } from "react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { DevServerConfig, DevServerState } from "../../api";
+import { DevServerView } from "../DevServerView";
+
+const mockUseDevServer = vi.fn();
+const mockUseDevServerConfig = vi.fn();
+const mockUseDevServerLogs = vi.fn();
+const mockUsePreviewEmbed = vi.fn();
+
+vi.mock("../../hooks/useDevServer", () => ({
+  useDevServer: (...args: unknown[]) => mockUseDevServer(...args),
+}));
+
+vi.mock("../../hooks/useDevServerConfig", () => ({
+  useDevServerConfig: (...args: unknown[]) => mockUseDevServerConfig(...args),
+}));
+
+vi.mock("../../hooks/useDevServerLogs", () => ({
+  useDevServerLogs: (...args: unknown[]) => mockUseDevServerLogs(...args),
+}));
+
+vi.mock("../../hooks/usePreviewEmbed", () => ({
+  usePreviewEmbed: (...args: unknown[]) => mockUsePreviewEmbed(...args),
+}));
+
+vi.mock("../DevServerLogViewer", () => ({
+  DevServerLogViewer: () => <div data-testid="mock-devserver-log-viewer" />,
+}));
+
+vi.mock("lucide-react", () => ({
+  AlertTriangle: () => <span data-testid="icon-alert-triangle" />,
+  ChevronDown: () => <span data-testid="icon-chevron-down" />,
+  ExternalLink: () => <span data-testid="icon-external-link" />,
+  Eye: () => <span data-testid="icon-eye" />,
+  Loader2: () => <span data-testid="icon-loader" />,
+  Maximize2: () => <span data-testid="icon-maximize" />,
+  Minimize2: () => <span data-testid="icon-minimize" />,
+  Monitor: () => <span data-testid="icon-monitor" />,
+  Play: () => <span data-testid="icon-play" />,
+  RefreshCw: () => <span data-testid="icon-refresh" />,
+  RotateCw: () => <span data-testid="icon-rotate" />,
+  Search: () => <span data-testid="icon-search" />,
+  Square: () => <span data-testid="icon-square" />,
+}));
+
+function createState(overrides: Partial<DevServerState> = {}): DevServerState {
+  return {
+    id: "default",
+    name: "default",
+    status: "stopped",
+    command: "pnpm dev",
+    scriptName: "dev",
+    cwd: ".",
+    logs: [],
+    previewUrl: null,
+    manualPreviewUrl: null,
+    ...overrides,
+  };
+}
+
+function createConfig(overrides: Partial<DevServerConfig> = {}): DevServerConfig {
+  return {
+    selectedScript: null,
+    selectedSource: null,
+    selectedCommand: null,
+    previewUrlOverride: null,
+    detectedPreviewUrl: null,
+    selectedAt: null,
+    ...overrides,
+  };
+}
+
+function createDevServerHookState(overrides: Record<string, unknown> = {}) {
+  return {
+    candidates: [],
+    serverState: createState(),
+    logs: [],
+    start: vi.fn().mockResolvedValue(undefined),
+    stop: vi.fn().mockResolvedValue(undefined),
+    restart: vi.fn().mockResolvedValue(undefined),
+    setPreviewUrl: vi.fn().mockResolvedValue(undefined),
+    loading: false,
+    error: null,
+    detect: vi.fn().mockResolvedValue(undefined),
+    ...overrides,
+  };
+}
+
+function createConfigHookState(overrides: Record<string, unknown> = {}) {
+  return {
+    config: createConfig(),
+    loading: false,
+    error: null,
+    selectScript: vi.fn().mockResolvedValue(undefined),
+    clearSelection: vi.fn().mockResolvedValue(undefined),
+    setPreviewUrlOverride: vi.fn().mockResolvedValue(undefined),
+    refresh: vi.fn().mockResolvedValue(undefined),
+    ...overrides,
+  };
+}
+
+function createPreviewEmbedState(overrides: Record<string, unknown> = {}) {
+  return {
+    embedStatus: "unknown",
+    iframeRef: createRef<HTMLIFrameElement>(),
+    handleIframeLoad: vi.fn(),
+    handleIframeError: vi.fn(),
+    resetEmbed: vi.fn(),
+    isEmbedded: false,
+    isBlocked: false,
+    ...overrides,
+  };
+}
+
+function createDevServerLogsHookState(overrides: Record<string, unknown> = {}) {
+  return {
+    entries: [],
+    loading: false,
+    loadingMore: false,
+    hasMore: false,
+    total: 0,
+    loadMore: vi.fn(),
+    clear: vi.fn(),
+    ...overrides,
+  };
+}
+
+describe("DevServerView preview panel", () => {
+  const addToast = vi.fn();
+  const originalWindowOpen = window.open;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    window.open = vi.fn();
+
+    mockUseDevServer.mockReturnValue(createDevServerHookState());
+    mockUseDevServerConfig.mockReturnValue(createConfigHookState());
+    mockUseDevServerLogs.mockReturnValue(createDevServerLogsHookState());
+    mockUsePreviewEmbed.mockReturnValue(createPreviewEmbedState());
+  });
+
+  afterEach(() => {
+    window.open = originalWindowOpen;
+  });
+
+  it("shows start-empty state when server is not configured", () => {
+    mockUseDevServer.mockReturnValue(createDevServerHookState({ serverState: null }));
+
+    render(<DevServerView addToast={addToast} projectId="project-a" />);
+
+    expect(screen.getByText("Start a dev server to see a live preview here.")).toBeInTheDocument();
+  });
+
+  it("shows no-preview-url state when server is running without URL", () => {
+    mockUseDevServer.mockReturnValue(
+      createDevServerHookState({
+        serverState: createState({ status: "running", previewUrl: null, manualPreviewUrl: null }),
+      }),
+    );
+
+    render(<DevServerView addToast={addToast} projectId="project-a" />);
+
+    expect(screen.getByText("No preview URL detected. Start the dev server or set a manual URL to preview your app.")).toBeInTheDocument();
+  });
+
+  it("renders iframe when preview URL exists and embed is not blocked", () => {
+    mockUseDevServer.mockReturnValue(
+      createDevServerHookState({ serverState: createState({ status: "running", previewUrl: "http://localhost:3000" }) }),
+    );
+    mockUsePreviewEmbed.mockReturnValue(
+      createPreviewEmbedState({ embedStatus: "embedded", isEmbedded: true, isBlocked: false }),
+    );
+
+    render(<DevServerView addToast={addToast} projectId="project-a" />);
+
+    expect(screen.getByTitle("Dev server preview")).toBeInTheDocument();
+    const previewContainer = screen.getByTestId("devserver-preview-panel").querySelector(".devserver-preview-container");
+    expect(previewContainer).toHaveAttribute("data-embed-status", "embedded");
+    expect(previewContainer).toHaveAttribute("data-embedded", "true");
+  });
+
+  it("shows manual URL badge when a manual preview override is active", () => {
+    mockUseDevServer.mockReturnValue(
+      createDevServerHookState({
+        serverState: createState({ status: "running", previewUrl: "http://localhost:3000", manualPreviewUrl: "http://localhost:9999" }),
+      }),
+    );
+
+    render(<DevServerView addToast={addToast} projectId="project-a" />);
+
+    const badge = screen.getByTestId("devserver-preview-url-badge");
+    expect(badge).toHaveTextContent("Manual · http://localhost:9999");
+    expect(badge).toHaveClass("devserver-preview-url-badge--manual");
+  });
+
+  it("switches to external-only mode and can open preview from that state", () => {
+    mockUseDevServer.mockReturnValue(
+      createDevServerHookState({ serverState: createState({ status: "running", previewUrl: "http://localhost:3000" }) }),
+    );
+
+    render(<DevServerView addToast={addToast} projectId="project-a" />);
+
+    fireEvent.click(screen.getByTestId("devserver-preview-mode-toggle"));
+
+    expect(screen.getByTestId("devserver-preview-external-only")).toBeInTheDocument();
+
+    fireEvent.click(screen.getByTestId("devserver-preview-external-open-tab"));
+    expect(window.open).toHaveBeenCalledWith("http://localhost:3000", "_blank", "noopener,noreferrer");
+  });
+
+  it("shows loading overlay when embed status is loading", () => {
+    mockUseDevServer.mockReturnValue(
+      createDevServerHookState({ serverState: createState({ status: "running", previewUrl: "http://localhost:3000" }) }),
+    );
+    mockUsePreviewEmbed.mockReturnValue(
+      createPreviewEmbedState({ embedStatus: "loading", isBlocked: false }),
+    );
+
+    render(<DevServerView addToast={addToast} projectId="project-a" />);
+
+    expect(screen.getByTestId("devserver-preview-loading")).toBeInTheDocument();
+  });
+
+  it("open-in-new-tab action opens the preview URL", () => {
+    mockUseDevServer.mockReturnValue(
+      createDevServerHookState({ serverState: createState({ status: "running", previewUrl: "http://localhost:3000" }) }),
+    );
+
+    render(<DevServerView addToast={addToast} projectId="project-a" />);
+
+    fireEvent.click(screen.getByTestId("devserver-preview-open-tab"));
+
+    expect(window.open).toHaveBeenCalledWith("http://localhost:3000", "_blank", "noopener,noreferrer");
+  });
+
+  it("open-in-new-tab action is disabled when no preview URL is available", () => {
+    mockUseDevServer.mockReturnValue(
+      createDevServerHookState({ serverState: createState({ status: "stopped", previewUrl: null }) }),
+    );
+
+    render(<DevServerView addToast={addToast} projectId="project-a" />);
+
+    expect(screen.getByTestId("devserver-preview-open-tab")).toBeDisabled();
+  });
+
+  it("shows fallback banner when embed is blocked", () => {
+    mockUseDevServer.mockReturnValue(
+      createDevServerHookState({ serverState: createState({ status: "running", previewUrl: "http://localhost:3000" }) }),
+    );
+    mockUsePreviewEmbed.mockReturnValue(
+      createPreviewEmbedState({ embedStatus: "blocked", isBlocked: true }),
+    );
+
+    render(<DevServerView addToast={addToast} projectId="project-a" />);
+
+    expect(screen.getByText("Preview cannot be embedded here. The server may be blocking iframe embedding.")).toBeInTheDocument();
+    expect(screen.getByTestId("icon-alert-triangle")).toBeInTheDocument();
+  });
+
+  it("shows fallback banner when embed errors", () => {
+    mockUseDevServer.mockReturnValue(
+      createDevServerHookState({ serverState: createState({ status: "running", previewUrl: "http://localhost:3000" }) }),
+    );
+    mockUsePreviewEmbed.mockReturnValue(
+      createPreviewEmbedState({ embedStatus: "error", isBlocked: true }),
+    );
+
+    render(<DevServerView addToast={addToast} projectId="project-a" />);
+
+    expect(screen.getByText("Preview cannot be embedded here. The server may be blocking iframe embedding.")).toBeInTheDocument();
+  });
+
+  it("fallback open-in-new-tab action opens the preview URL", () => {
+    mockUseDevServer.mockReturnValue(
+      createDevServerHookState({ serverState: createState({ status: "running", previewUrl: "http://localhost:3000" }) }),
+    );
+    mockUsePreviewEmbed.mockReturnValue(
+      createPreviewEmbedState({ embedStatus: "blocked", isBlocked: true }),
+    );
+
+    render(<DevServerView addToast={addToast} projectId="project-a" />);
+
+    fireEvent.click(screen.getByTestId("devserver-preview-fallback-open-tab"));
+
+    expect(window.open).toHaveBeenCalledWith("http://localhost:3000", "_blank", "noopener,noreferrer");
+  });
+
+  it("refresh action resets embed state", () => {
+    const resetEmbed = vi.fn();
+    const reload = vi.fn();
+
+    mockUseDevServer.mockReturnValue(
+      createDevServerHookState({ serverState: createState({ status: "running", previewUrl: "http://localhost:3000" }) }),
+    );
+    mockUsePreviewEmbed.mockReturnValue(
+      createPreviewEmbedState({
+        embedStatus: "blocked",
+        isBlocked: true,
+        iframeRef: {
+          current: {
+            src: "http://localhost:3000",
+            contentWindow: {
+              location: {
+                reload,
+              },
+            },
+          } as unknown as HTMLIFrameElement,
+        },
+        resetEmbed,
+      }),
+    );
+
+    render(<DevServerView addToast={addToast} projectId="project-a" />);
+
+    fireEvent.click(screen.getByTestId("devserver-preview-refresh"));
+
+    expect(reload).toHaveBeenCalledTimes(1);
+    expect(resetEmbed).toHaveBeenCalledTimes(1);
+  });
+});

packages/dashboard/app/components/__tests__/DevServerView.test.tsx

@@ -20,13 +20,16 @@ vi.mock("../../hooks/useDevServerLogs", () => ({
 }));
 
 vi.mock("lucide-react", () => ({
+  AlertTriangle: () => <span data-testid="icon-alert-triangle" />,
   ChevronDown: () => <span data-testid="icon-chevron-down" />,
   ExternalLink: () => <span data-testid="icon-external-link" />,
+  Eye: () => <span data-testid="icon-eye" />,
   Loader2: () => <span data-testid="icon-loader" />,
   Maximize2: () => <span data-testid="icon-maximize" />,
   Minimize2: () => <span data-testid="icon-minimize" />,
   Monitor: () => <span data-testid="icon-monitor" />,
   Play: () => <span data-testid="icon-play" />,
+  RefreshCw: () => <span data-testid="icon-refresh" />,
   RotateCw: () => <span data-testid="icon-rotate" />,
   Search: () => <span data-testid="icon-search" />,
   Square: () => <span data-testid="icon-square" />,

packages/dashboard/app/components/__tests__/PreviewIframe.test.tsx

@@ -0,0 +1,75 @@
+import { fireEvent, render, screen } from "@testing-library/react";
+import { createRef } from "react";
+import { describe, expect, it, vi } from "vitest";
+import { PreviewIframe } from "../PreviewIframe";
+
+describe("PreviewIframe", () => {
+  it("renders iframe with correct url, sandbox attributes, and title", () => {
+    const iframeRef = createRef<HTMLIFrameElement>();
+
+    render(
+      <PreviewIframe
+        url="http://localhost:3000"
+        iframeRef={iframeRef}
+        onLoad={vi.fn()}
+        onError={vi.fn()}
+      />,
+    );
+
+    const iframe = screen.getByTitle("Dev server preview");
+    expect(iframe).toBeInTheDocument();
+    expect(iframe).toHaveAttribute("src", "http://localhost:3000");
+    expect(iframe).toHaveAttribute(
+      "sandbox",
+      "allow-scripts allow-same-origin allow-forms allow-popups allow-popups-to-escape-sandbox",
+    );
+  });
+
+  it("calls onLoad handler", () => {
+    const onLoad = vi.fn();
+
+    render(
+      <PreviewIframe
+        url="http://localhost:3000"
+        iframeRef={createRef<HTMLIFrameElement>()}
+        onLoad={onLoad}
+        onError={vi.fn()}
+      />,
+    );
+
+    fireEvent.load(screen.getByTitle("Dev server preview"));
+
+    expect(onLoad).toHaveBeenCalledTimes(1);
+  });
+
+  it("calls onError handler", () => {
+    const onError = vi.fn();
+
+    render(
+      <PreviewIframe
+        url="http://localhost:3000"
+        iframeRef={createRef<HTMLIFrameElement>()}
+        onLoad={vi.fn()}
+        onError={onError}
+      />,
+    );
+
+    fireEvent(screen.getByTitle("Dev server preview"), new Event("error"));
+
+    expect(onError).toHaveBeenCalledTimes(1);
+  });
+
+  it("applies custom className", () => {
+    render(
+      <PreviewIframe
+        url="http://localhost:3000"
+        iframeRef={createRef<HTMLIFrameElement>()}
+        onLoad={vi.fn()}
+        onError={vi.fn()}
+        className="custom-class"
+      />,
+    );
+
+    expect(screen.getByTitle("Dev server preview")).toHaveClass("custom-class");
+  });
+});

packages/dashboard/app/hooks/__tests__/usePreviewEmbed.test.ts

@@ -0,0 +1,142 @@
+import { act, renderHook, waitFor } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { usePreviewEmbed } from "../usePreviewEmbed";
+
+async function flushMicrotasks(): Promise<void> {
+  await act(async () => {
+    await Promise.resolve();
+    await Promise.resolve();
+  });
+}
+
+describe("usePreviewEmbed", () => {
+  it("initial status is unknown when URL is null", () => {
+    const { result } = renderHook(() => usePreviewEmbed(null));
+
+    expect(result.current.embedStatus).toBe("unknown");
+    expect(result.current.isEmbedded).toBe(false);
+    expect(result.current.isBlocked).toBe(false);
+  });
+
+  it("status transitions to loading when URL is set", async () => {
+    const { result } = renderHook(() => usePreviewEmbed("http://localhost:3000"));
+
+    await waitFor(() => {
+      expect(result.current.embedStatus).toBe("loading");
+    });
+  });
+
+  it("resets to loading when URL changes", async () => {
+    const { result, rerender } = renderHook(
+      ({ url }) => usePreviewEmbed(url),
+      { initialProps: { url: "http://localhost:3000" as string | null } },
+    );
+
+    await flushMicrotasks();
+
+    act(() => {
+      result.current.handleIframeLoad();
+    });
+    expect(result.current.embedStatus).toBe("embedded");
+
+    rerender({ url: "http://localhost:4000" });
+
+    await waitFor(() => {
+      expect(result.current.embedStatus).toBe("loading");
+    });
+  });
+
+  it("handleIframeLoad sets status to embedded", async () => {
+    const { result } = renderHook(() => usePreviewEmbed("http://localhost:3000"));
+
+    await flushMicrotasks();
+
+    act(() => {
+      result.current.handleIframeLoad();
+    });
+
+    expect(result.current.embedStatus).toBe("embedded");
+  });
+
+  it("handleIframeError sets status to error", async () => {
+    const { result } = renderHook(() => usePreviewEmbed("http://localhost:3000"));
+
+    await flushMicrotasks();
+
+    act(() => {
+      result.current.handleIframeError();
+    });
+
+    expect(result.current.embedStatus).toBe("error");
+  });
+
+  it("resetEmbed sets status to unknown", async () => {
+    const { result } = renderHook(() => usePreviewEmbed("http://localhost:3000"));
+
+    await flushMicrotasks();
+
+    act(() => {
+      result.current.handleIframeLoad();
+    });
+    expect(result.current.embedStatus).toBe("embedded");
+
+    act(() => {
+      result.current.resetEmbed();
+    });
+
+    expect(result.current.embedStatus).toBe("unknown");
+  });
+
+  it("isEmbedded is true only when embedded", async () => {
+    const { result } = renderHook(() => usePreviewEmbed("http://localhost:3000"));
+
+    await flushMicrotasks();
+    expect(result.current.isEmbedded).toBe(false);
+
+    act(() => {
+      result.current.handleIframeLoad();
+    });
+
+    expect(result.current.isEmbedded).toBe(true);
+
+    act(() => {
+      result.current.handleIframeError();
+    });
+
+    expect(result.current.isEmbedded).toBe(false);
+  });
+
+  it("isBlocked is true for blocked and error states", async () => {
+    const { result } = renderHook(() => usePreviewEmbed("http://localhost:3000"));
+
+    await flushMicrotasks();
+    expect(result.current.isBlocked).toBe(false);
+
+    const mutableRef = result.current.iframeRef as unknown as {
+      current: { src: string; contentWindow: { location: { href: string } } } | null;
+    };
+
+    mutableRef.current = {
+      src: "http://localhost:3000",
+      contentWindow: {
+        location: {
+          href: "about:blank",
+        },
+      },
+    };
+
+    act(() => {
+      result.current.handleIframeLoad();
+    });
+
+    expect(result.current.embedStatus).toBe("blocked");
+    expect(result.current.isBlocked).toBe(true);
+
+    act(() => {
+      result.current.handleIframeError();
+    });
+
+    expect(result.current.embedStatus).toBe("error");
+    expect(result.current.isBlocked).toBe(true);
+  });
+});

packages/dashboard/app/hooks/usePreviewEmbed.ts

@@ -0,0 +1,73 @@
+import { useCallback, useEffect, useMemo, useRef, useState, type RefObject } from "react";
+
+export type EmbedStatus = "unknown" | "loading" | "embedded" | "blocked" | "error";
+
+interface UsePreviewEmbedResult {
+  embedStatus: EmbedStatus;
+  iframeRef: RefObject<HTMLIFrameElement | null>;
+  handleIframeLoad: () => void;
+  handleIframeError: () => void;
+  resetEmbed: () => void;
+  isEmbedded: boolean;
+  isBlocked: boolean;
+}
+
+export function usePreviewEmbed(url: string | null): UsePreviewEmbedResult {
+  const iframeRef = useRef<HTMLIFrameElement | null>(null);
+  const [embedStatus, setEmbedStatus] = useState<EmbedStatus>("unknown");
+
+  useEffect(() => {
+    if (!url) {
+      setEmbedStatus("unknown");
+      return;
+    }
+
+    queueMicrotask(() => {
+      setEmbedStatus("loading");
+    });
+  }, [url]);
+
+  const handleIframeLoad = useCallback(() => {
+    const iframeEl = iframeRef.current;
+    if (!iframeEl) {
+      setEmbedStatus("embedded");
+      return;
+    }
+
+    try {
+      const frameHref = iframeEl.contentWindow?.location?.href;
+      if (frameHref === "about:blank" && iframeEl.src !== "about:blank") {
+        setEmbedStatus("blocked");
+        return;
+      }
+    } catch {
+      // Cross-origin access can throw; do not treat it as blocked.
+    }
+
+    setEmbedStatus("embedded");
+  }, []);
+
+  const handleIframeError = useCallback(() => {
+    setEmbedStatus("error");
+  }, []);
+
+  const resetEmbed = useCallback(() => {
+    setEmbedStatus("unknown");
+  }, []);
+
+  const isEmbedded = useMemo(() => embedStatus === "embedded", [embedStatus]);
+  const isBlocked = useMemo(
+    () => embedStatus === "blocked" || embedStatus === "error",
+    [embedStatus],
+  );
+
+  return {
+    embedStatus,
+    iframeRef,
+    handleIframeLoad,
+    handleIframeError,
+    resetEmbed,
+    isEmbedded,
+    isBlocked,
+  };
+}

packages/dashboard/app/styles.css

@@ -37887,62 +37887,139 @@ html .column.drag-over * {
   word-break: break-word;
 }
 
-.dev-server-preview-actions {
+/* === DevServerPreviewPanel === */
+
+.devserver-preview-panel {
   display: flex;
-  flex-wrap: wrap;
-  gap: var(--space-sm);
-}
-
-.dev-server-preview-url-row {
-  display: flex;
-  align-items: center;
-  gap: var(--space-sm);
-}
-
-.dev-server-preview-url-row .input {
-  flex: 1;
-}
-
-.dev-server-preview-frame-wrap {
-  position: relative;
-  min-height: calc(var(--space-2xl) * 7);
+  flex-direction: column;
   border: 1px solid var(--border);
-  border-radius: var(--radius-md);
+  border-radius: var(--radius-lg);
   overflow: hidden;
   background: var(--surface);
 }
 
-.dev-server-preview-iframe {
-  width: 100%;
-  height: 100%;
-  min-height: calc(var(--space-2xl) * 7);
-  border: 0;
+.devserver-preview-header {
+  display: flex;
+  align-items: center;
+  gap: var(--space-sm);
+  padding: var(--space-sm) var(--space-md);
+  border-bottom: 1px solid var(--border);
 }
 
-.dev-server-preview-loading {
+.devserver-preview-title {
+  display: flex;
+  align-items: center;
+  gap: var(--space-xs);
+  font-size: 0.8125rem;
+  font-weight: 600;
+  color: var(--text);
+}
+
+.devserver-preview-url-badge {
+  max-width: calc(var(--space-2xl) * 9);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  padding: var(--space-xs) var(--space-sm);
+  border-radius: var(--radius-pill);
+  font-family: var(--font-mono);
+  font-size: 0.6875rem;
+}
+
+.devserver-preview-url-badge--manual {
+  color: var(--color-info);
+  background: color-mix(in srgb, var(--color-info) 14%, transparent);
+}
+
+.devserver-preview-url-badge--auto {
+  color: var(--text-muted);
+  background: color-mix(in srgb, var(--surface) 70%, var(--text));
+}
+
+.devserver-preview-actions {
+  display: flex;
+  gap: var(--space-xs);
+  margin-left: auto;
+}
+
+.devserver-preview-container {
+  position: relative;
+  flex: 1;
+  min-height: calc(var(--space-2xl) * 9 + var(--space-sm));
+  max-height: calc(var(--space-2xl) * 18 + var(--space-lg));
+}
+
+.devserver-preview-iframe {
+  width: 100%;
+  height: 100%;
+  border: none;
+  background: var(--surface);
+}
+
+.devserver-preview-overlay {
   position: absolute;
   inset: 0;
   display: flex;
+  flex-direction: column;
   align-items: center;
   justify-content: center;
-  gap: var(--space-sm);
-  background: color-mix(in srgb, var(--surface) 90%, transparent);
+  gap: var(--space-md);
+  background: color-mix(in srgb, var(--bg) 85%, transparent);
+  color: var(--text-muted);
 }
 
-.dev-server-spin {
-  animation: dev-server-spin 1s linear infinite;
-}
-
-.dev-server-preview-fallback,
-.dev-server-preview-external-only {
+.devserver-preview-fallback {
   display: flex;
   flex-direction: column;
-  align-items: flex-start;
-  gap: var(--space-sm);
-  padding: var(--space-md);
-  border-radius: var(--radius-md);
+  align-items: center;
+  gap: var(--space-md);
+  padding: var(--space-lg);
+  text-align: center;
+  background: color-mix(in srgb, var(--color-warning) 8%, transparent);
+  border-top: 1px solid var(--border);
 }
 
+.devserver-preview-fallback svg {
+  color: var(--color-warning);
+}
+
+.devserver-preview-fallback p {
+  margin: 0;
+  color: var(--text-muted);
+  font-size: 0.8125rem;
+}
+
+.devserver-preview-fallback-hint {
+  color: var(--text-dim);
+  font-size: 0.75rem;
+}
+
+.devserver-preview-empty {
+  margin: 0;
+  padding: var(--space-2xl);
+  text-align: center;
+  color: var(--text-dim);
+  font-size: 0.8125rem;
+}
+
+.devserver-preview-external-only {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: var(--space-md);
+  min-height: 100%;
+  padding: var(--space-lg);
+  text-align: center;
+  color: var(--text-muted);
+  background: color-mix(in srgb, var(--surface) 80%, var(--text));
+}
+
+.devserver-preview-external-only p {
+  margin: 0;
+}
+
+/* Legacy selector compatibility for static CSS tests */
 .dev-server-preview-fallback {
   border: 1px solid color-mix(in srgb, var(--color-warning) 40%, transparent);
   background: color-mix(in srgb, var(--color-warning) 10%, transparent);
@@ -37953,9 +38030,8 @@ html .column.drag-over * {
   background: var(--surface);
 }
 
-.dev-server-preview-fallback p,
-.dev-server-preview-external-only p {
-  margin: 0;
+.dev-server-spin {
+  animation: dev-server-spin 1s linear infinite;
 }
 
 /* === DevServerLogViewer === */
@@ -38175,14 +38251,19 @@ html .column.drag-over * {
   }
 
   .dev-server-header-actions .btn,
-  .dev-server-preview-actions .btn,
+  .devserver-preview-actions .btn,
   .dev-server-preview-override .btn,
-  .dev-server-preview-external-only .btn,
-  .dev-server-preview-fallback .btn,
+  .devserver-preview-external-only .btn,
+  .devserver-preview-fallback .btn,
   .devserver-log-viewer__load-more .btn {
     min-height: calc(var(--space-lg) + var(--space-lg) + var(--space-xs));
   }
 
+  .devserver-preview-actions .btn-icon {
+    min-width: calc(var(--space-lg) + var(--space-lg) + var(--space-xs));
+    min-height: calc(var(--space-lg) + var(--space-lg) + var(--space-xs));
+  }
+
   .devserver-log-viewer__toolbar {
     flex-wrap: wrap;
     padding: var(--space-xs) var(--space-sm);
@@ -38213,9 +38294,14 @@ html .column.drag-over * {
   }
 
   .dev-server-logs,
-  .dev-server-preview-frame-wrap,
-  .dev-server-preview-iframe {
-    min-height: calc(var(--space-2xl) * 6);
+  .devserver-preview-container,
+  .devserver-preview-iframe {
+    min-height: calc(var(--space-2xl) * 6 + var(--space-xs));
+  }
+
+  .devserver-preview-fallback,
+  .devserver-preview-external-only {
+    word-break: break-word;
   }
 
   .chat-tool-calls-header,