Merge pull request #99 from Automattic/feat/figma-source-payload

Send Figma source payload to Studio

Author: chubes4

docs/figma-studio-runner.md

@@ -1,19 +1,19 @@
 # Figma to WordPress Studio
 
-`plugins/figma-to-wordpress-studio` moves a Figma file into WordPress by posting a Studio import source to the local WordPress Studio app. Studio creates the site and imports the result with Static Site Importer and Blocks Engine.
+`plugins/figma-to-wordpress-studio` moves a Figma file into WordPress by posting a Figma source payload to the local WordPress Studio app. Studio creates the site and imports the result with Static Site Importer and Blocks Engine.
 
 ## Architecture
 
 ```text
 Figma plugin UI
-  -> Figma document scene data
-  -> Studio import artifact JSON
+  -> current-page scenegraph + selected-node intent
+  -> Studio Figma source payload
   -> local WordPress Studio handoff endpoint
   -> WordPress Studio site
   -> Static Site Importer / Blocks Engine inside WordPress
 ```
 
-The TypeScript boundary stops at artifact construction and a local handoff request. WordPress, PHP, Static Site Importer, Blocks Engine, and Studio site orchestration remain Studio runtime concerns.
+The TypeScript boundary stops at source capture and a local handoff request. WordPress, PHP, Static Site Importer, Blocks Engine, and Studio site orchestration remain Studio runtime concerns.
 
 ## Figma Iframe Limits
 
@@ -27,11 +27,11 @@ 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 integration shape is a local Studio handoff: the plugin posts an artifact JSON source to Studio's loopback endpoint. If Studio is not running, the plugin surfaces the connection error.
+Because of those constraints, the integration shape is a local Studio handoff: the plugin posts Figma source data to Studio's loopback endpoint. If Studio is not running, the plugin surfaces the connection error.
 
 ## Studio And PHP Role
 
-WordPress Studio is the correct place to run WordPress and PHP plugin logic. It provides the WordPress runtime and accepts flexible `studio create --from <source>` inputs, including artifact JSON, `.fig`, file, directory, zip, and URL shapes.
+WordPress Studio is the correct place to run WordPress and PHP plugin logic. It provides the WordPress runtime and accepts flexible `studio create --from <source>` inputs, including Figma source, artifact JSON, `.fig`, file, directory, zip, and URL shapes.
 
 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 Studio to route through Static Site Importer and clean up importer dependencies after a successful import.
 
@@ -40,8 +40,9 @@ Static Site Importer and Blocks Engine should run in that WordPress runtime beca
 Implemented now:
 
 - `GeneratedWebsiteArtifact` for static generated files from Figma.
-- `blocks-engine/php-transformer/site-artifact/v1` for the Studio CLI artifact handoff.
-- A Figma UI client that posts the artifact JSON to local Studio.
+- `wordpress-studio/figma-source/v1` for the primary Studio Figma handoff.
+- `blocks-engine/php-transformer/site-artifact/v1` retained as debug/diagnostic context.
+- A Figma UI client that posts the source payload to local Studio.
 
 Not implemented yet:
 
@@ -68,4 +69,4 @@ Figma development test:
 
 ## Next Integration Step
 
-The next meaningful step is richer Studio-side progress/error reporting around CLI imports and post-import block/visual validation. That should remain in the Studio layer, not by porting PHP importer behavior into the Figma plugin.
+The next meaningful step is Studio-side routing for `wordpress-studio/figma-source/v1`, plus richer progress/error reporting around imports and post-import block/visual validation. That should remain in the Studio layer, not by porting PHP importer behavior into the Figma plugin.

plugins/figma-to-wordpress-studio/README.md

@@ -1,24 +1,24 @@
 # Figma to WordPress Studio
 
-This plugin moves a Figma file into WordPress by sending a Studio import payload to the local WordPress Studio app.
+This plugin moves a Figma file into WordPress by sending a Figma source payload to the local WordPress Studio app.
 
-It does not port Static Site Importer, Blocks Engine, WordPress, PHP, or Studio internals to TypeScript. The TypeScript code extracts Figma scene data, prepares an artifact JSON source, and posts it to Studio's local handoff endpoint. Studio owns site creation, import through Static Site Importer, and cleanup after a successful import. If Studio is not running, the plugin surfaces the connection error.
+It does not port Static Site Importer, Blocks Engine, WordPress, PHP, or Studio internals to TypeScript. The TypeScript code extracts Figma scene data, captures the user's page/frame selection intent, and posts that source payload to Studio's local handoff endpoint. Studio owns site creation, Figma-to-WordPress transform/import through Static Site Importer and Blocks Engine, and cleanup after a successful import. If Studio is not running, the plugin surfaces the connection error.
 
 ## Flow
 
 ```text
 Figma plugin controller + UI
-  -> whole Figma document scene data
-  -> Studio import artifact JSON
+  -> current-page scenegraph + selected-node intent
+  -> Studio Figma source payload
   -> local WordPress Studio handoff endpoint
   -> WordPress Studio site
   -> 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 for the current local handoff.
+- Implemented: a Figma Desktop-loadable plugin shell with current-page scenegraph and selected-frame intent export.
+- Implemented: a reusable scene-to-HTML/CSS artifact generator retained as debug/diagnostic context.
 - Implemented: a Studio local handoff request.
 - Not implemented: running Static Site Importer from TypeScript.
 - Not implemented: automated visual parity/block validation after import.
@@ -29,7 +29,7 @@ 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 for the Studio CLI artifact handoff.
+- `src/payload.ts` contains the reusable TypeScript interfaces for the Studio Figma source handoff and debug artifact bundle.
 - `src/ui.html` is the Figma UI shell bundled into `dist/ui.html`.
 
 ## Local Test
@@ -50,6 +50,58 @@ npm test --prefix plugins/figma-to-wordpress-studio
 
 ## Studio Handoff Boundary
 
-Figma plugin UIs run in a constrained iframe-like environment and cannot spawn local shell commands. The supported boundary is a local Studio handoff: the plugin posts the import artifact to Studio's loopback endpoint. Studio accepts the artifact source, creates the site, runs Static Site Importer, and removes SSI after a successful import.
+Figma plugin UIs run in a constrained iframe-like environment and cannot spawn local shell commands. The supported boundary is a local Studio handoff: the plugin posts a Figma source payload to Studio's loopback endpoint. Studio accepts the source, creates the site, runs the Figma import route through Static Site Importer and Blocks Engine, and removes importer dependencies after a successful import.
+
+The `Open in WordPress Studio` request body is source-first:
+
+```json
+{
+  "source": {
+    "schema": "wordpress-studio/figma-source/v1",
+    "source": {
+      "type": "figma",
+      "metadata": {
+        "provider": "figma",
+        "plugin": "figma-to-wordpress-studio",
+        "fileKey": "...",
+        "fileName": "Marketing site",
+        "editorType": "figma",
+        "currentPage": { "id": "0:1", "name": "Landing" }
+      },
+      "exportedAt": "2026-01-01T00:00:00.000Z"
+    },
+    "intent": {
+      "scope": "selected-nodes",
+      "pageId": "0:1",
+      "pageName": "Landing",
+      "selectedNodeIds": ["1:2"],
+      "rootNodeIds": ["1:2"]
+    },
+    "scenegraph": {
+      "currentPage": {},
+      "selectedNodes": []
+    },
+    "assets": [],
+    "transform": {
+      "target": "wordpress",
+      "route": "static-site-importer/figma",
+      "options": {
+        "selectionScope": "selected-nodes",
+        "pageId": "0:1",
+        "selectedNodeIds": ["1:2"],
+        "preserveSourceScenegraph": true,
+        "importAssets": true
+      }
+    },
+    "debug": {
+      "generatedArtifact": {},
+      "diagnostics": []
+    }
+  },
+  "siteName": "Marketing site"
+}
+```
+
+`debug.generatedArtifact` is diagnostic context only. Studio should route from `source`, `scenegraph`, and `transform`, not from a pre-rendered website artifact bundle.
 
 See [`../../docs/figma-studio-runner.md`](../../docs/figma-studio-runner.md) for the integration notes.

plugins/figma-to-wordpress-studio/src/code.ts

@@ -229,27 +229,49 @@ async function exportAsset(node: SceneNode, format: AssetExportFormat, imageHash
 }
 
 async function getDocument(): Promise<NormalizedDocument> {
-  if ("loadAllPagesAsync" in figma) {
-    await figma.loadAllPagesAsync();
+  if ("loadAsync" in figma.currentPage) {
+    await figma.currentPage.loadAsync();
   }
 
   const context: NormalizeContext = { assets: new Map() };
-  const pages = await Promise.all(figma.root.children.map((page) => normalizeNode(page, context, "PAGE")));
+  const currentPage = await normalizeNode(figma.currentPage, context, "PAGE");
+  const selectedNodes = await Promise.all(figma.currentPage.selection.map((node) => normalizeNode(node, context)));
   const root: NormalizedSceneNode = {
     id: figma.root.id,
     name: figma.root.name || "Figma document",
     type: "DOCUMENT",
     visible: true,
-    children: pages,
+    children: [currentPage],
   };
   applyDerivedBounds(root);
+  const selectedNodeIds = selectedNodes.map((node) => node.id);
 
   return {
     id: figma.root.id,
     name: figma.root.name || "Figma document",
     type: "DOCUMENT",
     exportedAt: new Date().toISOString(),
     root,
+    source: {
+      provider: "figma",
+      plugin: "figma-to-wordpress-studio",
+      fileKey: figma.fileKey,
+      fileName: figma.root.name || "Figma document",
+      editorType: figma.editorType,
+      currentPage: {
+        id: figma.currentPage.id,
+        name: figma.currentPage.name,
+      },
+    },
+    selectionIntent: {
+      scope: selectedNodes.length ? "selected-nodes" : "current-page",
+      pageId: figma.currentPage.id,
+      pageName: figma.currentPage.name,
+      selectedNodeIds,
+      rootNodeIds: selectedNodes.length ? selectedNodeIds : [figma.currentPage.id],
+    },
+    currentPage,
+    selectedNodes,
     assets: Array.from(context.assets.values()),
   };
 }

plugins/figma-to-wordpress-studio/src/payload.ts

@@ -1,5 +1,5 @@
 import type { WebsiteArtifact } from "./index";
-import type { NormalizedSelection } from "./types";
+import type { GeneratedArtifact, NormalizedSelection } from "./types";
 
 export type WebsiteArtifactFileRole = "html" | "css" | "js" | "asset" | "metadata";
 
@@ -19,6 +19,70 @@ export interface WebsiteArtifactBundle {
   import_source: "figma-to-wordpress-studio";
 }
 
+export interface FigmaSourcePayload {
+  schema: "wordpress-studio/figma-source/v1";
+  source: {
+    type: "figma";
+    metadata: NormalizedSelection["source"];
+    exportedAt: string;
+  };
+  intent: NormalizedSelection["selectionIntent"];
+  scenegraph: {
+    currentPage: NormalizedSelection["currentPage"];
+    selectedNodes: NormalizedSelection["selectedNodes"];
+  };
+  assets: NormalizedSelection["assets"];
+  transform: {
+    target: "wordpress";
+    route: "static-site-importer/figma";
+    options: {
+      selectionScope: NormalizedSelection["selectionIntent"]["scope"];
+      pageId: string;
+      selectedNodeIds: string[];
+      preserveSourceScenegraph: true;
+      importAssets: true;
+    };
+  };
+  debug?: {
+    generatedArtifact?: GeneratedArtifact["studioImportPayload"];
+    diagnostics: GeneratedArtifact["diagnostics"];
+    metadata?: GeneratedArtifact["metadata"];
+  };
+}
+
+export function toFigmaSourcePayload(selection: NormalizedSelection, artifact?: GeneratedArtifact | null): FigmaSourcePayload {
+  return {
+    schema: "wordpress-studio/figma-source/v1",
+    source: {
+      type: "figma",
+      metadata: selection.source,
+      exportedAt: selection.exportedAt,
+    },
+    intent: selection.selectionIntent,
+    scenegraph: {
+      currentPage: selection.currentPage,
+      selectedNodes: selection.selectedNodes,
+    },
+    assets: selection.assets,
+    transform: {
+      target: "wordpress",
+      route: "static-site-importer/figma",
+      options: {
+        selectionScope: selection.selectionIntent.scope,
+        pageId: selection.selectionIntent.pageId,
+        selectedNodeIds: selection.selectionIntent.selectedNodeIds,
+        preserveSourceScenegraph: true,
+        importAssets: true,
+      },
+    },
+    debug: artifact ? {
+      generatedArtifact: artifact.studioImportPayload,
+      diagnostics: artifact.diagnostics,
+      metadata: artifact.metadata,
+    } : undefined,
+  };
+}
+
 export function toWebsiteArtifactBundle(artifact: WebsiteArtifact, _selection: NormalizedSelection): WebsiteArtifactBundle {
   return {
     schema: "blocks-engine/php-transformer/site-artifact/v1",

plugins/figma-to-wordpress-studio/src/types.ts

@@ -70,11 +70,35 @@ export type NormalizedSelection = {
   type: string;
   exportedAt: string;
   root: NormalizedSceneNode;
+  source: FigmaSourceMetadata;
+  selectionIntent: FigmaSelectionIntent;
+  currentPage: NormalizedSceneNode;
+  selectedNodes: NormalizedSceneNode[];
   assets: NormalizedAsset[];
 };
 
 export type NormalizedDocument = NormalizedSelection;
 
+export type FigmaSourceMetadata = {
+  provider: "figma";
+  plugin: "figma-to-wordpress-studio";
+  fileKey?: string;
+  fileName: string;
+  editorType: string;
+  currentPage: {
+    id: string;
+    name: string;
+  };
+};
+
+export type FigmaSelectionIntent = {
+  scope: "selected-nodes" | "current-page";
+  pageId: string;
+  pageName: string;
+  selectedNodeIds: string[];
+  rootNodeIds: string[];
+};
+
 export type GeneratedArtifact = {
   title: string;
   html: string;

plugins/figma-to-wordpress-studio/src/ui.ts

@@ -1,4 +1,5 @@
 import type { GeneratedArtifact, NormalizedSelection, PluginToUiMessage, UiToPluginMessage } from "./types";
+import { toFigmaSourcePayload } from "./payload";
 
 let currentArtifact: GeneratedArtifact | null = null;
 let currentSelection: NormalizedSelection | null = null;
@@ -37,14 +38,14 @@ function artifactBundleSummary(artifact: GeneratedArtifact | null) {
 }
 
 function updateActions() {
-  const disabled = !currentArtifact;
+  const disabled = !currentSelection;
 
   if (studioButton) studioButton.disabled = disabled;
 }
 
 async function openInStudio() {
-  if (!currentArtifact) {
-    log("Studio import requested before artifact was ready.");
+  if (!currentSelection) {
+    log("Studio import requested before Figma source data was ready.");
     return;
   }
 
@@ -54,14 +55,15 @@ async function openInStudio() {
   setStatus("Sending this Figma file to WordPress Studio...");
 
   try {
+    const sourcePayload = toFigmaSourcePayload(currentSelection, currentArtifact);
     const response = await fetch(studioHandoffEndpoint, {
       method: "POST",
       headers: {
         "Content-Type": "application/json",
       },
       body: JSON.stringify({
-        artifact: currentArtifact.studioImportPayload,
-        siteName: currentArtifact.title,
+        source: sourcePayload,
+        siteName: currentSelection.name,
       }),
     });
     const data = await response.json().catch(() => null) as { success?: boolean; error?: string } | null;
@@ -74,7 +76,11 @@ async function openInStudio() {
     sendToPlugin({ type: "notify", message: "Sent to WordPress Studio." });
     log("Studio import handoff accepted.", {
       endpoint: studioHandoffEndpoint,
-      ...artifactBundleSummary(currentArtifact),
+      schema: sourcePayload.schema,
+      selectionScope: sourcePayload.intent.scope,
+      pageId: sourcePayload.intent.pageId,
+      selectedNodes: sourcePayload.intent.selectedNodeIds.length,
+      debugArtifact: artifactBundleSummary(currentArtifact),
     });
   } catch (error) {
     console.error("[Figma to WordPress Studio] Studio handoff failed.", error);