[Client] Explicit Blueprints v1 handler (#2651)

Moves a chunk of the Blueprint v1-specific initialization logic into a
dedicated BlueprintsV1Handler class – similarly to how the Playground
CLI works.

There are no logic changes, this just moves the code around.

Sets the stage for #2586

 ## Testing instructions

CI

Author: adamziel

packages/playground/client/src/blueprints-v1-handler.ts

@@ -0,0 +1,82 @@
+import type { ProgressTracker } from '@php-wasm/progress';
+import {
+	type PlaygroundClient,
+	type StartPlaygroundOptions,
+	compileBlueprintV1,
+	runBlueprintV1Steps,
+} from '.';
+import { collectPhpLogs, logger } from '@php-wasm/logger';
+import { consumeAPI } from '@php-wasm/universal';
+
+export class BlueprintsV1Handler {
+	constructor(private readonly options: StartPlaygroundOptions) {}
+
+	async bootPlayground(
+		iframe: HTMLIFrameElement,
+		progressTracker: ProgressTracker
+	) {
+		const {
+			onBlueprintValidated,
+			onBlueprintStepCompleted,
+			corsProxy,
+			mounts,
+			sapiName,
+			scope,
+			shouldInstallWordPress,
+			sqliteDriverVersion,
+			onClientConnected,
+		} = this.options;
+		const executionProgress = progressTracker!.stage(0.5);
+		const downloadProgress = progressTracker!.stage();
+
+		// Set a default blueprint if none is provided.
+		const blueprint = this.options.blueprint || {};
+		const compiled = await compileBlueprintV1(blueprint, {
+			progress: executionProgress,
+			onStepCompleted: onBlueprintStepCompleted,
+			onBlueprintValidated,
+			corsProxy,
+		});
+
+		// Connect the Comlink API client to the remote worker,
+		// boot the playground, and run the blueprint steps.
+		const playground = consumeAPI<PlaygroundClient>(
+			iframe.contentWindow!,
+			iframe.ownerDocument!.defaultView!
+		) as PlaygroundClient;
+		await playground.isConnected();
+		progressTracker.pipe(playground);
+
+		await playground.onDownloadProgress(downloadProgress.loadingListener);
+		await playground.boot({
+			mounts,
+			sapiName,
+			scope: scope ?? Math.random().toFixed(16),
+			shouldInstallWordPress,
+			phpVersion: compiled.versions.php,
+			wpVersion: compiled.versions.wp,
+			withICU: compiled.features.intl,
+			withNetworking: compiled.features.networking,
+			corsProxyUrl: corsProxy,
+			sqliteDriverVersion,
+		});
+		await playground.isReady();
+		downloadProgress.finish();
+
+		collectPhpLogs(logger, playground);
+		onClientConnected?.(playground);
+
+		await runBlueprintV1Steps(compiled, playground);
+
+		/**
+		 * Pre-fetch WordPress update checks to speed up the initial wp-admin load.
+		 *
+		 * @see https://github.com/WordPress/wordpress-playground/pull/2295
+		 */
+		if (compiled.features.networking) {
+			await playground.prefetchUpdateChecks();
+		}
+
+		return playground;
+	}
+}

packages/playground/client/src/index.ts

@@ -30,17 +30,12 @@ import type {
 	BlueprintV1Declaration,
 	OnStepCompleted,
 } from '@wp-playground/blueprints';
-import {
-	compileBlueprintV1,
-	runBlueprintV1Steps,
-} from '@wp-playground/blueprints';
-import { consumeAPI } from '@php-wasm/web';
 import { ProgressTracker } from '@php-wasm/progress';
 import type { MountDescriptor, PlaygroundClient } from '@wp-playground/remote';
-import { collectPhpLogs, logger } from '@php-wasm/logger';
 import { additionalRemoteOrigins } from './additional-remote-origins';
 // eslint-disable-next-line @nx/enforce-module-boundaries
 import { remoteDevServerHost, remoteDevServerPort } from '../../build-config';
+import { BlueprintsV1Handler } from './blueprints-v1-handler';
 
 export interface StartPlaygroundOptions {
 	iframe: HTMLIFrameElement;
@@ -99,22 +94,15 @@ export interface StartPlaygroundOptions {
  * @param options Options for loading the playground.
  * @returns A PlaygroundClient instance.
  */
-export async function startPlaygroundWeb({
-	iframe,
-	blueprint,
-	remoteUrl,
-	progressTracker = new ProgressTracker(),
-	disableProgressBar,
-	onBlueprintStepCompleted,
-	onBlueprintValidated,
-	onClientConnected = () => {},
-	sapiName,
-	mounts,
-	scope,
-	corsProxy,
-	shouldInstallWordPress,
-	sqliteDriverVersion,
-}: StartPlaygroundOptions): Promise<PlaygroundClient> {
+export async function startPlaygroundWeb(
+	options: StartPlaygroundOptions
+): Promise<PlaygroundClient> {
+	const {
+		iframe,
+		progressTracker = new ProgressTracker(),
+		disableProgressBar,
+	} = options;
+	let { remoteUrl } = options;
 	assertLikelyCompatibleRemoteOrigin(remoteUrl);
 	allowStorageAccessByUserActivation(iframe);
 
@@ -123,60 +111,14 @@ export async function startPlaygroundWeb({
 	});
 	progressTracker.setCaption('Preparing WordPress');
 
-	// Set a default blueprint if none is provided.
-	if (!blueprint) {
-		blueprint = {};
-	}
-
-	const compiled = await compileBlueprintV1(blueprint, {
-		progress: progressTracker.stage(0.5),
-		onStepCompleted: onBlueprintStepCompleted,
-		onBlueprintValidated,
-		corsProxy,
-	});
-
 	await new Promise((resolve) => {
 		iframe.src = remoteUrl;
 		iframe.addEventListener('load', resolve, false);
 	});
 
-	// Connect the Comlink API client to the remote worker,
-	// boot the playground, and run the blueprint steps.
-	const playground = consumeAPI<PlaygroundClient>(
-		iframe.contentWindow!,
-		iframe.ownerDocument!.defaultView!
-	) as PlaygroundClient;
-	await playground.isConnected();
-	progressTracker.pipe(playground);
-	const downloadPHPandWP = progressTracker.stage();
-	await playground.onDownloadProgress(downloadPHPandWP.loadingListener);
-	await playground.boot({
-		mounts,
-		sapiName,
-		scope: scope ?? Math.random().toFixed(16),
-		shouldInstallWordPress,
-		phpVersion: compiled.versions.php,
-		wpVersion: compiled.versions.wp,
-		withICU: compiled.features.intl,
-		withNetworking: compiled.features.networking,
-		corsProxyUrl: corsProxy,
-		sqliteDriverVersion,
-	});
-	await playground.isReady();
-	downloadPHPandWP.finish();
+	const handler = new BlueprintsV1Handler(options);
+	const playground = await handler.bootPlayground(iframe, progressTracker);
 
-	collectPhpLogs(logger, playground);
-	onClientConnected(playground);
-
-	await runBlueprintV1Steps(compiled, playground);
-	/**
-	 * Pre-fetch WordPress update checks to speed up the initial wp-admin load.
-	 *
-	 * @see https://github.com/WordPress/wordpress-playground/pull/2295
-	 */
-	if (compiled.features.networking) {
-		await playground.prefetchUpdateChecks();
-	}
 	progressTracker.finish();
 
 	return playground;