@wp-playground/client 0.1.17 → 0.1.18

package/README.md

@@ -1,7 +1,6 @@
 # Playground Client
 
-Provides a WordPress Playground client you can bind to a Playground iframe
-to control the embedded WordPress site. Here's how to use it:
+Provides a [PlaygroundClient](https://wordpress.github.io/wordpress-playground/interfaces/_wp_playground_client.PlaygroundClient.html) that can be used to control a WordPress Playground iframe:
 
 ```ts
 import { connectPlayground } from '@wp-playground/client';
@@ -10,11 +9,46 @@ const client = await connectPlayground(
 	// An iframe pointing to https://playground.wordpress.net/remote.html
 	document.getElementById('wp')! as HTMLIFrameElement
 );
+// client is now a PlaygroundClient instance
 await client.isReady();
 await client.goTo('/wp-admin/');
 
-const result = await client.run({
+const response = await client.run({
 	code: '<?php echo "Hi!"; ',
 });
-console.log(new TextDecoder().decode(result.body));
+console.log(response.text);
 ```
+
+Using TypeScript is highly recommended as this package ships with comprehensive types – hit ctrl+space in your IDE after `client.` and you'll see all the available methods.
+
+Once you have a [PlaygroundClient](https://wordpress.github.io/wordpress-playground/interfaces/_wp_playground_client.PlaygroundClient.html) instance, you can use it to control the playground:
+
+```ts
+client.writeFile('/index.php', '<?php echo "Hi!"; ');
+client.run({
+	scriptPath: '/index.php',
+});
+
+console.log(client.readFileAsText('/index.php'));
+
+client.request({
+	url: '/index.php',
+	method: 'POST',
+	formData: {
+		foo: 'bar',
+	},
+});
+```
+
+To see all the available methods, check out the [PlaygroundClient](https://wordpress.github.io/wordpress-playground/interfaces/_wp_playground_client.PlaygroundClient.html) interface.
+
+## Helpers
+
+The `@wp-playground/client` package also provides a few helpers:
+
+-   [login](https://wordpress.github.io/wordpress-playground/functions/_wp_playground_client.login.html) - Logs the user in to wp-admin.
+-   [installPlugin](https://wordpress.github.io/wordpress-playground/functions/_wp_playground_client.installPlugin.html) - Installs a plugin from a given zip file.
+-   [installPluginsFromDirectory](https://wordpress.github.io/wordpress-playground/functions/_wp_playground_client.installPluginsFromDirectory.html) - Downloads and installs one or more plugins from the WordPress Plugin Directory.
+-   [activatePlugin](https://wordpress.github.io/wordpress-playground/functions/_wp_playground_client.activatePlugin.html) - Activates a specific plugin.
+-   [installTheme](https://wordpress.github.io/wordpress-playground/functions/_wp_playground_client.installTheme.html) - Installs a theme from a given zip file.
+-   [installThemeFromDirectory](https://wordpress.github.io/wordpress-playground/functions/_wp_playground_client.installThemeFromDirectory.html) - Downloads and installs a theme with a specific name from the WordPress Theme Directory.

package/index.d.ts

@@ -1,5 +1,151 @@
 // Generated by dts-bundle-generator v7.2.0
 
+/**
+ * PHP response. Body is an `ArrayBuffer` because it can
+ * contain binary data.
+ */
+export declare class PHPResponse {
+	/**
+	 * Response headers.
+	 */
+	readonly headers: Record<string, string[]>;
+	/**
+	 * Response body. Contains the output from `echo`,
+	 * `print`, inline HTML etc.
+	 */
+	private readonly body;
+	/**
+	 * Stderr contents, if any.
+	 */
+	readonly errors: string;
+	/**
+	 * The exit code of the script. `0` is a success, while
+	 * `1` and `2` indicate an error.
+	 */
+	readonly exitCode: number;
+	/**
+	 * Response HTTP status code, e.g. 200.
+	 */
+	readonly httpStatusCode: number;
+	constructor(httpStatusCode: number, headers: Record<string, string[]>, body: ArrayBuffer, errors?: string, exitCode?: number);
+	/**
+	 * Response body as JSON.
+	 */
+	get json(): any;
+	/**
+	 * Response body as text.
+	 */
+	get text(): string;
+	/**
+	 * Response body as bytes.
+	 */
+	get bytes(): ArrayBuffer;
+}
+export type PHPRequest = Pick<PHPRunOptions, "method" | "headers"> & {
+	url: string;
+	files?: Record<string, File>;
+} & ((Pick<PHPRunOptions, "body"> & {
+	formData?: never;
+}) | {
+	body?: never;
+	formData: Record<string, unknown>;
+});
+export interface PHPRequestHandlerConfiguration {
+	/**
+	 * The directory in the PHP filesystem where the server will look
+	 * for the files to serve. Default: `/var/www`.
+	 */
+	documentRoot?: string;
+	/**
+	 * Request Handler URL. Used to populate $_SERVER details like HTTP_HOST.
+	 */
+	absoluteUrl?: string;
+	/**
+	 * Callback used by the PHPRequestHandler to decide whether
+	 * the requested path refers to a PHP file or a static file.
+	 */
+	isStaticFilePath?: (path: string) => boolean;
+}
+declare class PHPRequestHandler {
+	#private;
+	/**
+	 * The PHP instance
+	 */
+	php: BasePHP;
+	/**
+	 * @param  php    - The PHP instance.
+	 * @param  config - Request Handler configuration.
+	 */
+	constructor(php: BasePHP, config?: PHPRequestHandlerConfiguration);
+	/**
+	 * Converts a path to an absolute URL based at the PHPRequestHandler
+	 * root.
+	 *
+	 * @param  path The server path to convert to an absolute URL.
+	 * @returns The absolute URL.
+	 */
+	pathToInternalUrl(path: string): string;
+	/**
+	 * Converts an absolute URL based at the PHPRequestHandler to a relative path
+	 * without the server pathname and scope.
+	 *
+	 * @param  internalUrl An absolute URL based at the PHPRequestHandler root.
+	 * @returns The relative path.
+	 */
+	internalUrlToPath(internalUrl: string): string;
+	get isRequestRunning(): boolean;
+	/**
+	 * The absolute URL of this PHPRequestHandler instance.
+	 */
+	get absoluteUrl(): string;
+	/**
+	 * The absolute URL of this PHPRequestHandler instance.
+	 */
+	get documentRoot(): string;
+	/**
+	 * Serves the request – either by serving a static file, or by
+	 * dispatching it to the PHP runtime.
+	 *
+	 * @param  request - The request.
+	 * @returns The response.
+	 */
+	request(request: PHPRequest): Promise<PHPResponse>;
+}
+export interface PHPBrowserConfiguration {
+	/**
+	 * Should handle redirects internally?
+	 */
+	handleRedirects?: boolean;
+	/**
+	 * The maximum number of redirects to follow internally. Once
+	 * exceeded, request() will return the redirecting response.
+	 */
+	maxRedirects?: number;
+}
+declare class PHPBrowser implements WithRequestHandler {
+	#private;
+	server: PHPRequestHandler;
+	/**
+	 * @param  server - The PHP server to browse.
+	 * @param  config - The browser configuration.
+	 */
+	constructor(server: PHPRequestHandler, config?: PHPBrowserConfiguration);
+	/**
+	 * Sends the request to the server.
+	 *
+	 * When cookies are present in the response, this method stores
+	 * them and sends them with any subsequent requests.
+	 *
+	 * When a redirection is present in the response, this method
+	 * follows it by discarding a response and sending a subsequent
+	 * request.
+	 *
+	 * @param  request   - The request.
+	 * @param  redirects - Internal. The number of redirects handled so far.
+	 * @returns PHPRequestHandler response.
+	 */
+	request(request: PHPRequest, redirects?: number): Promise<PHPResponse>;
+}
 export type PHPRequestHeaders = Record<string, string>;
 export interface FileInfo {
 	key: string;
@@ -7,7 +153,7 @@ export interface FileInfo {
 	type: string;
 	data: Uint8Array;
 }
-export interface PHPRequest {
+export interface PHPRunOptions {
 	/**
 	 * Request path following the domain:port part.
 	 */
@@ -41,30 +187,6 @@ export interface PHPRequest {
 	 */
 	code?: string;
 }
-export interface PHPResponse {
-	/**
-	 * The exit code of the script. `0` is a success, while
-	 * `1` and `2` indicate an error.
-	 */
-	exitCode: number;
-	/**
-	 * Response body. Contains the output from `echo`,
-	 * `print`, inline HTML etc.
-	 */
-	body: ArrayBuffer;
-	/**
-	 * PHP errors.
-	 */
-	errors: string;
-	/**
-	 * Response headers.
-	 */
-	headers: Record<string, string[]>;
-	/**
-	 * Response HTTP status code, e.g. 200.
-	 */
-	httpStatusCode: number;
-}
 export type PHPRuntimeId = number;
 export interface WithPHPIniBindings {
 	setPhpIniPath(path: string): void;
@@ -153,21 +275,30 @@ export interface WithFilesystem {
 	 * @returns True if the file exists, false otherwise.
 	 */
 	fileExists(path: string): boolean;
+	/**
+	 * Changes the current working directory in the PHP filesystem.
+	 * This is the directory that will be used as the base for relative paths.
+	 * For example, if the current working directory is `/root/php`, and the
+	 * path is `data`, the absolute path will be `/root/php/data`.
+	 *
+	 * @param  path - The new working directory.
+	 */
+	chdir(path: string): void;
 }
 export interface WithRun {
 	/**
-	 * Dispatches a PHP request.
+	 * Runs PHP code.
 	 * Cannot be used in conjunction with `cli()`.
 	 *
 	 * @example
 	 * ```js
-	 * const output = php.run('<?php echo "Hello world!";');
+	 * const output = await php.run('<?php echo "Hello world!";');
 	 * console.log(output.stdout); // "Hello world!"
 	 * ```
 	 *
 	 * @example
 	 * ```js
-	 * console.log(php.run(`<?php
+	 * console.log(await php.run(`<?php
 	 *  $fp = fopen('php://stderr', 'w');
 	 *  fwrite($fp, "Hello, world!");
 	 * `));
@@ -176,33 +307,80 @@ export interface WithRun {
 	 *
 	 * @param  request - PHP Request data.
 	 */
-	run(request?: PHPRequest): PHPResponse;
+	run(request?: PHPRunOptions): Promise<PHPResponse>;
+}
+export interface WithRequestHandler {
+	/**
+	 * Dispatches a HTTP request using PHP as a backend.
+	 * Cannot be used in conjunction with `cli()`.
+	 *
+	 * @example
+	 * ```js
+	 * const output = await php.request({
+	 * 	method: 'GET',
+	 * 	url: '/index.php',
+	 * 	headers: {
+	 * 		'X-foo': 'bar',
+	 * 	},
+	 * 	formData: {
+	 * 		foo: 'bar',
+	 * 	},
+	 * });
+	 * console.log(output.stdout); // "Hello world!"
+	 * ```
+	 *
+	 * @param  request - PHP Request data.
+	 */
+	request(request?: PHPRequest): Promise<PHPResponse>;
 }
+export type PHPRuntime = any;
+export type DataModule = {
+	dependencyFilename: string;
+	dependenciesTotalSize: number;
+	default: (phpRuntime: PHPRuntime) => void;
+};
+export type EmscriptenOptions = {
+	onAbort?: (message: string) => void;
+	ENV?: Record<string, string>;
+	locateFile?: (path: string) => string;
+	noInitialRun?: boolean;
+	dataFileDownloads?: Record<string, number>;
+	print?: (message: string) => void;
+	printErr?: (message: string) => void;
+	onRuntimeInitialized?: () => void;
+	monitorRunDependencies?: (left: number) => void;
+} & Record<string, any>;
 export type MountSettings = {
 	root: string;
-	mountpoint?: string;
 };
-declare class PHP implements WithPHPIniBindings, WithFilesystem, WithNodeFilesystem, WithCLI, WithRun {
+declare abstract class BasePHP implements WithPHPIniBindings, WithFilesystem, WithNodeFilesystem, WithCLI, WithRequestHandler, WithRun {
 	#private;
+	requestHandler?: PHPBrowser;
 	/**
 	 * Initializes a PHP runtime.
 	 *
 	 * @internal
 	 * @param  PHPRuntime - Optional. PHP Runtime ID as initialized by loadPHPRuntime.
+	 * @param  serverOptions - Optional. Options for the PHPRequestHandler. If undefined, no request handler will be initialized.
 	 */
-	constructor(PHPRuntimeId?: PHPRuntimeId);
+	constructor(PHPRuntimeId?: PHPRuntimeId, serverOptions?: PHPRequestHandlerConfiguration);
 	initializeRuntime(runtimeId: PHPRuntimeId): void;
 	/** @inheritDoc */
 	setPhpIniPath(path: string): void;
 	/** @inheritDoc */
 	setPhpIniEntry(key: string, value: string): void;
+	/** @inheritDoc */
 	chdir(path: string): void;
 	/** @inheritDoc */
-	run(request?: PHPRequest): PHPResponse;
+	request(request: PHPRequest, maxRedirects?: number): Promise<PHPResponse>;
+	/** @inheritDoc */
+	run(request?: PHPRunOptions): Promise<PHPResponse>;
 	cli(argv: string[]): Promise<number>;
 	setSkipShebang(shouldSkip: boolean): void;
 	addServerGlobalEntry(key: string, value: string): void;
+	/** @inheritDoc */
 	mkdirTree(path: string): void;
+	/** @inheritDoc */
 	readFileAsText(path: string): string;
 	/** @inheritDoc */
 	readFileAsBuffer(path: string): Uint8Array;
@@ -212,122 +390,25 @@ declare class PHP implements WithPHPIniBindings, WithFilesystem, WithNodeFilesys
 	unlink(path: string): void;
 	/** @inheritDoc */
 	listFiles(path: string): string[];
+	/** @inheritDoc */
 	isDir(path: string): boolean;
+	/** @inheritDoc */
 	fileExists(path: string): boolean;
+	/** @inheritDoc */
 	mount(settings: MountSettings, path: string): void;
 }
-export type PHPServerRequest = Pick<PHPRequest, "method" | "headers"> & {
-	files?: Record<string, File>;
-} & ({
-	absoluteUrl: string;
-	relativeUrl?: never;
-} | {
-	absoluteUrl?: never;
-	relativeUrl: string;
-}) & ((Pick<PHPRequest, "body"> & {
-	formData?: never;
-}) | {
-	body?: never;
-	formData: Record<string, unknown>;
-});
-declare class PHPServer {
-	#private;
-	/**
-	 * The PHP instance
-	 */
-	php: PHP;
-	/**
-	 * @param  php    - The PHP instance.
-	 * @param  config - Server configuration.
-	 */
-	constructor(php: PHP, config?: PHPServerConfigation);
-	/**
-	 * Converts a path to an absolute URL based at the PHPServer
-	 * root.
-	 *
-	 * @param  path The server path to convert to an absolute URL.
-	 * @returns The absolute URL.
-	 */
-	pathToInternalUrl(path: string): string;
-	/**
-	 * Converts an absolute URL based at the PHPServer to a relative path
-	 * without the server pathname and scope.
-	 *
-	 * @param  internalUrl An absolute URL based at the PHPServer root.
-	 * @returns The relative path.
-	 */
-	internalUrlToPath(internalUrl: string): string;
-	/**
-	 * The absolute URL of this PHPServer instance.
-	 */
-	get absoluteUrl(): string;
-	/**
-	 * The absolute URL of this PHPServer instance.
-	 */
-	get documentRoot(): string;
-	/**
-	 * Serves the request – either by serving a static file, or by
-	 * dispatching it to the PHP runtime.
-	 *
-	 * @param  request - The request.
-	 * @returns The response.
-	 */
-	request(request: PHPServerRequest): Promise<PHPResponse>;
-}
-export interface PHPServerConfigation {
-	/**
-	 * The directory in the PHP filesystem where the server will look
-	 * for the files to serve. Default: `/var/www`.
-	 */
-	documentRoot?: string;
-	/**
-	 * Server URL. Used to populate $_SERVER details like HTTP_HOST.
-	 */
-	absoluteUrl?: string;
-	/**
-	 * Callback used by the PHPServer to decide whether
-	 * the requested path refers to a PHP file or a static file.
-	 */
-	isStaticFilePath?: (path: string) => boolean;
-}
-export interface WithRequest {
-	/**
-	 * Sends the request to the server.
-	 *
-	 * When cookies are present in the response, this method stores
-	 * them and sends them with any subsequent requests.
-	 *
-	 * When a redirection is present in the response, this method
-	 * follows it by discarding a response and sending a subsequent
-	 * request.
-	 *
-	 * @param  request   - The request.
-	 * @param  redirects - Internal. The number of redirects handled so far.
-	 * @returns PHPServer response.
-	 */
-	request(request: PHPServerRequest, redirects?: number): Promise<PHPResponse>;
-}
-declare class PHPBrowser implements WithRequest {
-	#private;
-	server: PHPServer;
-	/**
-	 * @param  server - The PHP server to browse.
-	 * @param  config - The browser configuration.
-	 */
-	constructor(server: PHPServer, config?: PHPBrowserConfiguration);
-	request(request: PHPServerRequest, redirects?: number): Promise<PHPResponse>;
-}
-export interface PHPBrowserConfiguration {
-	/**
-	 * Should handle redirects internally?
-	 */
-	handleRedirects?: boolean;
-	/**
-	 * The maximum number of redirects to follow internally. Once
-	 * exceeded, request() will return the redirecting response.
-	 */
-	maxRedirects?: number;
-}
+declare const SupportedPHPVersions: readonly [
+	"8.2",
+	"8.1",
+	"8.0",
+	"7.4",
+	"7.3",
+	"7.2",
+	"7.1",
+	"7.0",
+	"5.6"
+];
+export type SupportedPHPVersion = (typeof SupportedPHPVersions)[number];
 export type PublicAPI<Methods, PipedAPI = unknown> = Methods & PipedAPI & {
 	isReady: () => Promise<void>;
 };
@@ -338,7 +419,7 @@ export interface MonitoredModule {
 declare class EmscriptenDownloadMonitor extends EventTarget {
 	#private;
 	constructor(modules?: MonitoredModule[]);
-	getEmscriptenArgs(): {
+	getEmscriptenOptions(): {
 		dataFileDownloads: Record<string, any>;
 	};
 	setModules(modules: MonitoredModule[]): void;
@@ -374,6 +455,40 @@ declare class ProgressObserver extends EventTarget {
 	slowlyIncrementBy(progress: number): void;
 	get totalProgress(): number;
 }
+export interface PHPWebLoaderOptions {
+	emscriptenOptions?: EmscriptenOptions;
+	downloadMonitor?: EmscriptenDownloadMonitor;
+	requestHandler?: PHPRequestHandlerConfiguration;
+	dataModules?: Array<DataModule | Promise<DataModule>>;
+}
+declare class PHP extends BasePHP {
+	/**
+	 * Creates a new PHP instance.
+	 *
+	 * Dynamically imports the PHP module, initializes the runtime,
+	 * and sets up networking. It's a shorthand for the lower-level
+	 * functions like `getPHPLoaderModule`, `loadPHPRuntime`, and
+	 * `PHP.initializeRuntime`
+	 *
+	 * @param phpVersion The PHP Version to load
+	 * @param options The options to use when loading PHP
+	 * @returns A new PHP instance
+	 */
+	static load(phpVersion: SupportedPHPVersion, options?: PHPWebLoaderOptions): Promise<PHP>;
+	/**
+	 * Does what load() does, but synchronously returns
+	 * an object with the PHP instance and a promise that
+	 * resolves when the PHP instance is ready.
+	 *
+	 * @see load
+	 * @inheritdoc load
+	 */
+	static loadSync(phpVersion: SupportedPHPVersion, options?: PHPWebLoaderOptions): {
+		php: PHP;
+		phpReady: Promise<PHP>;
+		dataModules: Promise<DataModule[]>;
+	};
+}
 /** @inheritdoc T */
 export type Promisify<T> = {
 	[P in keyof T]: T[P] extends (...args: infer A) => infer R ? R extends void | Promise<any> ? T[P] : (...args: A) => Promise<ReturnType<T[P]>> : Promise<T[P]>;
@@ -385,22 +500,24 @@ export interface WithPathConversion {
 export interface WithProgress {
 	onDownloadProgress(callback: (progress: CustomEvent<ProgressEvent>) => void): Promise<void>;
 }
-declare class PHPClient implements Promisify<WithRequest & WithPHPIniBindings & WithFilesystem & WithRun & WithProgress & WithPathConversion> {
-	/** @inheritDoc @php-wasm/web!PHPServer.absoluteUrl */
+declare class PHPClient implements Promisify<WithPHPIniBindings & WithFilesystem & WithRun & WithRequestHandler & WithProgress & WithPathConversion> {
+	/** @inheritDoc @php-wasm/web!PHPRequestHandler.absoluteUrl */
 	absoluteUrl: Promise<string>;
-	/** @inheritDoc @php-wasm/web!PHPServer.documentRoot */
+	/** @inheritDoc @php-wasm/web!PHPRequestHandler.documentRoot */
 	documentRoot: Promise<string>;
 	/** @inheritDoc */
-	constructor(browser: PHPBrowser, monitor?: EmscriptenDownloadMonitor);
-	/** @inheritDoc @php-wasm/web!PHPServer.pathToInternalUrl */
+	constructor(php: BasePHP, monitor?: EmscriptenDownloadMonitor);
+	/** @inheritDoc @php-wasm/web!PHPRequestHandler.pathToInternalUrl */
 	pathToInternalUrl(path: string): Promise<string>;
-	/** @inheritDoc @php-wasm/web!PHPServer.internalUrlToPath */
+	/** @inheritDoc @php-wasm/web!PHPRequestHandler.internalUrlToPath */
 	internalUrlToPath(internalUrl: string): Promise<string>;
 	onDownloadProgress(callback: (progress: CustomEvent<ProgressEvent>) => void): Promise<void>;
-	/** @inheritDoc @php-wasm/web!PHPServer.request */
-	request(request: PHPServerRequest, redirects?: number): Promise<PHPResponse>;
+	/** @inheritDoc @php-wasm/web!PHPRequestHandler.request */
+	request(request: PHPRequest, redirects?: number): Promise<PHPResponse>;
 	/** @inheritDoc @php-wasm/web!PHP.run */
-	run(request?: PHPRequest | undefined): Promise<PHPResponse>;
+	run(request?: PHPRunOptions): Promise<PHPResponse>;
+	/** @inheritDoc @php-wasm/web!PHP.chdir */
+	chdir(path: string): void;
 	/** @inheritDoc @php-wasm/web!PHP.setPhpIniPath */
 	setPhpIniPath(path: string): void;
 	/** @inheritDoc @php-wasm/web!PHP.setPhpIniEntry */
@@ -426,7 +543,7 @@ declare class PlaygroundWorkerClientClass extends PHPClient {
 	scope: Promise<string>;
 	wordPressVersion: Promise<string>;
 	phpVersion: Promise<string>;
-	constructor(browser: PHPBrowser, monitor: EmscriptenDownloadMonitor, scope: string, wordPressVersion: string, phpVersion: string);
+	constructor(php: PHP, monitor: EmscriptenDownloadMonitor, scope: string, wordPressVersion: string, phpVersion: string);
 	getWordPressModuleDetails(): Promise<{
 		staticAssetsDirectory: string;
 		defaultTheme: any;
@@ -449,12 +566,96 @@ export interface PlaygroundClient extends WebClientMixin, PlaygroundWorkerClient
 }
 export declare function exportFile(playground: PlaygroundClient): Promise<void>;
 export declare function importFile(playground: PlaygroundClient, file: File): Promise<boolean>;
+/**
+ * Logs in to the Playground.
+ * Under the hood, this function submits the wp-login.php form
+ * just like a user would.
+ *
+ * @param playground The playground client.
+ * @param user The user to log in as. Defaults to 'admin'.
+ * @param password The password to log in with. Defaults to 'password'.
+ */
 export declare function login(playground: PlaygroundClient, user?: string, password?: string): Promise<void>;
-export declare function installTheme(playground: PlaygroundClient, themeZipFile: File, options?: any): Promise<void>;
-export declare function installPlugin(playground: PlaygroundClient, pluginZipFile: File, options?: any): Promise<void>;
+export interface InstallThemeOptions {
+	/**
+	 * Whether to activate the theme after installing it.
+	 */
+	activate?: boolean;
+}
+/**
+ * Installs a WordPress theme in the Playground.
+ * Technically, it uses the same theme upload form as a WordPress user
+ * would, and then activates the theme if needed.
+ *
+ * @param playground The playground client.
+ * @param themeZipFile The theme zip file.
+ * @param options Optional. Set `activate` to false if you don't want to activate the theme.
+ */
+export declare function installTheme(playground: PlaygroundClient, themeZipFile: File, options?: InstallThemeOptions): Promise<void>;
+export interface InstallPluginOptions {
+	/**
+	 * Whether to activate the plugin after installing it.
+	 */
+	activate?: boolean;
+}
+/**
+ * Installs a WordPress plugin in the Playground.
+ * Technically, it uses the same plugin upload form as a WordPress user
+ * would, and then activates the plugin if needed.
+ *
+ * @param playground The playground client.
+ * @param pluginZipFile The plugin zip file.
+ * @param options Optional. Set `activate` to false if you don't want to activate the plugin.
+ */
+export declare function installPlugin(playground: PlaygroundClient, pluginZipFile: File, options?: InstallPluginOptions): Promise<void>;
+/**
+ * Activates a WordPress plugin in the Playground.
+ *
+ * @param playground The playground client.
+ * @param plugin The plugin slug.
+ */
 export declare function activatePlugin(playground: PlaygroundClient, plugin: string): Promise<void>;
+/**
+ * Downloads and installs a theme from the WordPress.org theme directory.
+ * Under the hood, it downloads the themes through a proxy endpoint
+ * and installs then one after another using the installTheme function.
+ *
+ * @see installPlugin
+ * @param playground The playground client.
+ * @param themeZipName The theme zip file name. For example, set this parameter
+ *                     to "twentytwentythree.1.1.zip" to download the Twenty Twenty Three theme
+ *                     from https://downloads.wordpress.org/theme/twentytwentythree.1.1.zip.
+ *
+ * @param maxProgress Optional. The maximum progress value to use. Defaults to 100.
+ * @param progress Optional. The progress observer that will be notified of the progress.
+ */
 export declare function installThemeFromDirectory(playground: PlaygroundClient, themeZipName: string, progressBudget?: number, progress?: ProgressObserver): Promise<void>;
-export declare function installPluginsFromDirectory(playground: PlaygroundClient, pluginsZipNames: string[], progressBudget?: number, progress?: ProgressObserver): Promise<void>;
-export declare function connectPlayground(iframe: HTMLIFrameElement, playgroundUrl: string): Promise<PlaygroundClient>;
+/**
+ * Downloads and installs multiple plugins from the WordPress.org plugin directory.
+ * Under the hood, it downloads the plugins through a proxy endpoint
+ * and installs then one after another using the installPlugin function.
+ *
+ * @see installPlugin
+ * @param playground The playground client.
+ * @param pluginsZipNames The plugin zip file names. For example, set this parameter
+ *                        to ["gutenberg.15.5.0.zip"] to download the Gutenberg plugin
+ *                        from https://downloads.wordpress.org/plugin/gutenberg.15.5.0.zip.
+ * @param maxProgress Optional. The maximum progress value to use. Defaults to 100.
+ * @param progress Optional. The progress observer that will be notified of the progress.
+ */
+export declare function installPluginsFromDirectory(playground: PlaygroundClient, pluginsZipNames: string[], maxProgress?: number, progress?: ProgressObserver): Promise<void>;
+export interface ConnectPlaygroundOptions {
+	loadRemote?: string;
+}
+/**
+ * Connects to a playground iframe and returns a PlaygroundClient instance.
+ *
+ * @param iframe Any iframe with Playground's remote.html loaded.
+ * @param options Optional. If `loadRemote` is set, the iframe's `src` will be set to that URL.
+ *                In other words, use this option if your iframe doesn't have remote.html already
+ * 				  loaded.
+ * @returns A PlaygroundClient instance.
+ */
+export declare function connectPlayground(iframe: HTMLIFrameElement, options?: ConnectPlaygroundOptions): Promise<PlaygroundClient>;
 
 export {};