@wp-playground/remote 3.1.59 → 3.1.61

package/README.md

@@ -6,6 +6,19 @@ This library was generated with [Nx](https://nx.dev).
 
 Run `nx build playground-remote` to build the library.
 
+## Development
+
+`npm run dev` starts this package in the website's `wordpress-frame` Vite mode.
+The website proxies its trusted module requests from port 5400 to this server
+while keeping the app Host header. Direct browser requests to port 4400 can load
+only the WordPress HTTP helper and worker loaders. They cannot load the PHP/API
+documents or arbitrary source modules. The helper imports its code from the app
+port so it still knows which parent may send PHP responses.
+
+`nx dev playground-remote` remains a standalone same-origin server. Personal WP,
+sync, and non-loopback forwarded hosts also retain their previous routing.
+See the [website development guide](../website/README.md#development).
+
 ## Running unit tests
 
 Run `nx test playground-remote` to execute the unit tests via [Jest](https://jestjs.io).

package/lib/blueprints-worker.d.ts

@@ -0,0 +1,9 @@
+import type { EmscriptenDownloadMonitor } from '@php-wasm/progress';
+import { PlaygroundWorkerEndpoint, type WorkerBootOptions } from './playground-worker-endpoint';
+export declare class PlaygroundWorkerEndpointBlueprints extends PlaygroundWorkerEndpoint {
+    constructor(monitor: EmscriptenDownloadMonitor, privateReady: () => void, privateError: (error: Error) => void);
+    private ready;
+    private failed;
+    /** Boot PHP using the app document's origin choice, including when script bytes are cached. */
+    boot({ scope, useWordPressSandbox, mounts, wpVersion, wordPressZip, sqliteDriverVersion, phpVersion, sapiName, extensions, withNetworking, shouldInstallWordPress, wordpressInstallMode, blueprint, corsProxyUrl, pathAliases, }: WorkerBootOptions): Promise<void>;
+}

package/lib/boot-playground-remote.d.ts

@@ -3,4 +3,19 @@ export type { MountDescriptor, WorkerBootOptions };
 import type { WebClientMixin } from './playground-client';
 type PHPRemoteApi = WebClientMixin & Pick<PlaygroundWorkerEndpoint, 'cli'>;
 export declare const serviceWorkerUrl: URL;
+/**
+ * Start remote.html's PHP host and expose its client API to the embedding window.
+ *
+ * This document and the PHP worker stay on the app origin. PHP keeps access to
+ * the site's OPFS files or user-picked directory handles there. With a separate
+ * origin configured, the rendered WordPress iframe uses wordPressSiteUrl; this
+ * document and PHP do not move.
+ *
+ * The returned API's boot() method starts PHP and connects HTTP requests to it.
+ * With separate origins it creates a hidden WordPress-origin request iframe;
+ * with one origin a dedicated runtime uses the existing service-worker listener.
+ * Same-origin shared runtimes receive requests directly through MessagePorts.
+ * The WordPress request connection is separate from the full client API exposed
+ * to the embedding window: rendered WordPress does not receive that API here.
+ */
 export declare function bootPlaygroundRemote(): Promise<import("@php-wasm/universal").PublicAPI<PHPRemoteApi, import("@php-wasm/universal").RemoteAPI<PlaygroundWorkerEndpoint>>>;

package/lib/config.d.ts

@@ -1,2 +1,22 @@
+/**
+ * App origin, taken from the loaded module URL rather than the current document.
+ * The WordPress-origin helper also imports this code from the app host, so using
+ * location.origin there would incorrectly identify the WordPress host as the app.
+ */
+export declare const playgroundOrigin: string;
+/**
+ * Fixed sandbox origin available to ?reprint sessions. The flag selects this
+ * origin; its value must never supply a hostname. Normal sessions keep WordPress
+ * on the app origin. PHP, OPFS, and directory handles stay there in both modes.
+ * Loopback development offers the remote server's existing port; standalone and
+ * custom hosts without a configured sandbox keep one origin.
+ */
+export declare const wordPressSandboxOrigin: string;
+/**
+ * Select once for this document. remote.html sends its choice in PHP boot options.
+ * Helper and thumbnail documents already on the sandbox origin keep
+ * that origin even though ordinary WordPress URLs do not contain the flag.
+ * Service workers route by their own origin, never by a tab's startup flag.
+ */
 export declare const wordPressSiteUrl: string;
 export declare const DOCROOT = "/wordpress";

package/lib/connect-shared-runtime.d.ts

@@ -0,0 +1,15 @@
+import type { PlaygroundWorkerEndpoint, WorkerBootOptions } from './playground-worker-endpoint';
+export type SharedRuntimeAPI = PlaygroundWorkerEndpoint & {
+    shutdownSharedRuntime(): Promise<void>;
+    beginSharedBoot(options: WorkerBootOptions): Promise<boolean>;
+    finishSharedRuntimeInitialization(): Promise<void>;
+};
+/**
+ * Join this site's shared PHP worker, preserving remote.html's origin choice.
+ * Sandbox sessions use the HTTP helper, not a direct app-service-worker port.
+ */
+export declare function connectSharedRuntime(scope: string, version: string, clientVersion: string, onProgress?: (caption: string) => void): Promise<{
+    api: import("@php-wasm/web").RemoteAPI<SharedRuntimeAPI>;
+    register: (serviceWorker: ServiceWorker) => void;
+    isRetired: () => boolean;
+}>;

package/lib/connect-wordpress-origin.d.ts

@@ -0,0 +1,40 @@
+import type { RemoteAPI } from '@php-wasm/universal';
+import type { PlaygroundWorkerEndpoint } from './playground-worker-endpoint';
+/**
+ * Connect WordPress HTTP requests on a separate origin to this app-origin PHP worker.
+ *
+ * For example, remote.html on playground.wordpress.net runs PHP, but the visible
+ * WordPress iframe loads wp.playground.wordpress.net/scope:site-a/. The WordPress
+ * service worker cannot message remote.html directly: it can only reach windows
+ * on its own origin. This function creates a hidden WordPress-origin iframe as
+ * a sibling of the visible WordPress iframe. Requests take this path:
+ *
+ * WordPress page -> WordPress service worker -> hidden iframe
+ *   -> remote.html (this listener) -> the supplied PHP worker.
+ *
+ * Only messages from that exact hidden iframe, at the configured WordPress origin,
+ * with the supplied scope reach PHP. The HTTP URL must also use that origin and
+ * scope. The connection exposes two operations: HTTP requests and the directory
+ * name for shared WordPress assets. It does not forward the full PHP API, file
+ * handles, mount options, or requests for a different scope. Response status and
+ * headers return as message data; body chunks travel through a MessagePort.
+ *
+ * Call after PHP has booted. Resolves when the helper reports its service worker
+ * is ready, not when a WordPress page has loaded. On success, the hidden iframe
+ * and listener remain for the lifetime of remote.html. If no ready message arrives
+ * within 30 seconds, both are removed and the promise rejects.
+ *
+ * After connection, reject app-service-worker HTTP requests for this scope with
+ * 404. That worker also serves ordinary, same-origin sites. Returning this site's
+ * HTML there would let its scripts run on the app origin with app storage access.
+ * The rejection listener lasts with remote.html and survives worker restarts.
+ *
+ * The scope selects a PHP instance; it does not prove which WordPress page made
+ * the HTTP request. Pages sharing the WordPress origin can still request another
+ * running site's known scope. This connection also does not prevent WordPress
+ * from embedding a fresh app/API document and connecting to that separate API.
+ *
+ * @param client The already-booted PHP worker that will serve this site's requests.
+ * @param scope The site's URL routing scope, as supplied in its PHP boot options.
+ */
+export declare function connectWordPressOrigin(client: RemoteAPI<PlaygroundWorkerEndpoint>, scope: string): Promise<void>;

package/lib/dev-server.d.ts

@@ -1 +1,13 @@
+/** Local aliases shared by origin selection and the remote Vite host checks. */
+export declare const localDevelopmentHostnames: Set<string>;
+/**
+ * Map the normal website dev origin to the existing remote server's HTTP port.
+ *
+ * For example, http://127.0.0.1:5400 uses WordPress on :4400. Keep PHP and its
+ * handles on :5400; only rendered pages and their HTTP helper use the other port.
+ * Do not rewrite standalone remote, Personal WP, preview, HTTPS, or tunnel URLs:
+ * those servers have different routing or cannot expose the local remote port.
+ * Call only in development; production origins still come from the build setting.
+ */
+export declare function getWordPressDevelopmentOrigin(app: URL): string | undefined;
 export declare function isDevServer(url: URL): boolean;

package/lib/offline-mode-cache.d.ts

@@ -1,5 +1,7 @@
 export declare function cacheFirstFetch(request: Request): Promise<Response>;
 export declare function networkFirstFetch(request: Request): Promise<Response>;
+/** Fetch the directory index without serving upstream HTML or headers on the app origin. */
+export declare function fetchBlueprintsIndex(): Promise<Response>;
 /**
  * For offline mode to work we need to cache all required assets.
  *
@@ -7,7 +9,7 @@ export declare function networkFirstFetch(request: Request): Promise<Response>;
  * file and contain JavaScript, CSS, and other assets required to load the
  * site without making any network requests.
  */
-export declare function cacheOfflineModeAssetsForCurrentRelease(): Promise<any>;
+export declare function cacheOfflineModeAssetsForCurrentRelease(excludedAssets?: readonly string[]): Promise<any>;
 /**
  * Remove outdated files from the cache.
  *
@@ -25,5 +27,28 @@ export declare function purgeEverythingFromPreviousRelease(): Promise<boolean[]>
  */
 export declare function hasCachedResponse(url: string, queryOptions?: CacheQueryOptions): Promise<boolean>;
 export declare function putCachedResponse(request: RequestInfo, response: Response): Promise<void>;
+/**
+ * Decide whether this worker may use Playground's CacheStorage for a URL.
+ *
+ * Only the app-origin worker may use CacheStorage for shared platform downloads.
+ * WordPress code can open and change any cache on the WordPress origin, including
+ * Playground's cache. Giving the cache a special name does not protect it.
+ *
+ * For example, a plugin could store a fake response under the cache key
+ * https://playground.wordpress.net/wp-6.9/wordpress-static.zip. Without the origin
+ * guard, the archive shortcut below would allow the WordPress worker to reuse
+ * those attacker-written bytes as a WordPress download. The app hostname in the
+ * key does not protect the entry: the cache still belongs to the WordPress origin.
+ *
+ * Reject WordPress-origin CacheStorage before checking the requested URL. The app
+ * can still cache its own shared downloads, and WordPress-side fetches can use the
+ * browser HTTP cache. This rule does not disable HTTP caching or require a separate
+ * copy of every download for each Playground.
+ *
+ * On the app origin, the WordPress static-archive shortcut is checked first.
+ * For other URLs, exclude live scoped responses, PHP endpoints, and Vite
+ * development assets. The final origin check also rejects other ports, which
+ * may serve a live site's responses rather than reusable platform files.
+ */
 export declare function shouldCacheUrl(url: URL): boolean;
 export declare function isCurrentServiceWorkerActive(): boolean;

package/lib/playground-client.d.ts

@@ -92,6 +92,26 @@ export interface WebClientMixin extends ProgressReceiver {
      */
     unmountOpfs(mountpoint: string): Promise<void>;
     boot(options: WorkerBootOptions): Promise<void>;
+    /**
+     * Retires the shared runtime for all connected tabs. Stops accepting new work,
+     * drains active operations, flushes and unmounts OPFS, and disposes PHP before
+     * confirming shutdown. Rejects if retirement fails. Dedicated runtimes ignore this call.
+     */
+    shutdownSharedRuntime(): Promise<void>;
+    /**
+     * Whether this connection owns initial Blueprint execution. Always true for a
+     * dedicated runtime. Used by the client startup handlers, not application code.
+     * @internal
+     */
+    shouldRunStartupBlueprint(): Promise<boolean>;
+    /**
+     * Signals that the initializing connection has finished its startup Blueprint,
+     * allowing waiting tabs to attach. Only that connection may complete initialization.
+     * Used by the client startup handlers, including after Blueprint errors so recovery
+     * tools remain available. Dedicated runtimes ignore this call.
+     * @internal
+     */
+    finishSharedRuntimeInitialization(): Promise<void>;
 }
 export type SiteThumbnail = {
     /** The encoded image's MIME type. */

package/lib/playground-worker-endpoint.d.ts

@@ -13,6 +13,8 @@ export interface MountDescriptor {
     initialSyncDirection: 'opfs-to-memfs' | 'memfs-to-opfs';
 }
 export type WorkerBootOptions = {
+    /** remote.html selects this from its startup flag, not the cached worker URL. */
+    useWordPressSandbox?: boolean;
     wpVersion?: string;
     /** A caller-provided WordPress archive used instead of downloading one. */
     wordPressZip?: File;
@@ -71,7 +73,22 @@ export declare abstract class PlaygroundWorkerEndpoint extends PHPWorker {
     private emailParsingQueue;
     protected downloadMonitor: EmscriptenDownloadMonitor;
     constructor(monitor: EmscriptenDownloadMonitor);
-    protected computeSiteUrl(scope: string): string;
+    /** Use the boot message's choice so a cached script cannot select another tab's mode. */
+    protected computeSiteUrl(scope: string, useWordPressSandbox?: boolean): string;
+    /**
+     * Create the PHP runtime pool and route siteUrl requests into its WordPress files.
+     *
+     * siteUrl is WordPress's public scoped URL, even when PHP runs on the app origin.
+     * For each PHP instance, define PLAYGROUND_PARENT_ORIGIN in split-origin mode.
+     * The injected WordPress scripts use it to send navigation, pointer, thumbnail,
+     * and tool messages back to remote.html instead of assuming their parent shares
+     * WordPress's origin. The value comes from the app module URL, not user input.
+     *
+     * Known remote asset paths get a marked 404 when absent from the local files.
+     * The service worker uses that marker to fetch the shared public asset instead
+     * of treating every missing URL, including PHP routes, as a static download.
+     * Existing runtime hooks set up networking, mail capture, and shared files.
+     */
     protected createRequestHandler({ siteUrl, sapiName, corsProxyUrl, knownRemoteAssetPaths, extensions, withNetworking, phpVersion, pathAliases, onProgress, }: {
         siteUrl: string;
         sapiName: string;
@@ -83,6 +100,20 @@ export declare abstract class PlaygroundWorkerEndpoint extends PHPWorker {
         pathAliases?: PathAlias[];
         onProgress?: (caption: string) => void;
     }): Promise<PHPRequestHandler>;
+    /**
+     * Finish WordPress startup and identify static files omitted from minified builds.
+     *
+     * Enable outbound networking only after installation, then read the installed
+     * WordPress version. A saved site may contain a different version than requested;
+     * using the requested version could select the wrong public asset directory.
+     *
+     * Older saved sites may lack wordpress-remote-asset-paths. Fetch that list from
+     * the installed version's directory on the shared app origin and save it in the
+     * site's files. The WordPress host serves virtual site pages, not these platform
+     * downloads. Add the listed paths to the set used by createRequestHandler() to
+     * distinguish omitted static files from normal WordPress 404s. If recovery fails,
+     * log a warning and continue startup without the missing list.
+     */
     protected finalizeAfterBoot(requestHandler: any, withNetworking: boolean, knownRemoteAssetPaths: Set<string>): Promise<void>;
     protected getRequestHandler(required?: true): PHPRequestHandler;
     protected getRequestHandler(required: false): PHPRequestHandler | undefined;

package/lib/request-wordpress-url.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Ask the WordPress document for its live location, including changes from pushState().
+ * Such changes do not update iframe.src and may have happened since the last URL report.
+ *
+ * Send a new reply port only to the expected WordPress origin. Each call has its own
+ * port, so a late reply to an earlier request cannot satisfy this one. Return undefined
+ * if no reply arrives within 500ms or the request fails. The caller can then try reading
+ * location directly or use iframe.src. A timeout does not prove the page has no reporter.
+ */
+export declare function requestWordPressUrl(frame: HTMLIFrameElement, wordPressOrigin: string): Promise<string | undefined>;

package/lib/shared-playground-worker.d.ts

@@ -0,0 +1,2 @@
+/// <reference lib="webworker" />
+export {};

package/lib/shared-runtime-service-worker.d.ts

@@ -0,0 +1,8 @@
+/// <reference lib="webworker" />
+export declare function registerSharedRuntime(event: ExtendableMessageEvent): void;
+/** Restores a direct route after ServiceWorker eviction, contacting one remote document. */
+export declare function hasSharedRuntime(scope: string): Promise<boolean>;
+export declare function sendSharedRuntimeRequest(message: {
+    method: string;
+    args: any[];
+}, scope: string, requestClient?: Pick<FetchEvent, 'clientId' | 'resultingClientId'>): Promise<any>;

package/lib/shared-runtime.d.ts

@@ -0,0 +1,36 @@
+import type { PlaygroundWorkerEndpoint } from './playground-worker-endpoint';
+export declare const RELOAD_REQUIRED = "playground-reload-required";
+export declare const RUNTIME_CLOSED = "playground-runtime-closed";
+/** One runtime per site; connected documents never own its lifetime. */
+export declare class SharedRuntime {
+    private bootPromise?;
+    private initialized;
+    private initializer?;
+    private initializationComplete;
+    private resolveInitialization;
+    private rejectInitialization;
+    private active;
+    private retiring?;
+    private retired;
+    private closed;
+    private runtimeId;
+    private ports;
+    private servicePorts;
+    private readiness;
+    constructor(endpoint: PlaygroundWorkerEndpoint, version: string, onClose: () => void);
+    private endpoint;
+    private version;
+    private close;
+    connect(port: MessagePort, ready: () => void, failed: (error: Error) => void): void;
+    registerServicePort(port: MessagePort): void;
+    /** Serves HTTP once through a direct port and keeps retirement waiting for the body. */
+    handleServiceWorkerRequest(message: {
+        method: string;
+        args: any[];
+        requestId: number;
+    }, port: MessagePort): Promise<void>;
+    api(port?: MessagePort): PlaygroundWorkerEndpoint;
+    retire(): Promise<void>;
+    private beginBoot;
+    private run;
+}

package/lib/wordpress-bridge.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/wordpress-origin.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Select the configured sandbox for ?reprint; never take a hostname from its value.
+ *
+ * For example, app/remote.html?reprint selects the sandbox. A WordPress page
+ * already on that sandbox keeps it without putting ?reprint on every navigation.
+ * Other app documents use the app origin.
+ * The presence of the flag enables the sandbox, even for ?reprint=0.
+ */
+export declare function selectWordPressOrigin(context: URL, appOrigin: string, sandboxOrigin: string): string;

package/lib/wordpress-popup.d.ts

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@wp-playground/remote",
-	"version": "3.1.59",
+	"version": "3.1.61",
 	"description": "WordPress Playground remote host",
 	"repository": {
 		"type": "git",
@@ -25,5 +25,5 @@
 		"access": "public",
 		"directory": "../../../dist/packages/playground/remote"
 	},
-	"gitHead": "d5483ab9efa6dfedcf3610443eea12cfaba75f1c"
+	"gitHead": "1e779217fceedb5b29b1359a196dc97ce40f31de"
 }