Add lightweight saved-site export API

Author: ashfame

packages/playground/client/README.md

@@ -22,6 +22,32 @@ console.log(response.text);
 
 Loading the client from `https://playground.wordpress.net/client/index.js` keeps it in sync with the remote Playground runtime. The client and the iframe communicate over an internal protocol, and backwards compatibility is guaranteed by serving a matching client and remote from the same deployment.
 
+## Saved-site export API
+
+Use `startPlaygroundAPI()` to work with saved OPFS Playgrounds without booting WordPress, PHP, workers, or a service worker. The API endpoint must have the same origin and browser storage partition as the Playground that saved the site. WebKit requires save and export to use the same top-level origin, including its scheme, host, and port; a site saved while Playground is top-level is not visible to an API iframe embedded under another top-level origin.
+
+The `/api.html` entry point is part of the full Playground website deployment. It is not included in the `@wp-playground/remote` npm package.
+
+```js
+import { startPlaygroundAPI } from 'https://playground.wordpress.net/client/index.js';
+
+const iframe = document.createElement('iframe');
+iframe.hidden = true;
+iframe.sandbox.add('allow-scripts');
+iframe.sandbox.add('allow-same-origin');
+document.body.appendChild(iframe);
+
+const api = await startPlaygroundAPI({
+	iframe,
+	apiUrl: 'https://playground.wordpress.net/api.html',
+});
+const zip = await api.exportSavedSiteAsZip('my-site', {
+	excludePatterns: ['/*', '!/wp-content/', '!/wp-content/**'],
+});
+```
+
+The optional `excludePatterns` use gitignore semantics: matching paths are excluded, later patterns take precedence, and a leading `!` re-includes a path. When `excludePatterns` is omitted, the ZIP contains the complete saved site.
+
 ## npm package
 
 The npm package exists for projects that want to install `@wp-playground/client` through a package manager, bundle it with their application, or use its TypeScript declarations locally.

packages/playground/client/src/index.spec.ts

@@ -13,6 +13,7 @@ const mocks = vi.hoisted(() => {
 		BlueprintsV1Handler: vi.fn(),
 		BlueprintsV2Handler: vi.fn(),
 		createBlueprintReflection: vi.fn(),
+		consumeAPI: vi.fn(),
 	};
 });
 
@@ -31,7 +32,15 @@ vi.mock('./blueprints-v2-handler', () => ({
 	BlueprintsV2Handler: mocks.BlueprintsV2Handler,
 }));
 
-import { startPlaygroundWeb } from './index';
+vi.mock('@php-wasm/universal', async (importActual) => {
+	const actual = await importActual();
+	return {
+		...(actual as object),
+		consumeAPI: mocks.consumeAPI,
+	};
+});
+
+import { startPlaygroundAPI, startPlaygroundWeb } from './index';
 
 describe('startPlaygroundWeb', () => {
 	afterEach(() => {
@@ -121,9 +130,69 @@ describe('startPlaygroundWeb', () => {
 	});
 });
 
+describe('startPlaygroundAPI', () => {
+	afterEach(() => {
+		vi.clearAllMocks();
+	});
+
+	it('loads api.html and returns its API client', async () => {
+		const api = createAPIClient();
+		mocks.consumeAPI.mockReturnValue(api);
+		const iframe = createIframe();
+
+		await expect(
+			startPlaygroundAPI({
+				iframe,
+				apiUrl: 'http://localhost/api.html',
+			})
+		).resolves.toBe(api);
+
+		expect(iframe.src).toBe('http://localhost/api.html');
+		expect(mocks.consumeAPI).toHaveBeenCalledWith(
+			iframe.contentWindow,
+			iframe.ownerDocument!.defaultView
+		);
+		expect(api.isConnected).toHaveBeenCalledTimes(1);
+		expect(api.isReady).toHaveBeenCalledTimes(1);
+	});
+
+	it('resolves a relative API URL against the default remote origin', async () => {
+		mocks.consumeAPI.mockReturnValue(createAPIClient());
+		const iframe = createIframe();
+
+		await startPlaygroundAPI({
+			iframe,
+			apiUrl: '/api.html',
+		});
+
+		expect(iframe.src).toBe('https://playground.wordpress.net/api.html');
+	});
+
+	it('requires the API URL to point to api.html', async () => {
+		await expect(
+			startPlaygroundAPI({
+				iframe: createIframe(),
+				apiUrl: 'http://localhost/remote.html',
+			})
+		).rejects.toThrow('/api.html');
+	});
+});
+
+function createAPIClient() {
+	return {
+		isConnected: vi.fn(async () => undefined),
+		isReady: vi.fn(async () => undefined),
+		exportSavedSiteAsZip: vi.fn(),
+	};
+}
+
 function createIframe() {
 	return {
 		src: '',
+		contentWindow: {},
+		ownerDocument: {
+			defaultView: {},
+		},
 		addEventListener: vi.fn((_event, callback: () => void) => {
 			callback();
 		}),

packages/playground/client/src/index.ts

@@ -46,7 +46,7 @@ import type {
 	PlaygroundClient,
 	SiteThumbnail,
 } from '@wp-playground/remote';
-import type { PathAlias } from '@php-wasm/universal';
+import { consumeAPI, type PathAlias } from '@php-wasm/universal';
 import type { PHPWebExtension } from '@php-wasm/web';
 import { additionalRemoteOrigins } from './additional-remote-origins';
 // eslint-disable-next-line @nx/enforce-module-boundaries
@@ -147,6 +147,26 @@ export interface StartPlaygroundWebOptions extends Omit<
 	onBlueprintValidated?: (blueprint: BlueprintDeclaration) => void;
 }
 
+export interface ExportSavedSiteAsZipOptions {
+	/**
+	 * Gitignore-style exclusion patterns applied relative to the saved site root.
+	 * Patterns starting with `!` re-include paths.
+	 */
+	excludePatterns?: readonly string[];
+}
+
+export interface PlaygroundAPIClient {
+	exportSavedSiteAsZip(
+		slug: string,
+		options?: ExportSavedSiteAsZipOptions
+	): Promise<Blob | undefined>;
+}
+
+export interface StartPlaygroundAPIOptions {
+	iframe: HTMLIFrameElement;
+	apiUrl: string;
+}
+
 /**
  * Loads playground in iframe and returns a PlaygroundClient instance.
  *
@@ -196,6 +216,34 @@ export async function startPlaygroundWeb(
 	return playground;
 }
 
+/**
+ * Loads the lightweight Playground API endpoint without booting WordPress.
+ *
+ * The API endpoint and saved OPFS site must share an origin and storage partition.
+ */
+export async function startPlaygroundAPI(
+	options: StartPlaygroundAPIOptions
+): Promise<PlaygroundAPIClient> {
+	const { iframe, apiUrl } = options;
+	assertLikelyCompatibleAPIOrigin(apiUrl);
+	allowStorageAccessByUserActivation(iframe);
+	const resolvedAPIUrl = new URL(apiUrl, remoteOrigin).toString();
+
+	await new Promise((resolve) => {
+		iframe.src = resolvedAPIUrl;
+		iframe.addEventListener('load', resolve, false);
+	});
+
+	const api = consumeAPI<PlaygroundAPIClient>(
+		iframe.contentWindow!,
+		iframe.ownerDocument!.defaultView!
+	);
+	await api.isConnected();
+	await api.isReady();
+
+	return api;
+}
+
 async function shouldUseBlueprintV2Handler(
 	blueprint: StartPlaygroundWebOptions['blueprint']
 ) {
@@ -265,16 +313,27 @@ const remoteOrigin =
  * @param remoteHtmlUrl The URL for remote.html
  */
 function assertLikelyCompatibleRemoteOrigin(remoteHtmlUrl: string) {
-	const url = new URL(remoteHtmlUrl, remoteOrigin);
+	assertLikelyCompatibleRemotePath(remoteHtmlUrl, '/remote.html');
+}
+
+function assertLikelyCompatibleAPIOrigin(apiUrl: string) {
+	assertLikelyCompatibleRemotePath(apiUrl, '/api.html');
+}
+
+function assertLikelyCompatibleRemotePath(
+	urlString: string,
+	expectedPath: string
+) {
+	const url = new URL(urlString, remoteOrigin);
 
 	const validRemote =
 		validRemoteOrigins.includes(url.origin) &&
-		url.pathname === '/remote.html';
+		url.pathname === expectedPath;
 
 	if (!validRemote) {
 		throw new Error(
 			`Invalid remote URL: ${url}. ` +
-				'Expected remote URL to have a path of "/remote.html" based ' +
+				`Expected remote URL to have a path of "${expectedPath}" based ` +
 				`on one of the following origins:\n ${validRemoteOrigins.join(
 					'\n'
 				)}`

packages/playground/website/api.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html>
+	<head>
+		<title>WordPress Playground API</title>
+	</head>
+	<body>
+		<script type="module">
+			import { bootPlaygroundAPI } from './src/lib/boot-playground-api';
+
+			window.playgroundAPI = bootPlaygroundAPI();
+		</script>
+	</body>
+</html>

packages/playground/website/src/lib/boot-playground-api.spec.ts

@@ -0,0 +1,75 @@
+import { bootPlaygroundAPI } from './boot-playground-api';
+
+const mocks = vi.hoisted(() => {
+	const exportSavedSiteAsZip = vi.fn();
+	return {
+		exposeAPI: vi.fn(),
+		exportSavedSiteAsZip,
+		opfsSiteStorage: { exportSavedSiteAsZip } as
+			| { exportSavedSiteAsZip: typeof exportSavedSiteAsZip }
+			| undefined,
+		setAPIReady: vi.fn(),
+	};
+});
+
+vi.mock('@php-wasm/universal', () => ({
+	exposeAPI: mocks.exposeAPI,
+}));
+
+vi.mock('./state/opfs/opfs-site-storage', () => ({
+	get opfsSiteStorage() {
+		return mocks.opfsSiteStorage;
+	},
+}));
+
+describe('bootPlaygroundAPI', () => {
+	beforeEach(() => {
+		mocks.opfsSiteStorage = {
+			exportSavedSiteAsZip: mocks.exportSavedSiteAsZip,
+		};
+	});
+
+	afterEach(() => {
+		vi.clearAllMocks();
+	});
+
+	it('exposes the saved-site export API and forwards its options', async () => {
+		const exposedAPI = { isReady: vi.fn() };
+		mocks.exposeAPI.mockReturnValue([
+			mocks.setAPIReady,
+			vi.fn(),
+			exposedAPI,
+		]);
+		const zip = new Blob(['zip'], { type: 'application/zip' });
+		mocks.exportSavedSiteAsZip.mockResolvedValue(zip);
+
+		expect(bootPlaygroundAPI()).toBe(exposedAPI);
+		const methods = mocks.exposeAPI.mock.calls[0][0];
+		await expect(
+			methods.exportSavedSiteAsZip('my-site', {
+				excludePatterns: ['/*', '!/wp-content/**'],
+			})
+		).resolves.toBe(zip);
+
+		expect(mocks.exportSavedSiteAsZip).toHaveBeenCalledWith('my-site', {
+			excludePatterns: ['/*', '!/wp-content/**'],
+		});
+		expect(mocks.setAPIReady).toHaveBeenCalledTimes(1);
+	});
+
+	it('reports when OPFS site storage is unavailable', async () => {
+		mocks.exposeAPI.mockReturnValue([
+			mocks.setAPIReady,
+			vi.fn(),
+			{ isReady: vi.fn() },
+		]);
+		mocks.opfsSiteStorage = undefined;
+
+		bootPlaygroundAPI();
+		const methods = mocks.exposeAPI.mock.calls[0][0];
+
+		await expect(methods.exportSavedSiteAsZip('my-site')).rejects.toThrow(
+			'OPFS site storage is unavailable in this context.'
+		);
+	});
+});

packages/playground/website/src/lib/boot-playground-api.ts

@@ -0,0 +1,18 @@
+import { exposeAPI } from '@php-wasm/universal';
+import type { PlaygroundAPIClient } from '@wp-playground/client';
+import { opfsSiteStorage } from './state/opfs/opfs-site-storage';
+
+export function bootPlaygroundAPI() {
+	const [setAPIReady, , api] = exposeAPI<PlaygroundAPIClient, undefined>({
+		async exportSavedSiteAsZip(slug, options) {
+			if (!opfsSiteStorage) {
+				throw new Error(
+					'OPFS site storage is unavailable in this context.'
+				);
+			}
+			return await opfsSiteStorage.exportSavedSiteAsZip(slug, options);
+		},
+	});
+	setAPIReady();
+	return api;
+}

packages/playground/website/src/lib/state/opfs/opfs-site-storage.ts

@@ -21,6 +21,7 @@ import {
 	type PHPConstants,
 	getBlueprintDeclaration,
 } from '@wp-playground/blueprints';
+import type { ExportSavedSiteAsZipOptions } from '@wp-playground/client';
 import type { AllPHPVersion } from '@php-wasm/universal';
 import { RecommendedPHPVersion } from '@wp-playground/common';
 import {
@@ -65,14 +66,6 @@ type StoredSiteChanges = {
 	originalUrlParams?: OriginalUrlParams;
 };
 
-export interface ExportSavedSiteAsZipOptions {
-	/**
-	 * Gitignore-style exclusion patterns applied relative to the saved site root.
-	 * Patterns starting with `!` re-include paths.
-	 */
-	excludePatterns?: readonly string[];
-}
-
 let opfsSitesRoot: FileSystemDirectoryHandle | undefined = undefined;
 try {
 	opfsSitesRoot = await navigator.storage.getDirectory();