From bd59c7244ec33da5a97f60e84aada51f1b0e9318 Mon Sep 17 00:00:00 2001
From: Shaun Andrews <shaun@automattic.com>
Date: Tue, 16 Jun 2026 13:04:35 -0400
Subject: [PATCH] Keep the site preview webview warm with a contained surface

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 apps/ui/src/components/site-preview/index.tsx | 84 +++++++++++--------
 .../components/site-preview/style.module.css  | 25 +++++-
 2 files changed, 71 insertions(+), 38 deletions(-)

diff --git a/apps/ui/src/components/site-preview/index.tsx b/apps/ui/src/components/site-preview/index.tsx
index 2452025214..17096f38f3 100644
--- a/apps/ui/src/components/site-preview/index.tsx
+++ b/apps/ui/src/components/site-preview/index.tsx
@@ -2,6 +2,7 @@ import { __ } from '@wordpress/i18n';
 import { chevronLeft, chevronRight, external, pencil } from '@wordpress/icons';
 import { ariaKeyShortcut, displayShortcut, isKeyboardEvent } from '@wordpress/keycodes';
 import { Button, IconButton, Tooltip } from '@wordpress/ui';
+import { clsx } from 'clsx';
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { useConnector } from '@/data/core';
 import { useIsSiteStarting, useStartSite } from '@/data/queries/use-sites';
@@ -297,6 +298,10 @@ export function SitePreview( {
 		return () => document.removeEventListener( 'keydown', handleKeyDown, { capture: true } );
 	}, [ canPreview, collapsed, sendBrowserCommand ] );
 
+	// Kept mounted while collapsed so the webview stays warm; `active` gates the
+	// surface's visibility and interactivity.
+	const active = ! collapsed;
+
 	return (
 		<aside ref={ rootRef } className={ styles.root } aria-label={ __( 'Site preview' ) }>
 			<div className={ styles.header }>
@@ -384,43 +389,48 @@ export function SitePreview( {
 			</div>
 			<div className={ styles.body }>
 				{ canPreview ? (
-					isElectron() ? (
-						<WebviewSurface
-							key={ site.id }
-							url={ previewUrl }
-							reloadNonce={ reloadNonce }
-							onAnnotationsDone={ onAnnotationsDone }
-							onInspectorState={ handleInspectorState }
-							inspectorCommand={ inspectorCommand }
-							browserCommand={ browserCommand }
-							onBrowserStateChange={ handleBrowserStateChange }
-							onBrowserCommand={ sendBrowserCommand }
-							onNavigate={ handlePreviewNavigation }
-						/>
-					) : (
-						// Non-Electron fallback: plain iframe, no inspector. Reloads
-						// by remounting; back/forward aren't reachable from the host.
-						<iframe
-							key={ `${ previewUrl }#${ reloadNonce }#${
-								browserCommand?.type === 'reload' ? browserCommand.id : 0
-							}` }
-							className={ styles.iframe }
-							src={ previewUrl }
-							title={ site.name }
-							onLoad={ ( event ) => {
-								handlePreviewNavigation( event.currentTarget.src );
-								setBrowserState( ( current ) => {
-									const next = {
-										...current,
-										loading: false,
-										progress: 0,
-										title: getIframeTitle( event.currentTarget ),
-									};
-									return areBrowserStatesEqual( current, next ) ? current : next;
-								} );
-							} }
-						/>
-					)
+					<div
+						className={ clsx( styles.previewSurface, active && styles.previewSurfaceActive ) }
+						aria-hidden={ ! active }
+					>
+						{ isElectron() ? (
+							<WebviewSurface
+								key={ site.id }
+								url={ previewUrl }
+								reloadNonce={ reloadNonce }
+								onAnnotationsDone={ onAnnotationsDone }
+								onInspectorState={ handleInspectorState }
+								inspectorCommand={ inspectorCommand }
+								browserCommand={ browserCommand }
+								onBrowserStateChange={ handleBrowserStateChange }
+								onBrowserCommand={ sendBrowserCommand }
+								onNavigate={ handlePreviewNavigation }
+							/>
+						) : (
+							// Non-Electron fallback: plain iframe, no inspector. Reloads
+							// by remounting; back/forward aren't reachable from the host.
+							<iframe
+								key={ `${ previewUrl }#${ reloadNonce }#${
+									browserCommand?.type === 'reload' ? browserCommand.id : 0
+								}` }
+								className={ styles.iframe }
+								src={ previewUrl }
+								title={ site.name }
+								onLoad={ ( event ) => {
+									handlePreviewNavigation( event.currentTarget.src );
+									setBrowserState( ( current ) => {
+										const next = {
+											...current,
+											loading: false,
+											progress: 0,
+											title: getIframeTitle( event.currentTarget ),
+										};
+										return areBrowserStatesEqual( current, next ) ? current : next;
+									} );
+								} }
+							/>
+						) }
+					</div>
 				) : (
 					<div className={ styles.empty }>
 						<p className={ styles.emptyText }>{ __( 'Start the site to see a live preview.' ) }</p>
diff --git a/apps/ui/src/components/site-preview/style.module.css b/apps/ui/src/components/site-preview/style.module.css
index 4963544876..5cd7fe7924 100644
--- a/apps/ui/src/components/site-preview/style.module.css
+++ b/apps/ui/src/components/site-preview/style.module.css
@@ -108,12 +108,31 @@
 .body {
 	flex: 1;
 	min-height: 0;
-	display: flex;
 	position: relative;
 	background-color: var(--wpds-color-bg-surface-neutral-strong, #fff);
 	overflow: hidden;
 }
 
+.previewSurface {
+	position: absolute;
+	inset: 0;
+	display: flex;
+	min-width: 0;
+	min-height: 0;
+	overflow: hidden;
+	contain: layout paint size;
+	visibility: hidden;
+	opacity: 0;
+	pointer-events: none;
+	background-color: var(--wpds-color-bg-surface-neutral-strong, #fff);
+}
+
+.previewSurfaceActive {
+	visibility: visible;
+	opacity: 1;
+	pointer-events: auto;
+}
+
 .spinnerOverlay {
 	position: absolute;
 	inset: 0;
@@ -145,6 +164,8 @@
 
 .iframe {
 	flex: 1;
+	min-width: 0;
+	min-height: 0;
 	width: 100%;
 	height: 100%;
 	border: 0;
@@ -158,6 +179,8 @@
 	gap: var(--wpds-dimension-padding-md);
 	align-items: center;
 	justify-content: center;
+	box-sizing: border-box;
+	height: 100%;
 	padding: var(--wpds-dimension-padding-xl);
 	color: var(--wpds-color-fg-content-neutral-weak);
 	font-size: var(--wpds-typography-font-size-sm);