[Blueprints] Add Blueprint v2 web declarations

[adamziel]

What it does

Allows Blueprint v2 declarations to flow through the Playground website and @wp-playground/client web boot path.

When startPlaygroundWeb() receives a v2 declaration or v2 bundle, it now uses BlueprintsV2Handler. That handler compiles the declaration with compileBlueprintForExecution(), boots the remote iframe with the resolved runtime settings, and runs the compiled steps through the normal remote API.

Rationale

This is the first smaller PR from the broader consumer wiring work. It keeps the scope to the web/client v2 flow so it can be reviewed independently.

It does not enable the CLI v2 flow, change v1 Query API behavior, alter package build output, or remove remote worker endpoints.

Implementation

• Adds StartPlaygroundWebOptions so the web entrypoint can accept v1 or v2 Blueprints while preserving the existing v1-only StartPlaygroundOptions shape.
• Routes v2 declarations and bundles to BlueprintsV2Handler automatically.
• Keeps the iframe on blueprints-runner=v1; v2 compilation and execution happen in @wp-playground/client, while the iframe only needs the normal remote API.
• Widens website Blueprint pass-through types so v2 declarations from blueprint-url or hash fragments can reach the client path.
• Keeps URL query overrides applied only to v1 Blueprints.

Testing instructions

npx nx test playground-client --runInBand
npx nx typecheck playground-client
npx nx typecheck playground-website
npx nx lint playground-client
npx nx lint playground-website

Part of #2592.

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Wires the Blueprint v2 TypeScript compiler/runner into the website, client, remote iframe, and CLI flows while keeping legacy worker entrypoints stable and hardening ZIP extraction to prevent path traversal/symlink writes.

Changes:

• Replace v1/v2 split handlers with version-aware handlers (client + CLI) and route all remote boots through the standard worker.
• Extend website Query API overrides and error surfacing to handle Blueprint v2 declarations (including Gutenberg/core PR preview helpers).
• Harden ZIP extraction and expand built-package smoke tests for v2 exports and git-directory resources.

Reviewed changes

Copilot reviewed 51 out of 51 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
packages/playground/website/src/lib/tracking.ts	Updates Blueprint tracking logger to accept generic declarations.
packages/playground/website/src/lib/state/url/resolve-blueprint-from-url.ts	Adds v2-aware Query API overrides and helpers (plugins/themes/WXR/core PR/Gutenberg).
packages/playground/website/src/lib/state/url/resolve-blueprint-from-url.spec.ts	Adds unit tests for URL resolving + v2 Query API behaviors.
packages/playground/website/src/lib/state/redux/slice-sites.ts	Routes v2 blueprints through Query API overrides and updates error classification.
packages/playground/website/src/lib/state/redux/error-utils.ts	Adds cause-chain detection for v1/v2 blueprint validation errors.
packages/playground/website/src/lib/state/redux/boot-site-client.ts	Uses shared blueprint validation error detection and narrows v1-only WP opt-out check.
packages/playground/website/src/lib/state/opfs/opfs-site-storage.ts	Uses BlueprintReflection to persist original blueprint declarations.
packages/playground/website/src/lib/gutenberg-preview.ts	Adds marker constant to dedupe generated Gutenberg installer step.
packages/playground/website/public/test-fixtures/blueprint/v2_text_file.txt	Adds v2 bundled resource fixture.
packages/playground/website/public/test-fixtures/blueprint/blueprint-v2-with-bundled-resources.json	Adds v2 blueprint fixture referencing bundled resources.
packages/playground/website/playwright/e2e/blueprints.spec.ts	Adds Playwright smoke tests for website v2 boots + bundled resources.
packages/playground/test-built-npm-packages/run-tests.sh	Documents configurable per-PHP test timeout.
packages/playground/test-built-npm-packages/es-modules-and-vitest/tests/wp.spec.ts	Updates built-package smoke tests to cover v2 exports and adjust CLI boot parameters.
packages/playground/test-built-npm-packages/es-modules-and-vitest/tests/git-directory-resource.spec.ts	Adds isolated git:directory resource smoke test.
packages/playground/test-built-npm-packages/es-modules-and-vitest/run-tests.ts	Adds new test file and increases default timeout.
packages/playground/test-built-npm-packages/es-modules-and-vitest/package.json	Adds storage dependency for git chunk smoke test.
packages/playground/test-built-npm-packages/es-modules-and-vitest/bundler-tests/entry-web-static-imports.ts	Extends bundler smoke test to include storage git chunk availability.
packages/playground/test-built-npm-packages/commonjs-and-jest/tests/wp.spec.ts	Adds CommonJS smoke test for v2 compiler exports and increases timeouts.
packages/playground/test-built-npm-packages/commonjs-and-jest/package.json	Adds storage dependency for CommonJS bundler smoke path.
packages/playground/test-built-npm-packages/commonjs-and-jest/bundler-tests/entry-web-require.cjs	Extends require() smoke test to include storage git chunk availability.
packages/playground/remote/src/lib/playground-worker-endpoint.ts	Deprecates legacy remote v2 boot options and adds wordPressZip buffer boot option.
packages/playground/remote/src/lib/playground-worker-endpoint-blueprints-v2.ts	Removes dedicated remote v2 worker entrypoint.
packages/playground/remote/src/lib/playground-worker-endpoint-blueprints-v1.ts	Rejects legacy remote v2 options and supports caller-provided WP ZIP buffers.
packages/playground/remote/src/lib/playground-worker-endpoint-blueprints-v1.spec.ts	Adds tests for rejecting legacy v2 options and passing WP ZIP buffers.
packages/playground/remote/src/lib/boot-playground-remote.ts	Always uses the standard worker; warns on deprecated blueprints-runner=v2.
packages/playground/remote/README.md	Updates docs to describe standard worker usage for v1/v2.
packages/playground/common/src/index.ts	Hardens unzip and fixes zip entry naming when zipping directories.
packages/playground/client/src/index.ts	Routes all blueprints through a unified handler and standard remote worker.
packages/playground/client/src/index.spec.ts	Adds regression test asserting routing through shared handler.
packages/playground/client/src/blueprints-v2-handler.ts	Removes legacy v2-only browser handler.
packages/playground/client/src/blueprints-v1-handler.ts	Removes legacy v1-only browser handler (replaced by shared handler).
packages/playground/client/src/blueprints-handler.ts	Adds version-aware browser boot + compile+run flow for v1/v2.
packages/playground/client/src/blueprints-handler.spec.ts	Adds unit tests for shared browser handler behaviors.
packages/playground/client/README.md	Documents v2 declarations support in startPlaygroundWeb().
packages/playground/cli/tests/worker-thread-events.spec.ts	Removes v2 worker listener test and renames to “standard worker” semantics.
packages/playground/cli/tests/run-cli.spec.ts	Adds coverage for v2 routing, mode handling, ZIP extraction safety, and start behavior.
packages/playground/cli/tests/mounts.spec.ts	Ensures auto-mount does not override an explicitly provided mode.
packages/playground/cli/tests/blueprints-v2-handler.spec.ts	Adds unit tests for v2 handler overrides, modes, runtime boot, and validation.
packages/playground/cli/tests/blueprints-v1-handler.spec.ts	Adds unit tests for v1 handler respecting explicit CLI option origins.
packages/playground/cli/src/run-cli.ts	Introduces worker entrypoint aliases, v2 handler routing, richer CLI option origin tracking, and improved error formatting.
packages/playground/cli/src/resolve-blueprint.ts	Fixes ArrayBuffer slicing when reading .zip blueprints from Node buffers.
packages/playground/cli/src/mounts.ts	Prevents auto-mount from overriding an explicit --mode.
packages/playground/cli/src/cli-output.ts	Adjusts output formatting for config line wrapping.
packages/playground/cli/src/blueprints-v2/worker-thread-v2.ts	Replaces v2 worker with a compatibility shim importing the standard worker.
packages/playground/cli/src/blueprints-v2/blueprints-v2-handler.ts	Reworks v2 CLI handling to compile in TS and boot via standard worker APIs.
packages/playground/cli/src/blueprints-v1/worker-thread-v1.ts	Adds networking-controlled php.ini defaults and uses standard worker entrypoint.
packages/playground/cli/src/blueprints-v1/blueprints-v1-handler.ts	Applies CLI overrides only when flags were explicitly provided.
packages/playground/cli/README.md	Documents --mode and updates v1 schema example field name.
packages/playground/blueprints/src/lib/v2/compile.ts	Adds InvalidBlueprintV2Error, returns declaration, and supports progress option.
packages/playground/blueprints/src/index.ts	Exposes v2 compile/plan APIs and v2-specific error types publicly.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.