Playground Public API

[adamziel]

Description

With this PR, Playground exposes a consistent communication layer for its consumers:

const playground = connect( iframe.contentWindow );
playground.writeFile( '/wordpress/test.php', 'Hello, world!' );
playground.goTo( '/test.php' );

It means your app can have the same powers as the official demo. Just note this PR does not expose any public packages yet. That will be the next step.

Under the hood

Technically, this PR:

1. Formalizes php-wasm public API
2. Formalizes Playground public API as an extension of the above
3. Uses the comlink library to expose Playground's public API

There are a few layers to this:

• Playground worker initializes the PHP and WordPress and exposes an internal API using comlink
• Playground "connector" HTML page consumes the worker API, extends it, and re-exposes it publicly using comlink
• Playground UI is now a separate app that connects to the "connector" page and consumes its API using comlink

All the public-facing features, like plugin pre-installation or import/export, are now implemented by consuming the public API. Once I publish these features in npm, consuming Playground will be as simple as importing a package.

This PR also refactors the Playground website to use React – this process was indispensable in shaping the public API.

Public API

Here's the raw interface – the documentation will be shipped with the npm package and provided in this repo.

interface PlaygroundAPI {
	absoluteUrl: string;
	goTo(requestedPath: string): Promise<void>;
	getCurrentURL(): Promise<void>;
	setIframeSandboxFlags(flags: string[]): Promise<void>;

	onNavigation(callback: (newURL: string) => void): Promise<void>;
	onDownloadProgress(
		callback: (progress: CustomEvent<ProgressEvent>) => void
	): Promise<void>;

	getWordPressModuleDetails(): Promise<{ staticAssetsDirectory: string; defaultTheme: string; }>;

	pathToInternalUrl(path: string): Promise<string>;
	internalUrlToPath(internalUrl: string): Promise<string>;

	request(
		request: PHPServerRequest,
		redirects?: number
	): Promise<PHPResponse>;
	run(request?: PHPRequest | undefined): Promise<PHPResponse>;
	setPhpIniPath(path: string): Promise<void>;
	setPhpIniEntry(key: string, value: string): Promise<void>;
	mkdirTree(path: string): Promise<void>;
	readFileAsText(path: string): Promise<string>;
	readFileAsBuffer(path: string): Promise<Uint8Array>;
	writeFile(path: string, data: string | Uint8Array): Promise<void>;
	unlink(path: string): Promise<void>;
	listFiles(path: string): Promise<string[]>;
	isDir(path: string): Promise<boolean>;
	fileExists(path: string): Promise<boolean>;
}

[adamziel]

I'm going to merge this as it's a blocker for the public npm package