Add autosaved site lifecycle APIs

Author: adamziel

packages/playground/website/playwright/e2e/sites-api.spec.ts

@@ -20,7 +20,7 @@ test('playgroundSites.list() returns the active site', async ({ website }) => {
 	const active = sites.find((s: any) => s.isActive);
 	expect(active).toBeTruthy();
 	expect(active.slug).toBeTruthy();
-	expect(active.storage).toBe('temporary');
+	expect(['opfs', 'local-fs', 'temporary']).toContain(active.storage);
 });
 
 test('playgroundSites.saveInBrowser() persists a temporary site', async ({
@@ -32,7 +32,7 @@ test('playgroundSites.saveInBrowser() persists a temporary site', async ({
 		`This test relies on OPFS which isn't available in Playwright's flavor of ${browserName}.`
 	);
 
-	await website.goto('./');
+	await website.goto('./?storage=temp');
 	await website.page.waitForFunction(() =>
 		Boolean((window as any).playgroundSites?.getClient())
 	);
@@ -60,7 +60,6 @@ test('playgroundSites.rename() renames a saved site', async ({
 
 	const newName = await website.page.evaluate(async () => {
 		const api = (window as any).playgroundSites;
-		await api.saveInBrowser();
 		const name = 'Renamed Via API';
 		await api.rename(name);
 		const sites = api.list();

packages/playground/website/src/lib/state/redux/boot-site-client.ts

@@ -17,7 +17,7 @@ import {
 	isBlueprintBundle,
 } from '@wp-playground/blueprints';
 import { logger } from '@php-wasm/logger';
-import { setupPostMessageRelay } from '@php-wasm/web';
+import { type SyncProgress, setupPostMessageRelay } from '@php-wasm/web';
 import { startPlaygroundWeb } from '@wp-playground/client';
 import type { PlaygroundClient } from '@wp-playground/remote';
 import { getRemoteUrl } from '../../config';
@@ -27,7 +27,11 @@ import {
 	setGitHubAuthRepoUrl,
 } from './slice-ui';
 import type { PlaygroundDispatch, PlaygroundReduxState } from './store';
-import { selectSiteBySlug } from './slice-sites';
+import {
+	isAutosavedSite,
+	selectSiteBySlug,
+	updateSiteMetadata,
+} from './slice-sites';
 // @ts-ignore
 import { corsProxyUrl } from 'virtual:cors-proxy-url';
 import { modalSlugs } from './slice-ui';
@@ -161,6 +165,21 @@ export function bootSiteClient(
 				? 'install-from-existing-files-if-needed'
 				: 'download-and-install';
 
+		const shouldSyncNewOpfsSiteInBackground =
+			site.metadata.storage === 'opfs' &&
+			!!mountDescriptor &&
+			!isWordPressInstalled;
+		const syncOperation = isAutosavedSite(site) ? 'autosave' : 'save';
+		const mounts =
+			mountDescriptor && !shouldSyncNewOpfsSiteInBackground
+				? [
+						{
+							...mountDescriptor,
+							initialSyncDirection: 'opfs-to-memfs' as const,
+						},
+					]
+				: [];
+
 		let playground: PlaygroundClient | undefined = undefined;
 		try {
 			const phpExtensions = phpExtensionQueryArgsToExtensionsArray(
@@ -187,14 +206,7 @@ export function bootSiteClient(
 				},
 				// Log Blueprint events
 				onBlueprintValidated: logBlueprintEvents,
-				mounts: mountDescriptor
-					? [
-							{
-								...mountDescriptor,
-								initialSyncDirection: 'opfs-to-memfs',
-							},
-						]
-					: [],
+				mounts,
 				wordpressInstallMode,
 				corsProxy: corsProxyUrl,
 				gitAdditionalHeadersCallback: createGitAuthHeaders(),
@@ -290,19 +302,137 @@ export function bootSiteClient(
 		if (signal.aborted || !playground) {
 			return;
 		}
+		const connectedPlayground = playground as PlaygroundClient;
 
 		setupPostMessageRelay(iframe, document.location.origin);
 
 		dispatch(
 			addClientInfo({
 				siteSlug: site.slug,
 				url: '/',
-				client: playground,
+				client: connectedPlayground,
 				opfsMountDescriptor: mountDescriptor,
+				opfsSync: shouldSyncNewOpfsSiteInBackground
+					? {
+							status: 'syncing',
+							operation: syncOperation,
+						}
+					: undefined,
 			})
 		);
+		if (site.metadata.storage !== 'none') {
+			try {
+				await dispatch(
+					updateSiteMetadata({
+						slug: site.slug,
+						changes: {
+							whenLastUsed: Date.now(),
+						},
+					})
+				);
+			} catch (error) {
+				logger.error('Error updating Playground last-used time', error);
+			}
+		}
+
+		if (
+			site.metadata.initialOpfsSyncPending &&
+			!shouldSyncNewOpfsSiteInBackground
+		) {
+			try {
+				await dispatch(
+					updateSiteMetadata({
+						slug: site.slug,
+						changes: {
+							initialOpfsSyncPending: false,
+						},
+					})
+				);
+			} catch (error) {
+				logger.error(
+					'Error updating Playground initial sync state',
+					error
+				);
+			}
+		}
+
+		if (shouldSyncNewOpfsSiteInBackground && mountDescriptor) {
+			// Progress callbacks cross worker and iframe boundaries asynchronously.
+			// A final progress message may arrive after mountOpfs() resolves and
+			// must not resurrect the completed sync state in Redux.
+			let opfsMountSettled = false;
+			void connectedPlayground
+				.mountOpfs(
+					{
+						...mountDescriptor,
+						initialSyncDirection: 'memfs-to-opfs',
+					},
+					(progress: SyncProgress) => {
+						if (opfsMountSettled) {
+							return;
+						}
+						dispatch(
+							updateClientInfo({
+								siteSlug: site.slug,
+								changes: {
+									opfsSync: {
+										status: 'syncing',
+										progress,
+										operation: syncOperation,
+									},
+								},
+							})
+						);
+					}
+				)
+				.then(async () => {
+					try {
+						await dispatch(
+							updateSiteMetadata({
+								slug: site.slug,
+								changes: {
+									initialOpfsSyncPending: false,
+								},
+							})
+						);
+					} catch (error) {
+						logger.error(
+							'Error updating Playground initial sync state',
+							error
+						);
+					}
+					await new Promise((resolve) => setTimeout(resolve, 100));
+					opfsMountSettled = true;
+					dispatch(
+						updateClientInfo({
+							siteSlug: site.slug,
+							changes: {
+								opfsSync: undefined,
+							},
+						})
+					);
+				})
+				.catch((error: unknown) => {
+					opfsMountSettled = true;
+					logger.error(
+						'Error syncing saved Playground to OPFS',
+						error
+					);
+					dispatch(
+						updateClientInfo({
+							siteSlug: site.slug,
+							changes: {
+								opfsSync: {
+									status: 'error',
+									operation: syncOperation,
+								},
+							},
+						})
+					);
+				});
+		}
 
-		(playground as PlaygroundClient).onNavigation((url) => {
+		connectedPlayground.onNavigation((url) => {
 			dispatch(
 				updateClientInfo({
 					siteSlug: site.slug,

packages/playground/website/src/lib/state/redux/persist-temporary-site.ts

@@ -16,6 +16,7 @@ import type store from './store';
 import { selectClientBySiteSlug, updateClientInfo } from './slice-clients';
 import {
 	selectSiteBySlug,
+	type SitePersistence,
 	updateSite,
 	updateSiteMetadata,
 } from './slice-sites';
@@ -30,6 +31,10 @@ export function persistTemporarySite(
 		localFsHandle?: FileSystemDirectoryHandle;
 		siteName?: string;
 		skipRenameModal?: boolean;
+		persistence?: SitePersistence;
+		updateUrl?: boolean;
+		keepOriginalUrlParams?: boolean;
+		keepRunningClient?: boolean;
 	} = {}
 ) {
 	return async (
@@ -156,13 +161,18 @@ export function persistTemporarySite(
 		} else {
 			throw new Error(`Unsupported device type: ${storageType}`);
 		}
+		const syncOperation =
+			options.persistence === 'autosave' ? 'autosave' : 'save';
 
 		dispatch(
 			updateClientInfo({
 				siteSlug,
 				changes: {
 					opfsMountDescriptor: mountDescriptor,
-					opfsSync: { status: 'syncing' },
+					opfsSync: {
+						status: 'syncing',
+						operation: syncOperation,
+					},
 				},
 			})
 		);
@@ -180,6 +190,7 @@ export function persistTemporarySite(
 								opfsSync: {
 									status: 'syncing',
 									progress,
+									operation: syncOperation,
 								},
 							},
 						})
@@ -203,37 +214,52 @@ export function persistTemporarySite(
 					changes: {
 						opfsSync: {
 							status: 'error',
+							operation: syncOperation,
 						},
 					},
 				})
 			);
 			throw error;
 		}
 
-		await dispatch(
-			updateSite({
-				slug: siteSlug,
-				changes: {
-					originalUrlParams: undefined,
-				},
-			})
-		);
+		if (!options.keepOriginalUrlParams) {
+			await dispatch(
+				updateSite({
+					slug: siteSlug,
+					changes: {
+						originalUrlParams: undefined,
+					},
+				})
+			);
+		}
 
+		const persistedAt = Date.now();
+		const runtimeConfiguration = {
+			...siteInfo.metadata.runtimeConfiguration,
+			constants: await getPlaygroundDefinedPHPConstants(playground),
+		};
 		await dispatch(
 			updateSiteMetadata({
 				slug: siteSlug,
 				changes: {
 					storage: storageType,
-					// Reset the created date. Mental model: From the perspective of
-					// the storage backend, the site was just created.
-					whenCreated: Date.now(),
+					persistence: options.persistence ?? 'explicit',
+					/**
+					 * The viewport key includes whenCreated to distinguish
+					 * delete/recreate cycles for the same slug. The delayed
+					 * autosave path already has a live Playground iframe and
+					 * must not change that key, or React will remount it after
+					 * the OPFS sync completes.
+					 */
+					...(options.keepRunningClient
+						? {}
+						: { whenCreated: persistedAt }),
+					whenLastUsed: persistedAt,
 					// Make sure to store the constants we'll want to re-apply
 					// on the next page load.
-					runtimeConfiguration: {
-						...siteInfo.metadata.runtimeConfiguration,
-						constants:
-							await getPlaygroundDefinedPHPConstants(playground),
-					},
+					...(options.keepRunningClient
+						? {}
+						: { runtimeConfiguration }),
 					// If we persisted a blueprint bundle, point to it so we can
 					// load the full bundle (not just the declaration) on next load.
 					...(bundleWasPersisted
@@ -247,6 +273,15 @@ export function persistTemporarySite(
 				},
 			})
 		);
+		if (options.keepRunningClient) {
+			const updatedSite = selectSiteBySlug(getState(), siteSlug);
+			if (updatedSite?.metadata.storage !== 'none') {
+				await opfsSiteStorage?.update(updatedSite.slug, {
+					...updatedSite.metadata,
+					runtimeConfiguration,
+				});
+			}
+		}
 		/**
 		 * @TODO: Fix OPFS site storage write timeout that happens alongside 2000
 		 *        "Cannot read properties of undefined (reading 'apply')" errors here:
@@ -258,7 +293,9 @@ export function persistTemporarySite(
 		const updatedState = getState();
 		const updatedSite = selectSiteBySlug(updatedState, siteSlug);
 		const persistentSiteUrl = PlaygroundRoute.site(updatedSite!);
-		redirectTo(persistentSiteUrl);
+		if (options.updateUrl !== false) {
+			redirectTo(persistentSiteUrl);
+		}
 		if (!options.skipRenameModal) {
 			dispatch(setActiveModal('rename-site'));
 		}