@design-embed/plugin-figma-html 0.1.0 → 1.0.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Jin-Woo Lee
+Copyright (c) 2026 Jin Woo Lee
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 

package/dist/compilers/compilerUtils.d.mts

@@ -0,0 +1,11 @@
+import { FigmaNode } from "../types.mjs";
+
+//#region packages/plugin-figma-html/src/compilers/compilerUtils.d.ts
+declare function toComponentName(name: string | undefined, fallback?: string): string;
+declare function escapeHtml(value: string | undefined): string;
+declare function escapeJsString(value: string | undefined): string;
+declare function getNodeStyles(node: FigmaNode, parent?: FigmaNode): Record<string, string | number>;
+declare function toReactStyle(styles: Record<string, string | number>): string;
+declare function toCssText(styles: Record<string, string | number>): string;
+//#endregion
+export { escapeHtml, escapeJsString, getNodeStyles, toComponentName, toCssText, toReactStyle };

package/dist/compilers/compilerUtils.mjs

@@ -0,0 +1,119 @@
+//#region packages/plugin-figma-html/src/compilers/compilerUtils.ts
+function toComponentName(name, fallback = "FigmaExport") {
+	const cleaned = (name || "").replace(/[^a-zA-Z0-9가-힣]/g, "");
+	if (!cleaned) return fallback;
+	return /^[0-9]/.test(cleaned) ? `${fallback}${cleaned}` : cleaned;
+}
+function escapeHtml(value) {
+	return (value || "").replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+}
+function escapeJsString(value) {
+	return JSON.stringify(value || "");
+}
+function getNodeStyles(node, parent) {
+	const styles = {};
+	const bounds = node.absoluteBoundingBox;
+	const parentBounds = parent?.absoluteBoundingBox;
+	const parentUsesLayout = Boolean(parent?.layoutMode && parent.layoutMode !== "NONE");
+	if (Boolean(parent && (!parentUsesLayout || node.layoutPositioning === "ABSOLUTE")) && bounds && parentBounds) {
+		styles.position = "absolute";
+		styles.left = `${Math.round((bounds.x || 0) - (parentBounds.x || 0))}px`;
+		styles.top = `${Math.round((bounds.y || 0) - (parentBounds.y || 0))}px`;
+	} else if (node.children?.length || node.layoutMode === "NONE") styles.position = "relative";
+	if (bounds && node.layoutSizingHorizontal !== "HUG") styles.width = `${Math.round(bounds.width || 0)}px`;
+	if (bounds && node.layoutSizingVertical !== "HUG") styles.height = `${Math.round(bounds.height || 0)}px`;
+	if (node.layoutMode === "HORIZONTAL" || node.layoutMode === "VERTICAL") {
+		styles.display = "flex";
+		styles.flexDirection = node.layoutMode === "HORIZONTAL" ? "row" : "column";
+		styles.boxSizing = "border-box";
+		if (node.layoutWrap === "WRAP") styles.flexWrap = "wrap";
+		if (node.itemSpacing !== void 0) styles.gap = `${Math.round(node.itemSpacing)}px`;
+		if (node.counterAxisSpacing !== void 0 && node.layoutWrap === "WRAP") styles.rowGap = `${Math.round(node.counterAxisSpacing)}px`;
+		styles.justifyContent = mapPrimaryAxisAlignment(node.primaryAxisAlignItems);
+		styles.alignItems = mapCounterAxisAlignment(node.counterAxisAlignItems);
+	} else if (node.layoutMode === "GRID") {
+		styles.display = "grid";
+		styles.boxSizing = "border-box";
+		if (node.gridColumnsSizing) styles.gridTemplateColumns = node.gridColumnsSizing;
+		if (node.gridRowsSizing) styles.gridTemplateRows = node.gridRowsSizing;
+		if (node.gridColumnGap !== void 0) styles.columnGap = `${Math.round(node.gridColumnGap)}px`;
+		if (node.gridRowGap !== void 0) styles.rowGap = `${Math.round(node.gridRowGap)}px`;
+	}
+	if (node.layoutSizingHorizontal === "FILL" || node.layoutGrow === 1) {
+		styles.flex = 1;
+		styles.width = "100%";
+	}
+	if (node.layoutSizingVertical === "FILL") styles.height = "100%";
+	if (node.layoutAlign === "STRETCH") styles.alignSelf = "stretch";
+	if (node.gridColumnSpan && node.gridColumnSpan > 1) styles.gridColumn = `span ${node.gridColumnSpan}`;
+	if (node.gridRowSpan && node.gridRowSpan > 1) styles.gridRow = `span ${node.gridRowSpan}`;
+	if (node.paddingTop !== void 0) styles.paddingTop = `${node.paddingTop}px`;
+	if (node.paddingBottom !== void 0) styles.paddingBottom = `${node.paddingBottom}px`;
+	if (node.paddingLeft !== void 0) styles.paddingLeft = `${node.paddingLeft}px`;
+	if (node.paddingRight !== void 0) styles.paddingRight = `${node.paddingRight}px`;
+	if (node.clipsContent) styles.overflow = "hidden";
+	if (node.opacity !== void 0 && node.opacity !== 1) styles.opacity = node.opacity;
+	const fill = node.fills?.find((item) => item.type === "SOLID" && item.color);
+	if (fill?.color) if (node.type === "TEXT") styles.color = toRgba(fill.color, fill.opacity ?? 1);
+	else styles.backgroundColor = toRgba(fill.color, fill.opacity ?? 1);
+	const imageFill = node.fills?.find((item) => item.type === "IMAGE" && (item.imageLocalPath || item.imageUrl));
+	const imageSource = imageFill?.imageLocalPath || imageFill?.imageUrl;
+	if (imageSource) {
+		styles.backgroundImage = `url("${imageSource}")`;
+		styles.backgroundRepeat = "no-repeat";
+		styles.backgroundPosition = "center";
+		styles.backgroundSize = mapImageScaleMode(imageFill.scaleMode);
+	}
+	const stroke = node.strokes?.find((item) => item.type === "SOLID" && item.color);
+	if (stroke?.color && node.strokeWeight) {
+		styles.border = `${Math.round(node.strokeWeight)}px solid ${toRgba(stroke.color, stroke.opacity ?? 1)}`;
+		styles.boxSizing = "border-box";
+	}
+	if (node.rectangleCornerRadii?.length === 4) styles.borderRadius = node.rectangleCornerRadii.map((radius) => `${Math.round(radius)}px`).join(" ");
+	else if (node.cornerRadius) styles.borderRadius = `${Math.round(node.cornerRadius)}px`;
+	if (node.type === "TEXT") {
+		const textStyle = node.style || {};
+		if (textStyle.fontSize) styles.fontSize = `${textStyle.fontSize}px`;
+		if (textStyle.fontWeight) styles.fontWeight = textStyle.fontWeight;
+		if (textStyle.fontFamily) styles.fontFamily = `"${textStyle.fontFamily}", sans-serif`;
+		if (textStyle.lineHeightPx) styles.lineHeight = `${Math.round(textStyle.lineHeightPx)}px`;
+	}
+	return styles;
+}
+function toReactStyle(styles) {
+	return JSON.stringify(styles).replace(/"([^"]+)":/g, "$1:");
+}
+function toCssText(styles) {
+	return Object.entries(styles).map(([key, value]) => `${toKebabCase(key)}: ${value};`).join(" ");
+}
+function toKebabCase(value) {
+	return value.replace(/[A-Z]/g, (match) => `-${match.toLowerCase()}`);
+}
+function mapPrimaryAxisAlignment(value) {
+	switch (value) {
+		case "CENTER": return "center";
+		case "MAX": return "flex-end";
+		case "SPACE_BETWEEN": return "space-between";
+		default: return "flex-start";
+	}
+}
+function mapCounterAxisAlignment(value) {
+	switch (value) {
+		case "CENTER": return "center";
+		case "MAX": return "flex-end";
+		case "BASELINE": return "baseline";
+		default: return "flex-start";
+	}
+}
+function mapImageScaleMode(value) {
+	switch (value) {
+		case "FIT": return "contain";
+		case "TILE": return "auto";
+		default: return "cover";
+	}
+}
+function toRgba(color, opacity) {
+	return `rgba(${Math.round(color.r * 255)}, ${Math.round(color.g * 255)}, ${Math.round(color.b * 255)}, ${opacity})`;
+}
+//#endregion
+export { escapeHtml, escapeJsString, getNodeStyles, toComponentName, toCssText, toReactStyle };

package/dist/compilers/htmlCompiler.d.mts

@@ -0,0 +1,6 @@
+import { FigmaCompiler } from "../types.mjs";
+
+//#region packages/plugin-figma-html/src/compilers/htmlCompiler.d.ts
+declare const compileHtml: FigmaCompiler;
+//#endregion
+export { compileHtml };

package/dist/compilers/htmlCompiler.mjs

@@ -0,0 +1,31 @@
+import { escapeHtml, getNodeStyles, toCssText } from "./compilerUtils.mjs";
+//#region packages/plugin-figma-html/src/compilers/htmlCompiler.ts
+const compileHtml = (node) => [{
+	path: "index.html",
+	contents: `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>${escapeHtml(node.name || "Figma Export")}</title>
+  </head>
+  <body>
+${walkHtml(node, void 0, 2).trimEnd()}
+  </body>
+</html>
+`
+}];
+function walkHtml(node, parent, depth = 0) {
+	if (!node || node.visible === false) return "";
+	const indent = "  ".repeat(depth);
+	const childIndent = "  ".repeat(depth + 1);
+	const name = escapeHtml(node.name || "LayoutBox");
+	const style = escapeHtml(toCssText(getNodeStyles(node, parent)));
+	if (node.type === "TEXT") return `${indent}<span style="${style}" data-layer="${name}">
+${childIndent}${escapeHtml(node.characters)}
+${indent}</span>\n`;
+	return `${indent}<div style="${style}" data-layer="${name}">
+${node.children?.map((child) => walkHtml(child, node, depth + 1)).join("") || ""}${indent}</div>\n`;
+}
+//#endregion
+export { compileHtml };

package/dist/compilers/index.d.mts

@@ -0,0 +1,11 @@
+import { CompilerMode, FigmaCompiler } from "../types.mjs";
+import { compileHtml } from "./htmlCompiler.mjs";
+import { compileReact } from "./reactCompiler.mjs";
+import { compileVanjs } from "./vanjsCompiler.mjs";
+
+//#region packages/plugin-figma-html/src/compilers/index.d.ts
+declare const compilers: Record<CompilerMode, FigmaCompiler>;
+declare function isCompilerMode(value: string | undefined): value is CompilerMode;
+declare function getCompiler(mode: CompilerMode): FigmaCompiler;
+//#endregion
+export { compileHtml, compileReact, compileVanjs, compilers, getCompiler, isCompilerMode };

package/dist/compilers/index.mjs

@@ -0,0 +1,17 @@
+import { compileHtml } from "./htmlCompiler.mjs";
+import { compileReact } from "./reactCompiler.mjs";
+import { compileVanjs } from "./vanjsCompiler.mjs";
+//#region packages/plugin-figma-html/src/compilers/index.ts
+const compilers = {
+	react: compileReact,
+	html: compileHtml,
+	vanjs: compileVanjs
+};
+function isCompilerMode(value) {
+	return Boolean(value && value in compilers);
+}
+function getCompiler(mode) {
+	return compilers[mode];
+}
+//#endregion
+export { compileHtml, compileReact, compileVanjs, compilers, getCompiler, isCompilerMode };

package/dist/compilers/index.test.d.mts

@@ -0,0 +1 @@
+export { };

package/dist/compilers/index.test.mjs

@@ -0,0 +1,45 @@
+import { compileHtml } from "./htmlCompiler.mjs";
+import { compileReact } from "./reactCompiler.mjs";
+import { compileVanjs } from "./vanjsCompiler.mjs";
+import { getCompiler } from "./index.mjs";
+import assert from "node:assert/strict";
+import { describe, test } from "node:test";
+//#region packages/plugin-figma-html/src/compilers/index.test.ts
+const sampleNode = {
+	name: "Sample Frame",
+	type: "FRAME",
+	layoutMode: "VERTICAL",
+	absoluteBoundingBox: {
+		x: 0,
+		y: 0,
+		width: 100,
+		height: 80
+	},
+	children: [{
+		name: "Title",
+		type: "TEXT",
+		characters: "Hello",
+		absoluteBoundingBox: {
+			x: 8,
+			y: 8,
+			width: 40,
+			height: 20
+		}
+	}]
+};
+describe("compiler registry", () => {
+	test("returns compiler functions without external dependencies", () => {
+		assert.equal(getCompiler("html"), compileHtml);
+		assert.equal(getCompiler("react"), compileReact);
+		assert.equal(getCompiler("vanjs"), compileVanjs);
+	});
+});
+describe("compilers", () => {
+	test("compile a Figma node into generated files", () => {
+		assert.match(compileHtml(sampleNode)[0]?.contents ?? "", /Hello/);
+		assert.match(compileReact(sampleNode)[0]?.contents ?? "", /SampleFrame/);
+		assert.deepEqual(compileVanjs(sampleNode).map((file) => file.path), ["index.html", "main.js"]);
+	});
+});
+//#endregion
+export {};

package/dist/compilers/reactCompiler.d.mts

@@ -0,0 +1,6 @@
+import { FigmaCompiler } from "../types.mjs";
+
+//#region packages/plugin-figma-html/src/compilers/reactCompiler.d.ts
+declare const compileReact: FigmaCompiler;
+//#endregion
+export { compileReact };

package/dist/compilers/reactCompiler.mjs

@@ -0,0 +1,47 @@
+import { escapeHtml, escapeJsString, getNodeStyles, toComponentName, toReactStyle } from "./compilerUtils.mjs";
+//#region packages/plugin-figma-html/src/compilers/reactCompiler.ts
+const compileReact = (node) => {
+	const componentName = toComponentName(node.name);
+	return [{
+		path: "FigmaComponent.tsx",
+		contents: `import React from 'react';
+
+/**
+ * Auto-generated UI component from Figma frame: "${escapeHtml(node.name)}"
+ */
+export const ${componentName}: React.FC = () => {
+  return (
+${walkReact(node).trimEnd()}
+  );
+};
+
+export default ${componentName};
+`
+	}];
+};
+function walkReact(node, depth = 2) {
+	if (!node || node.visible === false) return "";
+	const indent = "  ".repeat(depth);
+	const childIndent = "  ".repeat(depth + 1);
+	const name = escapeHtml(node.name || "LayoutBox");
+	const styles = toReactStyle(getNodeStyles(node));
+	if (node.type === "TEXT") return `${indent}<span style={${styles}} data-layer={${escapeJsString(node.name || "LayoutBox")}}>
+${childIndent}{${escapeJsString(node.characters)}}
+${indent}</span>\n`;
+	return `${indent}<div style={${styles}} data-layer="${name}">
+${node.children?.map((child) => walkReactWithParent(child, node, depth + 1)).join("") || ""}${indent}</div>\n`;
+}
+function walkReactWithParent(node, parent, depth) {
+	if (!node || node.visible === false) return "";
+	const indent = "  ".repeat(depth);
+	const childIndent = "  ".repeat(depth + 1);
+	const name = escapeHtml(node.name || "LayoutBox");
+	const styles = toReactStyle(getNodeStyles(node, parent));
+	if (node.type === "TEXT") return `${indent}<span style={${styles}} data-layer={${escapeJsString(node.name || "LayoutBox")}}>
+${childIndent}{${escapeJsString(node.characters)}}
+${indent}</span>\n`;
+	return `${indent}<div style={${styles}} data-layer="${name}">
+${node.children?.map((child) => walkReactWithParent(child, node, depth + 1)).join("") || ""}${indent}</div>\n`;
+}
+//#endregion
+export { compileReact };

package/dist/compilers/vanjsCompiler.d.mts

@@ -0,0 +1,6 @@
+import { FigmaCompiler } from "../types.mjs";
+
+//#region packages/plugin-figma-html/src/compilers/vanjsCompiler.d.ts
+declare const compileVanjs: FigmaCompiler;
+//#endregion
+export { compileVanjs };

package/dist/compilers/vanjsCompiler.mjs

@@ -0,0 +1,47 @@
+import { escapeHtml, escapeJsString, getNodeStyles, toCssText } from "./compilerUtils.mjs";
+//#region packages/plugin-figma-html/src/compilers/vanjsCompiler.ts
+const compileVanjs = (node) => [{
+	path: "index.html",
+	contents: `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>${escapeHtml(node.name || "Figma Export")}</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="./main.js"><\/script>
+  </body>
+</html>
+`
+}, {
+	path: "main.js",
+	contents: `import van from 'https://cdn.jsdelivr.net/npm/vanjs-core@1.5.5/src/van.min.js';
+
+const { div, span } = van.tags;
+
+const App = () => (
+${walkVanjs(node, void 0, 1).trimEnd()}
+);
+
+van.add(document.getElementById('app'), App());
+`
+}];
+function walkVanjs(node, parent, depth = 0) {
+	if (!node || node.visible === false) return "null";
+	const indent = "  ".repeat(depth);
+	const childIndent = "  ".repeat(depth + 1);
+	const tag = node.type === "TEXT" ? "span" : "div";
+	const props = `{
+${childIndent}style: ${escapeJsString(toCssText(getNodeStyles(node, parent)))},
+${childIndent}"data-layer": ${escapeJsString(node.name || "LayoutBox")}
+${indent}}`;
+	if (node.type === "TEXT") return `${indent}${tag}(${props}, ${escapeJsString(node.characters)})\n`;
+	const children = (node.children || []).map((child) => walkVanjs(child, node, depth + 1)).filter((value) => value.trim() !== "null").join(",");
+	if (!children) return `${indent}${tag}(${props})\n`;
+	return `${indent}${tag}(${props},
+${children}${indent})\n`;
+}
+//#endregion
+export { compileVanjs };

package/dist/design-embed/src/core/diagnostics/diagnostic.d.mts

@@ -0,0 +1,16 @@
+import { SourceLocation } from "../nodes.mjs";
+
+//#region packages/design-embed/src/core/diagnostics/diagnostic.d.ts
+type DiagnosticSeverity = "error" | "warning" | "info";
+interface Diagnostic {
+  code: string;
+  message: string;
+  severity: DiagnosticSeverity;
+  file?: string;
+  source?: SourceLocation;
+  selector?: string;
+  property?: string;
+  details?: Record<string, unknown>;
+}
+//#endregion
+export { Diagnostic };

package/dist/design-embed/src/core/nodes.d.mts

@@ -0,0 +1,14 @@
+//#region packages/design-embed/src/core/nodes.d.ts
+/**
+ * Location in the source HTML file.
+ */
+interface SourceLocation {
+  /** Absolute offset in characters. */
+  offset: number;
+  /** 1-based line number. */
+  line: number;
+  /** 1-based column number. */
+  column: number;
+}
+//#endregion
+export { SourceLocation };

package/dist/design-embed/src/core/plugins/pluginApi.d.mts

@@ -0,0 +1,34 @@
+import { Diagnostic } from "../diagnostics/diagnostic.mjs";
+
+//#region packages/design-embed/src/core/plugins/pluginApi.d.ts
+/**
+ * Represents a file generated by the compiler.
+ */
+interface GeneratedFile {
+  /** Relative path from the output directory. */
+  path: string;
+  /** File content. */
+  contents: string;
+}
+interface GeneratedAsset {
+  path: string;
+  contents?: string | Uint8Array;
+  sourceUrl?: string;
+}
+interface SourcePlugin {
+  name: string;
+  run(input: SourcePluginInput): Promise<SourcePluginResult>;
+}
+interface SourcePluginInput {
+  cwd: string;
+  config?: unknown;
+}
+interface SourcePluginResult {
+  html?: string;
+  css?: string;
+  assets?: GeneratedAsset[];
+  files?: GeneratedFile[];
+  diagnostics: Diagnostic[];
+}
+//#endregion
+export { SourcePlugin, SourcePluginInput, SourcePluginResult };

package/dist/external/figmaApi.d.mts

@@ -0,0 +1,17 @@
+import { ExtractedParams, FigmaNode } from "../types.mjs";
+
+//#region packages/plugin-figma-html/src/external/figmaApi.d.ts
+type FigmaApiResponse = unknown;
+type FigmaFetcher = (input: string, init?: RequestInit) => Promise<Response>;
+interface FigmaClientOptions {
+  token: string;
+  fetcher?: FigmaFetcher;
+}
+declare function extractParamsFromURL(input: string): ExtractedParams;
+declare function fetchFigmaNode(fileKey: string, nodeId: string | null, options: FigmaClientOptions): Promise<FigmaNode>;
+declare function fetchFigmaApiResponse(fileKey: string, nodeId: string | null, options: FigmaClientOptions): Promise<FigmaApiResponse>;
+declare function buildFigmaNodeEndpoint(fileKey: string, nodeId: string | null): string;
+declare function fetchFigmaImageFills(fileKey: string, options: FigmaClientOptions): Promise<Record<string, string>>;
+declare function buildFigmaImageFillsEndpoint(fileKey: string): string;
+//#endregion
+export { FigmaApiResponse, FigmaClientOptions, FigmaFetcher, buildFigmaImageFillsEndpoint, buildFigmaNodeEndpoint, extractParamsFromURL, fetchFigmaApiResponse, fetchFigmaImageFills, fetchFigmaNode };

package/dist/external/figmaApi.mjs

@@ -0,0 +1,55 @@
+//#region packages/plugin-figma-html/src/external/figmaApi.ts
+function extractParamsFromURL(input) {
+	const cleanInput = input.trim();
+	const fileKey = cleanInput.match(/figma\.com\/(?:file|design)\/([^/]+)/)?.[1] || cleanInput;
+	let nodeId = null;
+	try {
+		if (cleanInput.includes("figma.com")) {
+			const rawNodeId = new URL(cleanInput).searchParams.get("node-id");
+			if (rawNodeId) nodeId = rawNodeId.replace(/-/g, ":");
+		}
+	} catch {}
+	return {
+		fileKey,
+		nodeId
+	};
+}
+async function fetchFigmaNode(fileKey, nodeId, options) {
+	const data = await fetchFigmaApiResponse(fileKey, nodeId, options);
+	const rootNode = nodeId ? data.nodes?.[nodeId]?.document : data.document;
+	if (!rootNode) throw new Error(`Could not find valid element tree for Node ID: ${nodeId}`);
+	attachImageFillUrls(rootNode, await fetchFigmaImageFills(fileKey, options));
+	return rootNode;
+}
+async function fetchFigmaApiResponse(fileKey, nodeId, options) {
+	const endpoint = buildFigmaNodeEndpoint(fileKey, nodeId);
+	const response = await (options.fetcher ?? fetch)(endpoint, {
+		method: "GET",
+		headers: { "X-Figma-Token": options.token }
+	});
+	if (!response.ok) throw new Error(`Figma API Error: ${response.status} ${response.statusText}`);
+	return response.json();
+}
+function buildFigmaNodeEndpoint(fileKey, nodeId) {
+	if (!nodeId) return `https://api.figma.com/v1/files/${fileKey}?depth=2`;
+	return `https://api.figma.com/v1/files/${fileKey}/nodes?ids=${encodeURIComponent(nodeId)}`;
+}
+async function fetchFigmaImageFills(fileKey, options) {
+	const endpoint = buildFigmaImageFillsEndpoint(fileKey);
+	const response = await (options.fetcher ?? fetch)(endpoint, {
+		method: "GET",
+		headers: { "X-Figma-Token": options.token }
+	});
+	if (!response.ok) throw new Error(`Figma image fills API Error: ${response.status} ${response.statusText}`);
+	const data = await response.json();
+	return Object.fromEntries(Object.entries(data.images || {}).filter((entry) => typeof entry[1] === "string"));
+}
+function buildFigmaImageFillsEndpoint(fileKey) {
+	return `https://api.figma.com/v1/files/${fileKey}/images`;
+}
+function attachImageFillUrls(node, imageFills) {
+	for (const fill of node.fills || []) if (fill.type === "IMAGE" && fill.imageRef) fill.imageUrl = imageFills[fill.imageRef];
+	for (const child of node.children || []) attachImageFillUrls(child, imageFills);
+}
+//#endregion
+export { buildFigmaImageFillsEndpoint, buildFigmaNodeEndpoint, extractParamsFromURL, fetchFigmaApiResponse, fetchFigmaImageFills, fetchFigmaNode };

package/dist/external/figmaApi.test.d.mts

@@ -0,0 +1 @@
+export { };

package/dist/external/figmaApi.test.mjs

@@ -0,0 +1,101 @@
+import { buildFigmaImageFillsEndpoint, buildFigmaNodeEndpoint, extractParamsFromURL, fetchFigmaApiResponse, fetchFigmaImageFills, fetchFigmaNode } from "./figmaApi.mjs";
+import assert from "node:assert/strict";
+import { describe, test } from "node:test";
+//#region packages/plugin-figma-html/src/external/figmaApi.test.ts
+describe("extractParamsFromURL", () => {
+	test("extracts file key and node id from a Figma design URL", () => {
+		assert.deepEqual(extractParamsFromURL("https://www.figma.com/design/file123/Sample?node-id=1-2&t=abc"), {
+			fileKey: "file123",
+			nodeId: "1:2"
+		});
+	});
+	test("treats non-url input as a raw file key", () => {
+		assert.deepEqual(extractParamsFromURL("file123"), {
+			fileKey: "file123",
+			nodeId: null
+		});
+	});
+});
+describe("buildFigmaNodeEndpoint", () => {
+	test("builds root document endpoint", () => {
+		assert.equal(buildFigmaNodeEndpoint("file123", null), "https://api.figma.com/v1/files/file123?depth=2");
+	});
+	test("builds node endpoint with an encoded node id", () => {
+		assert.equal(buildFigmaNodeEndpoint("file123", "1:2"), "https://api.figma.com/v1/files/file123/nodes?ids=1%3A2");
+	});
+});
+describe("buildFigmaImageFillsEndpoint", () => {
+	test("builds image fills endpoint", () => {
+		assert.equal(buildFigmaImageFillsEndpoint("file123"), "https://api.figma.com/v1/files/file123/images");
+	});
+});
+describe("fetchFigmaNode", () => {
+	test("uses an injected fetcher and returns the selected node with image fill URLs", async () => {
+		const calls = [];
+		const fetcher = async (url, init) => {
+			calls.push([url, init]);
+			if (url.endsWith("/images")) return new Response(JSON.stringify({ images: { image123: "https://example.com/image.png" } }));
+			return new Response(JSON.stringify({ nodes: { "1:2": { document: {
+				id: "1:2",
+				name: "Button",
+				type: "FRAME",
+				fills: [{
+					type: "IMAGE",
+					imageRef: "image123"
+				}]
+			} } } }));
+		};
+		const node = await fetchFigmaNode("file123", "1:2", {
+			token: "token",
+			fetcher
+		});
+		assert.deepEqual(node, {
+			id: "1:2",
+			name: "Button",
+			type: "FRAME",
+			fills: [{
+				type: "IMAGE",
+				imageRef: "image123",
+				imageUrl: "https://example.com/image.png"
+			}]
+		});
+		assert.deepEqual(calls, [["https://api.figma.com/v1/files/file123/nodes?ids=1%3A2", {
+			method: "GET",
+			headers: { "X-Figma-Token": "token" }
+		}], ["https://api.figma.com/v1/files/file123/images", {
+			method: "GET",
+			headers: { "X-Figma-Token": "token" }
+		}]]);
+	});
+});
+describe("fetchFigmaImageFills", () => {
+	test("returns only successful image fill URLs", async () => {
+		const fetcher = async () => new Response(JSON.stringify({ images: {
+			image123: "https://example.com/image.png",
+			image456: null
+		} }));
+		assert.deepEqual(await fetchFigmaImageFills("file123", {
+			token: "token",
+			fetcher
+		}), { image123: "https://example.com/image.png" });
+	});
+});
+describe("fetchFigmaApiResponse", () => {
+	test("returns the raw API payload without extracting a document node", async () => {
+		const payload = {
+			name: "Raw file response",
+			document: {
+				id: "0:0",
+				name: "Document",
+				type: "DOCUMENT"
+			}
+		};
+		const fetcher = async () => new Response(JSON.stringify(payload));
+		assert.deepEqual(await fetchFigmaApiResponse("file123", null, {
+			token: "token",
+			fetcher
+		}), payload);
+	});
+});
+//#endregion
+export {};

package/dist/external/imageDownloader.d.mts

@@ -0,0 +1,17 @@
+import { FigmaNode } from "../types.mjs";
+import { FigmaFetcher } from "./figmaApi.mjs";
+
+//#region packages/plugin-figma-html/src/external/imageDownloader.d.ts
+interface DownloadFigmaImagesOptions {
+  fetcher?: FigmaFetcher;
+  publicPath?: string;
+}
+interface DownloadedFigmaImage {
+  imageRef: string;
+  sourceUrl: string;
+  filePath: string;
+  publicPath: string;
+}
+declare function downloadFigmaImageFills(rootNode: FigmaNode, outDir: string, options?: DownloadFigmaImagesOptions): Promise<DownloadedFigmaImage[]>;
+//#endregion
+export { DownloadFigmaImagesOptions, DownloadedFigmaImage, downloadFigmaImageFills };