Use WordPress runner for Figma imports

Author: chubes4

docs/figma-playground-runner.md

@@ -1,19 +1,19 @@
 # Figma to WordPress
 
-`plugins/figma-to-wordpress` moves a Figma file into WordPress. Internally it generates a static HTML/CSS website artifact, then hands that artifact to a WordPress Playground runner that imports it with Static Site Importer and Blocks Engine.
+`plugins/figma-to-wordpress` moves a Figma file into WordPress. It hands the design to a WordPress runner service that creates a Playground session and imports the result with Static Site Importer and Blocks Engine.
 
 ## Architecture
 
 ```text
 Figma plugin UI
-  -> GeneratedWebsiteArtifact
-  -> PlaygroundRunnerPayload
-  -> runner URL or generated runner page
-  -> WordPress Playground blueprint
+  -> Figma document scene data
+  -> runner request
+  -> WordPress runner service
+  -> WordPress Playground session URL
   -> Static Site Importer / Blocks Engine inside WordPress
 ```
 
-The TypeScript boundary stops at payload construction and Playground blueprint creation. WordPress, PHP, Static Site Importer, and Blocks Engine remain WordPress-side runtime concerns.
+The TypeScript boundary stops at request construction and opening the returned Playground URL. WordPress, PHP, Static Site Importer, Blocks Engine, and Playground session orchestration remain WordPress-side runtime concerns.
 
 ## Figma Iframe Limits
 
@@ -27,27 +27,25 @@ Practical constraints for this browser-based flow:
 - Clipboard access can require user activation.
 - Local file URLs can behave differently between desktop Figma, browser Figma, and development builds.
 
-Because of those constraints, the primary integration shape is a browser fallback: the plugin builds the same runner payload and opens or copies a runner URL. If in-plugin embedding works later, it can consume the same `PlaygroundRunnerPayload` interface.
+Because of those constraints, the primary integration shape is a service handoff: the plugin posts a runner request and opens the returned URL in a browser tab. If in-plugin embedding works later, it can consume the same runner response interface.
 
 ## Playground And PHP Role
 
 WordPress Playground is the correct place to run WordPress and PHP plugin logic. It provides a browser-hosted WordPress runtime backed by WebAssembly PHP and a virtual filesystem.
 
-Static Site Importer and Blocks Engine should run in that WordPress runtime because they are WordPress/PHP import systems. The Figma plugin should not reimplement them in TypeScript. The plugin's job is to hand off a generated static artifact with enough metadata for the Playground runner to install/activate/import with those plugins.
+Static Site Importer and Blocks Engine should run in that WordPress runtime because they are WordPress/PHP import systems. The Figma plugin should not reimplement them in TypeScript. The plugin's job is to hand off design data with enough metadata for the WordPress runner to transform, install, activate, and import with those plugins.
 
 ## Current Boundary
 
 Implemented now:
 
 - `GeneratedWebsiteArtifact` for static generated files from Figma.
-- `PlaygroundRunnerPayload` for the Playground handoff plan.
-- Runner URL construction with an encoded payload fragment.
-- A standalone runner HTML page that decodes and displays the payload.
-- A Playground URL builder that installs Static Site Importer from GitHub, writes the artifact JSON into `/tmp/figma-to-wordpress-artifact.json`, and runs the `static-site-importer/import-website-artifact` ability.
+- `figma-to-wordpress/runner-request/v1` for the runner handoff plan.
+- A Figma UI client that posts the runner request and opens the returned Playground URL.
 
 Not implemented yet:
 
-- Embedded Playground execution inside the Figma iframe.
+- The hosted WordPress runner endpoint that creates the Playground session.
 - Post-import block validation and visual parity checks.
 
 ## Local Testing
@@ -60,21 +58,14 @@ npm run build --prefix plugins/figma-to-wordpress
 npm test --prefix plugins/figma-to-wordpress
 ```
 
-Manual runner test:
-
-1. Build or otherwise serve `plugins/figma-to-wordpress/runner/playground-runner.html`.
-2. Use `buildRunnerPayload()` and `buildRunnerUrl()` from `src/payload.ts` to create a URL with `#payload=...`.
-3. Open the URL in a browser.
-4. Confirm the payload is decoded and the Playground link opens a session that installs Static Site Importer and runs the artifact import.
-
 Figma development test:
 
 1. Run `npm run build --prefix plugins/figma-to-wordpress`.
 2. Load `plugins/figma-to-wordpress/manifest.json` as a Figma development plugin.
 3. Run the plugin.
 4. Use `Open in WordPress Playground`.
-5. If the runner does not open from inside Figma, paste the copied URL into a normal browser tab.
+5. Confirm the runner service returns a Playground URL that opens in a normal browser tab.
 
 ## Next Integration Step
 
-The next meaningful step is a hosted runner page with richer progress/error reporting around the Playground import and post-import block/visual validation. That should remain in the WordPress/Playground runner layer, not by porting PHP importer behavior into the Figma plugin.
+The next meaningful step is a hosted WordPress runner endpoint with progress/error reporting around the Playground import and post-import block/visual validation. That should remain in the WordPress/Playground runner layer, not by porting PHP importer behavior into the Figma plugin.

plugins/figma-to-wordpress/README.md

@@ -1,29 +1,27 @@
 # Figma to WordPress
 
-This plugin moves a Figma file into WordPress by generating static HTML/CSS internally and importing that artifact with Static Site Importer and Blocks Engine in WordPress Playground.
+This plugin moves a Figma file into WordPress by handing the design to a WordPress runner service that imports it with Static Site Importer and Blocks Engine in WordPress Playground.
 
-It does not port Static Site Importer, Blocks Engine, WordPress, PHP, or Playground internals to TypeScript. The TypeScript code extracts Figma scene data, builds a static artifact, and creates a Playground blueprint that runs the WordPress/PHP import path.
+It does not port Static Site Importer, Blocks Engine, WordPress, PHP, or Playground internals to TypeScript. The TypeScript code extracts Figma scene data, prepares the runner request, and opens the Playground session URL returned by the WordPress-side runner.
 
 ## Flow
 
 ```text
 Figma plugin controller + UI
-  -> selected Figma scene
-  -> static HTML/CSS website artifact
-  -> runner payload
-  -> Playground blueprint URL
-  -> WordPress Playground boots WordPress/PHP in WASM
-  -> Static Site Importer installs and imports through Blocks Engine
+  -> whole Figma document scene data
+  -> runner request
+  -> WordPress runner service
+  -> WordPress Playground session
+  -> Static Site Importer imports through Blocks Engine
 ```
 
 ## Boundaries
 
 - Implemented: a Figma Desktop-loadable plugin shell with whole-file export.
-- Implemented: a reusable scene-to-HTML/CSS artifact generator with diagnostics and tests.
-- Implemented: a Playground blueprint URL that installs Static Site Importer from GitHub and calls `static-site-importer/import-website-artifact` with the generated artifact.
-- Implemented: a standalone runner page that decodes the payload and opens the same Playground import URL.
+- Implemented: a reusable scene-to-HTML/CSS artifact generator with diagnostics and tests for the current local handoff.
+- Implemented: a product-neutral runner request that can be posted to a WordPress-side Playground session service.
 - Not implemented: running Static Site Importer from TypeScript.
-- Not implemented: in-plugin embedded Playground validation; the reliable path opens Playground in a browser tab.
+- Not implemented: the hosted WordPress runner endpoint that creates the Playground session and returns its URL.
 - Not implemented: automated visual parity/block validation after import.
 
 ## Files
@@ -32,17 +30,16 @@ Figma plugin controller + UI
 - `src/code.ts` is the Figma plugin main thread entry.
 - `src/ui.ts` is the Figma UI-side handoff logic.
 - `src/index.ts` contains the reusable Figma-scene-to-website-artifact generator.
-- `src/payload.ts` contains the reusable TypeScript interfaces and Playground blueprint URL builders.
+- `src/payload.ts` contains the reusable TypeScript interfaces for the runner handoff.
+- `src/wordpress-runner.ts` posts the runner request and expects an `open_url` response.
 - `src/ui.html` is the Figma UI shell bundled into `dist/ui.html`.
-- `runner/playground-runner.html` is the browser fallback runner page.
 
 ## Local Test
 
 1. Run `npm run build --prefix plugins/figma-to-wordpress`.
 2. In Figma Desktop, use Plugins -> Development -> Import plugin from manifest, then select `plugins/figma-to-wordpress/manifest.json`.
 3. Open the plugin and choose `Open in WordPress Playground`.
-4. If Figma blocks embedding or navigation, copy the generated runner URL and open it in a normal browser tab.
-5. Confirm WordPress Playground boots, installs Static Site Importer, runs the import, and opens wp-admin.
+4. Confirm the WordPress runner service returns a Playground URL and the plugin opens it in a browser tab.
 
 For quick syntax verification without a full Figma build pipeline:
 
@@ -52,8 +49,8 @@ npm run build --prefix plugins/figma-to-wordpress
 npm test --prefix plugins/figma-to-wordpress
 ```
 
-## Figma Iframe Fallback
+## Runner Boundary
 
-Figma plugin UIs run in a constrained iframe-like environment. Cross-origin iframes, WASM boot, popup behavior, and navigation can be restricted depending on host context and plugin permissions. The supported fallback is to build the same payload, encode it into a runner URL fragment, and ask the user to open the runner page in a browser tab.
+Figma plugin UIs run in a constrained iframe-like environment. Cross-origin iframes, WASM boot, popup behavior, and navigation can be restricted depending on host context and plugin permissions. The supported boundary is a WordPress-side runner service: the plugin posts a runner request, the service creates the Playground session, and the plugin opens the returned URL.
 
 See [`../../docs/figma-playground-runner.md`](../../docs/figma-playground-runner.md) for the integration notes.