Add saved site creation APIs

Author: adamziel

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

@@ -20,7 +20,9 @@ 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');
+	// Storage-specific behavior is covered below. This test only checks that
+	// the list exposes the active Playground through the public API shape.
+	expect(['opfs', 'local-fs', 'temporary']).toContain(active.storage);
 });
 
 test('playgroundSites.saveInBrowser() persists a temporary site', async ({
@@ -32,7 +34,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())
 	);
@@ -44,6 +46,87 @@ test('playgroundSites.saveInBrowser() persists a temporary site', async ({
 	expect(result.storage).toBe('opfs');
 });
 
+test('playgroundSites.autosaveTemporarySite() persists without disrupting the tab', async ({
+	website,
+	browserName,
+}) => {
+	test.skip(
+		browserName !== 'chromium',
+		`This test relies on OPFS which isn't available in Playwright's flavor of ${browserName}.`
+	);
+
+	await website.goto('./?storage=temp');
+	await website.page.waitForFunction(() =>
+		Boolean((window as any).playgroundSites?.getClient())
+	);
+
+	const result = await website.page.evaluate(async () => {
+		const api = (window as any).playgroundSites;
+		const beforeUrl = window.location.href;
+		const beforeClient = api.getClient();
+		const beforeActive = api.list().find((s: any) => s.isActive);
+		const saveResult = await api.autosaveTemporarySite();
+		const afterActive = api.list().find((s: any) => s.isActive);
+		return {
+			beforeSlug: beforeActive?.slug,
+			saveResult,
+			afterActive,
+			sameClient: beforeClient === api.getClient(),
+			sameUrl: window.location.href === beforeUrl,
+		};
+	});
+
+	// Autosave should promote the active temporary site to browser storage
+	// without changing the visible URL or replacing the running Playground.
+	expect(result.saveResult.slug).toBe(result.beforeSlug);
+	expect(result.saveResult.storage).toBe('opfs');
+	expect(result.afterActive.storage).toBe('opfs');
+	expect(result.afterActive.persistence).toBe('autosave');
+	expect(result.sameClient).toBe(true);
+	expect(result.sameUrl).toBe(true);
+});
+
+test('playgroundSites.createNewSavedSite() creates an explicit OPFS site by default', async ({
+	website,
+	browserName,
+}) => {
+	test.skip(
+		browserName !== 'chromium',
+		`This test relies on OPFS which isn't available in Playwright's flavor of ${browserName}.`
+	);
+
+	await website.goto('./?storage=temp');
+	await website.page.waitForFunction(() =>
+		Boolean((window as any).playgroundSites?.getClient())
+	);
+
+	const result = await website.page.evaluate(async () => {
+		const api = (window as any).playgroundSites;
+		const beforeUrl = window.location.href;
+		const slug = await api.createNewSavedSite(
+			'api-created-site',
+			{ phpVersion: '8.3' },
+			{ updateUrl: false }
+		);
+		const active = api.list().find((s: any) => s.isActive);
+		return {
+			slug,
+			active,
+			sameUrl: window.location.href === beforeUrl,
+			hasClient: api.getClient() != null,
+		};
+	});
+
+	// The new API creates a saved site record, boots it, and marks it as an
+	// explicit save unless the caller opts into autosave persistence.
+	expect(result.slug).toBe('api-created-site');
+	expect(result.active.slug).toBe('api-created-site');
+	expect(result.active.storage).toBe('opfs');
+	expect(result.active.persistence).toBe('explicit');
+	expect(result.hasClient).toBe(true);
+	expect(result.sameUrl).toBe(true);
+});
+
 test('playgroundSites.rename() renames a saved site', async ({
 	website,
 	browserName,
@@ -60,8 +143,8 @@ 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.saveInBrowser();
 		await api.rename(name);
 		const sites = api.list();
 		const active = sites.find((s: any) => s.isActive);

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';
@@ -142,7 +146,10 @@ export function bootSiteClient(
 				},
 				extraLibraries: site.metadata.runtimeConfiguration
 					.extraLibraries as any[],
-				constants: site.metadata.runtimeConfiguration.constants,
+				constants: {
+					...site.metadata.runtimeConfiguration.constants,
+					...site.metadata.playgroundDefinedConstants,
+				},
 			};
 		} else {
 			blueprint = site.metadata.originalBlueprint;
@@ -161,6 +168,27 @@ export function bootSiteClient(
 				? 'install-from-existing-files-if-needed'
 				: 'download-and-install';
 
+		// A newly created saved site has wp-runtime.json in OPFS, but not the
+		// WordPress tree yet. The first boot must let the setup URL build that
+		// tree in MEMFS. Passing the OPFS mount here would copy the
+		// metadata-only directory into /wordpress, so seed OPFS from MEMFS after
+		// the iframe connects instead.
+		const shouldFinishInitialOpfsSyncInBackground =
+			site.metadata.initialOpfsSyncPending === true &&
+			site.metadata.storage === 'opfs' &&
+			!!mountDescriptor &&
+			!isWordPressInstalled;
+		const syncOperation = isAutosavedSite(site) ? 'autosave' : 'save';
+		const mounts =
+			mountDescriptor && !shouldFinishInitialOpfsSyncInBackground
+				? [
+						{
+							...mountDescriptor,
+							initialSyncDirection: 'opfs-to-memfs' as const,
+						},
+					]
+				: [];
+
 		let playground: PlaygroundClient | undefined = undefined;
 		try {
 			const phpExtensions = phpExtensionQueryArgsToExtensionsArray(
@@ -187,14 +215,7 @@ export function bootSiteClient(
 				},
 				// Log Blueprint events
 				onBlueprintValidated: logBlueprintEvents,
-				mounts: mountDescriptor
-					? [
-							{
-								...mountDescriptor,
-								initialSyncDirection: 'opfs-to-memfs',
-							},
-						]
-					: [],
+				mounts,
 				wordpressInstallMode,
 				corsProxy: corsProxyUrl,
 				gitAdditionalHeadersCallback: createGitAuthHeaders(),
@@ -290,19 +311,140 @@ 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: shouldFinishInitialOpfsSyncInBackground
+					? {
+							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 WordPress was already present in OPFS, the regular OPFS-to-MEMFS
+		// mount above completed the initial sync path.
+		const shouldClearInitialOpfsSyncPending =
+			site.metadata.initialOpfsSyncPending === true &&
+			site.metadata.storage === 'opfs' &&
+			!!mountDescriptor &&
+			!shouldFinishInitialOpfsSyncInBackground;
+		if (shouldClearInitialOpfsSyncPending) {
+			try {
+				await dispatch(
+					updateSiteMetadata({
+						slug: site.slug,
+						changes: {
+							initialOpfsSyncPending: false,
+						},
+					})
+				);
+			} catch (error) {
+				logger.error(
+					'Error updating Playground initial sync state',
+					error
+				);
+			}
+		}
+
+		if (shouldFinishInitialOpfsSyncInBackground && 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 () => {
+					opfsMountSettled = true;
+					try {
+						await dispatch(
+							updateSiteMetadata({
+								slug: site.slug,
+								changes: {
+									initialOpfsSyncPending: false,
+								},
+							})
+						);
+					} catch (error) {
+						logger.error(
+							'Error updating Playground initial sync state',
+							error
+						);
+					}
+					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,