Improve Figma runner artifact fidelity

Author: chubes4

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

@@ -32,35 +32,81 @@ function normalizePaints(paints: unknown) {
         type: typedPaint.type,
         visible: typedPaint.visible,
         opacity: typedPaint.opacity,
+        imageHash: "imageHash" in typedPaint && typeof typedPaint.imageHash === "string" ? typedPaint.imageHash : undefined,
         color: "color" in typedPaint ? typedPaint.color : undefined,
       };
     });
 }
 
+function hasImagePaint(paints: unknown): boolean {
+  return Array.isArray(paints) && paints.some((paint) => {
+    return !!paint && typeof paint === "object" && "type" in paint && paint.type === "IMAGE" && (!("visible" in paint) || paint.visible !== false);
+  });
+}
+
 function normalizeTextStyle(node: TextNode) {
   return {
     fontFamily: typeof node.fontName === "object" ? node.fontName.family : undefined,
     fontSize: typeof node.fontSize === "number" ? node.fontSize : undefined,
     fontWeight: typeof node.fontName === "object" ? node.fontName.style : undefined,
+    lineHeight: typeof node.lineHeight === "object" && node.lineHeight.unit === "PIXELS" ? node.lineHeight.value : undefined,
     textAlignHorizontal: node.textAlignHorizontal,
   };
 }
 
-function normalizeNode(node: SceneNode | PageNode, fallbackType?: string): NormalizedSceneNode {
+function applyDerivedBounds(node: NormalizedSceneNode) {
+  const children = (node.children || []).filter(
+    (child) => child.x !== undefined && child.y !== undefined && child.width !== undefined && child.height !== undefined,
+  );
+
+  if (!children.length) {
+    return;
+  }
+
+  const minX = Math.min(...children.map((child) => child.x || 0));
+  const minY = Math.min(...children.map((child) => child.y || 0));
+  const maxX = Math.max(...children.map((child) => (child.x || 0) + (child.width || 0)));
+  const maxY = Math.max(...children.map((child) => (child.y || 0) + (child.height || 0)));
+
+  if (node.x === undefined) normalizedNumberAssign(node, "x", minX);
+  if (node.y === undefined) normalizedNumberAssign(node, "y", minY);
+  if (node.width === undefined) normalizedNumberAssign(node, "width", maxX - minX);
+  if (node.height === undefined) normalizedNumberAssign(node, "height", maxY - minY);
+}
+
+function normalizedNumberAssign(node: NormalizedSceneNode, key: "x" | "y" | "width" | "height", value: number) {
+  if (Number.isFinite(value)) {
+    node[key] = value;
+  }
+}
+
+async function normalizeNode(node: SceneNode | PageNode, fallbackType?: string): Promise<NormalizedSceneNode> {
   const bounds = "absoluteBoundingBox" in node ? node.absoluteBoundingBox : null;
+  const fills = "fills" in node ? clonePaints(node, "fills") : undefined;
+  const hasImageFill = hasImagePaint(fills);
   const normalized: NormalizedSceneNode = {
     id: node.id,
     name: node.name,
-    type: fallbackType || node.type,
+    type: fallbackType || (hasImageFill ? "IMAGE" : node.type),
     visible: "visible" in node ? node.visible : true,
     x: bounds?.x,
     y: bounds?.y,
     width: bounds?.width,
     height: bounds?.height,
-    fills: "fills" in node ? normalizePaints(clonePaints(node, "fills")) : undefined,
+    fills: normalizePaints(fills),
     strokes: "strokes" in node ? normalizePaints(clonePaints(node, "strokes")) : undefined,
   };
 
+  if (hasImageFill && "exportAsync" in node) {
+    const asset = await exportAsset(node as SceneNode);
+    if (asset) {
+      normalized.image = {
+        dataUri: asset.dataUrl,
+        alt: node.name,
+      };
+    }
+  }
+
   if (node.type === "TEXT") {
     normalized.characters = node.characters;
     normalized.style = normalizeTextStyle(node);
@@ -75,7 +121,8 @@ function normalizeNode(node: SceneNode | PageNode, fallbackType?: string): Norma
   }
 
   if ("children" in node) {
-    normalized.children = node.children.map((child) => normalizeNode(child));
+    normalized.children = await Promise.all(node.children.map((child) => normalizeNode(child)));
+    applyDerivedBounds(normalized);
   }
 
   return normalized;
@@ -110,14 +157,15 @@ async function getDocument(): Promise<NormalizedDocument> {
     await figma.loadAllPagesAsync();
   }
 
-  const pages = figma.root.children.map((page) => normalizeNode(page, "PAGE"));
+  const pages = await Promise.all(figma.root.children.map((page) => normalizeNode(page, "PAGE")));
   const root: NormalizedSceneNode = {
     id: figma.root.id,
     name: figma.root.name || "Figma document",
     type: "DOCUMENT",
     visible: true,
     children: pages,
   };
+  applyDerivedBounds(root);
 
   return {
     id: figma.root.id,

plugins/figma-to-wordpress/src/index.ts

@@ -134,7 +134,7 @@ export function generateWebsiteArtifact(
   };
 }
 
-function renderNode(node: FigmaSceneNode, context: RenderContext, isRoot = false): string {
+function renderNode(node: FigmaSceneNode, context: RenderContext, isRoot = false, parent?: FigmaSceneNode): string {
   context.nodeCount += 1;
 
   if (node.visible === false) {
@@ -152,22 +152,22 @@ function renderNode(node: FigmaSceneNode, context: RenderContext, isRoot = false
   }
 
   if (node.type === "TEXT") {
-    return renderText(node, context);
+    return renderText(node, context, parent);
   }
 
   if (node.type === "IMAGE") {
-    return renderImage(node, context);
+    return renderImage(node, context, parent);
   }
 
   if (node.type === "RECTANGLE" && !node.children?.length) {
-    return renderRectangle(node, context);
+    return renderRectangle(node, context, parent);
   }
 
-  return renderContainer(node, context, isRoot);
+  return renderContainer(node, context, isRoot, parent);
 }
 
-function renderContainer(node: FigmaSceneNode, context: RenderContext, isRoot: boolean): string {
-  const className = addCssRule(node, context, ["section"]);
+function renderContainer(node: FigmaSceneNode, context: RenderContext, isRoot: boolean, parent?: FigmaSceneNode): string {
+  const className = addCssRule(node, context, ["section"], isRoot, parent);
   const tagName = isRoot ? "main" : isButtonLike(node) ? "a" : "section";
   const attrs = [
     `class="${className}"`,
@@ -178,21 +178,21 @@ function renderContainer(node: FigmaSceneNode, context: RenderContext, isRoot: b
   return `<${tagName} ${attrs.join(" ")}>\n${children}\n</${tagName}>`;
 }
 
-function renderText(node: FigmaSceneNode, context: RenderContext): string {
-  const className = addCssRule(node, context, ["text"]);
+function renderText(node: FigmaSceneNode, context: RenderContext, parent?: FigmaSceneNode): string {
+  const className = addCssRule(node, context, ["text"], false, parent);
   const content = escapeHtml(node.characters || "");
   const tagName = textTagName(node);
 
   return `<${tagName} class="${className}">${content}</${tagName}>`;
 }
 
-function renderRectangle(node: FigmaSceneNode, context: RenderContext): string {
-  const className = addCssRule(node, context, ["shape"]);
+function renderRectangle(node: FigmaSceneNode, context: RenderContext, parent?: FigmaSceneNode): string {
+  const className = addCssRule(node, context, ["shape"], false, parent);
   return `<div class="${className}" aria-hidden="true"></div>`;
 }
 
-function renderImage(node: FigmaSceneNode, context: RenderContext): string {
-  const className = addCssRule(node, context, ["image"]);
+function renderImage(node: FigmaSceneNode, context: RenderContext, parent?: FigmaSceneNode): string {
+  const className = addCssRule(node, context, ["image"], false, parent);
   const src = resolveImageSource(node, context);
   const alt = escapeAttribute(node.image?.alt || node.name || "");
 
@@ -201,17 +201,17 @@ function renderImage(node: FigmaSceneNode, context: RenderContext): string {
 
 function renderChildren(node: FigmaSceneNode, context: RenderContext): string {
   return (node.children || [])
-    .map((child) => renderNode(child, context))
+    .map((child) => renderNode(child, context, false, node))
     .filter(Boolean)
     .join("\n");
 }
 
-function addCssRule(node: FigmaSceneNode, context: RenderContext, parts: string[]): string {
+function addCssRule(node: FigmaSceneNode, context: RenderContext, parts: string[], isRoot = false, parent?: FigmaSceneNode): string {
   const baseClass = toClassName([node.name].concat(parts).join("-"));
   const count = context.usedClasses.get(baseClass) || 0;
   context.usedClasses.set(baseClass, count + 1);
   const className = count === 0 ? baseClass : `${baseClass}-${count + 1}`;
-  const declarations = cssDeclarations(node);
+  const declarations = cssDeclarations(node, isRoot, parent);
 
   if (declarations.length) {
     context.cssRules.push(`.${className} {\n${declarations.map((rule) => `  ${rule}`).join("\n")}\n}`);
@@ -220,28 +220,43 @@ function addCssRule(node: FigmaSceneNode, context: RenderContext, parts: string[
   return className;
 }
 
-function cssDeclarations(node: FigmaSceneNode): string[] {
+function cssDeclarations(node: FigmaSceneNode, isRoot: boolean, parent?: FigmaSceneNode): string[] {
   const declarations: string[] = [];
   const fill = firstVisiblePaint(node.fills);
   const stroke = firstVisiblePaint(node.strokes);
+  const positioned = shouldAbsolutelyPosition(node, parent);
 
+  if (positioned) {
+    declarations.push("position: absolute;");
+    declarations.push(`left: ${formatPx((node.x || 0) - (parent?.x || 0))};`);
+    declarations.push(`top: ${formatPx((node.y || 0) - (parent?.y || 0))};`);
+  }
   if (node.width !== undefined) declarations.push(`width: ${formatPx(node.width)};`);
   if (node.height !== undefined && node.type !== "TEXT") declarations.push(`min-height: ${formatPx(node.height)};`);
   if (node.opacity !== undefined && node.opacity < 1) declarations.push(`opacity: ${node.opacity};`);
   if (node.cornerRadius !== undefined) declarations.push(`border-radius: ${formatPx(node.cornerRadius)};`);
-  if (fill) declarations.push(`background: ${paintToCss(fill)};`);
+  if (fill && node.type === "TEXT") declarations.push(`color: ${paintToCss(fill)};`);
+  if (fill && node.type !== "TEXT") declarations.push(`background: ${paintToCss(fill)};`);
   if (stroke) declarations.push(`border: 1px solid ${paintToCss(stroke)};`);
 
   if (containerTypes.has(node.type)) {
-    declarations.push("display: flex;");
-    declarations.push("flex-direction: column;");
-    declarations.push("gap: 1rem;");
+    if (!positioned) declarations.push("position: relative;");
+    if (!hasPositionedChildren(node)) {
+      declarations.push("display: flex;");
+      declarations.push("flex-direction: column;");
+      declarations.push("gap: 1rem;");
+    }
+    if (isRoot) {
+      declarations.push("margin: 0 auto;");
+      declarations.push("overflow: hidden;");
+    }
   }
 
   if (node.type === "TEXT") {
+    declarations.push("margin: 0;");
     if (node.style?.fontFamily) declarations.push(`font-family: ${quoteFontFamily(node.style.fontFamily)};`);
     if (node.style?.fontSize) declarations.push(`font-size: ${formatPx(node.style.fontSize)};`);
-    if (node.style?.fontWeight) declarations.push(`font-weight: ${node.style.fontWeight};`);
+    if (node.style?.fontWeight) declarations.push(`font-weight: ${formatFontWeight(node.style.fontWeight)};`);
     if (node.style?.lineHeight) declarations.push(`line-height: ${formatLineHeight(node.style.lineHeight)};`);
     if (node.style?.textAlignHorizontal) declarations.push(`text-align: ${textAlign(node.style.textAlignHorizontal)};`);
   }
@@ -260,6 +275,14 @@ function cssDeclarations(node: FigmaSceneNode): string[] {
   return declarations;
 }
 
+function shouldAbsolutelyPosition(node: FigmaSceneNode, parent?: FigmaSceneNode): boolean {
+  return !!parent && node.x !== undefined && node.y !== undefined && hasPositionedChildren(parent);
+}
+
+function hasPositionedChildren(node: FigmaSceneNode): boolean {
+  return (node.children || []).some((child) => child.x !== undefined && child.y !== undefined);
+}
+
 function resolveImageSource(node: FigmaSceneNode, context: RenderContext): string {
   if (node.image?.src) {
     return node.image.src;
@@ -377,6 +400,25 @@ function formatLineHeight(value: number | string): string {
   return typeof value === "number" ? formatPx(value) : value;
 }
 
+function formatFontWeight(value: number | string): string {
+  if (typeof value === "number") {
+    return String(value);
+  }
+
+  const normalized = value.toLowerCase();
+  if (normalized.includes("thin")) return "100";
+  if (normalized.includes("extra light") || normalized.includes("ultra light")) return "200";
+  if (normalized.includes("light")) return "300";
+  if (normalized.includes("regular") || normalized.includes("book")) return "400";
+  if (normalized.includes("medium")) return "500";
+  if (normalized.includes("semi bold") || normalized.includes("semibold") || normalized.includes("demi bold")) return "600";
+  if (normalized.includes("extra bold") || normalized.includes("ultra bold")) return "800";
+  if (normalized.includes("bold")) return "700";
+  if (normalized.includes("black") || normalized.includes("heavy")) return "900";
+
+  return value;
+}
+
 function textAlign(value: string): string {
   const normalized = value.toLowerCase();
   return normalized === "justified" ? "justify" : normalized;

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

@@ -1,11 +1,12 @@
 import type { WebsiteArtifact } from "./index";
-import type { NormalizedSelection } from "./types";
+import type { NormalizedAsset, NormalizedSceneNode, NormalizedSelection } from "./types";
 
 export type WebsiteArtifactFileRole = "html" | "css" | "js" | "asset" | "metadata";
 
 export interface WebsiteArtifactBundleFile {
   path: string;
-  content: string;
+  content?: string;
+  content_base64?: string;
   role?: WebsiteArtifactFileRole;
   mime_type?: string;
 }
@@ -27,24 +28,58 @@ export interface WordPressRunnerRequest {
     exportedAt: string;
   };
   goal: string;
+  figma: FigmaScenegraphPayload;
   artifact_bundle: WebsiteArtifactBundle;
 }
 
+export interface FigmaScenegraphPayload {
+  schema: "figma-to-wordpress/scenegraph/v1";
+  name: string;
+  exportedAt: string;
+  root: NormalizedSceneNode;
+  nodes: NormalizedSceneNode[];
+  assets: NormalizedAsset[];
+}
+
 export function toWebsiteArtifactBundle(artifact: WebsiteArtifact, selection: NormalizedSelection): WebsiteArtifactBundle {
   return {
     schema: "figma-to-wordpress/website-artifact-bundle/v1",
     root: "website/",
     entrypoint: "website/index.html",
-    files: Object.entries(artifact.files).map(([filePath, content]) => ({
-      path: filePath.startsWith("website/") ? filePath : `website/${filePath}`,
-      content,
-      role: fileRole(filePath),
-      mime_type: mimeType(filePath),
-    })),
+    files: Object.entries(artifact.files).map(([filePath, content]) => toWebsiteArtifactBundleFile(filePath, content)),
     import_source: "figma-to-wordpress",
   };
 }
 
+function toWebsiteArtifactBundleFile(filePath: string, content: string): WebsiteArtifactBundleFile {
+  const file: WebsiteArtifactBundleFile = {
+    path: filePath.startsWith("website/") ? filePath : `website/${filePath}`,
+    role: fileRole(filePath),
+    mime_type: mimeType(filePath),
+  };
+  const dataUri = parseDataUri(content);
+  if (dataUri) {
+    file.content_base64 = dataUri.contentBase64;
+    file.mime_type = dataUri.mimeType;
+  } else {
+    file.content = content;
+  }
+
+  return file;
+}
+
+function parseDataUri(content: string): { mimeType: string; contentBase64: string } | null {
+  const match = content.match(/^data:([^;,]+);base64,(.+)$/s);
+  if (!match) {
+    return null;
+  }
+
+  return {
+    mimeType: match[1],
+    contentBase64: match[2],
+  };
+}
+
 export function buildWordPressRunnerRequest(bundle: WebsiteArtifactBundle, selection: NormalizedSelection): WordPressRunnerRequest {
   return {
     schema: "figma-to-wordpress/runner-request/v1",
@@ -54,10 +89,22 @@ export function buildWordPressRunnerRequest(bundle: WebsiteArtifactBundle, selec
       exportedAt: selection.exportedAt,
     },
     goal: `Import ${selection.name} into WordPress using Static Site Importer inside a browser Playground session.`,
+    figma: toFigmaScenegraphPayload(selection),
     artifact_bundle: bundle,
   };
 }
 
+function toFigmaScenegraphPayload(selection: NormalizedSelection): FigmaScenegraphPayload {
+  return {
+    schema: "figma-to-wordpress/scenegraph/v1",
+    name: selection.name,
+    exportedAt: selection.exportedAt,
+    root: selection.root,
+    nodes: selection.root.children?.length ? selection.root.children : [selection.root],
+    assets: selection.assets,
+  };
+}
+
 function fileRole(filePath: string): WebsiteArtifactFileRole {
   if (/\.html?$/.test(filePath)) return "html";
   if (/\.css$/.test(filePath)) return "css";