@wp-playground/client 3.1.21 → 3.1.25

package/README.md

@@ -1,9 +1,11 @@
 # Playground Client
 
-Provides a [PlaygroundClient](https://wordpress.github.io/wordpress-playground/api/client/) that can be used to control a WordPress Playground iframe:
+Provides a [PlaygroundClient](https://wordpress.github.io/wordpress-playground/api/client/) that can be used to control a WordPress Playground iframe.
 
-```ts
-import { startPlaygroundWeb } from '@wp-playground/client';
+In browser applications, consume the client over HTTP from the same Playground deployment that serves `remote.html`:
+
+```js
+import { startPlaygroundWeb } from 'https://playground.wordpress.net/client/index.js';
 
 const client = await startPlaygroundWeb({
 	// An iframe pointing to https://playground.wordpress.net/remote.html:
@@ -18,7 +20,25 @@ const response = await client.run({
 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.
+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.
+
+## 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.
+
+Prefer the direct `https://playground.wordpress.net/client/index.js` import for browser applications that use the hosted Playground runtime. An npm-installed client can drift from the `remote.html` it controls, and that may expose protocol mismatches between the parent page and iframe. If you use the npm package, make sure the client and remote runtime are versioned together.
+
+The npm package ships comprehensive types for the client API. In TypeScript, your editor can show the available methods after `client.`.
+
+## TypeScript declarations
+
+The published npm package ships one bundled declaration file, `index.d.ts`. That file is generated from `src/index.ts` and inlines the Playground and PHP-WASM types that are reachable from the public client API.
+
+This is intentional. `@wp-playground/client` exposes types such as Blueprints, PHP responses, mounts, and filesystem options that are implemented across several packages in this monorepo. Consumers should not need to install or resolve those internal workspace packages just to type-check code that imports `@wp-playground/client`.
+
+The build verifies this by checking that the published package contains a single declaration file and that `index.d.ts` does not import from other packages.
+
+Known limitation: The bundled declarations are not yet guaranteed to pass `skipLibCheck: false` in every TypeScript and DOM library combination. The rollup includes lower-level Playground APIs, and strict declaration checking may still surface environment-specific type issues such as Node `Buffer` references or `File.stream()` compatibility. These issues do not affect the usual `PlaygroundClient` API usage.
 
 Once you have a [PlaygroundClient](https://wordpress.github.io/wordpress-playground/api/client/) instance, you can use it to control the playground: