figma-rust-mcp 7.0.0 → 8.0.0

package/README.md

@@ -8,7 +8,7 @@ Enables AI agents (Google Antigravity, Claude Code, Cursor, Windsurf, VS Code, Z
 
 ## ⚡ Highlights
 
-- **Lossless Rust Tree Compression**: Compact/minimal tree responses share identical style bundles when the complete JSON becomes smaller. Node IDs, hierarchy, text, geometry and state differences remain intact. Full detail bypasses Rust compression; no heuristic merging of screens or repeated items.
+- **Lossless Rust Tree Compression**: Node reads are compact by default: identical style bundles are shared and values every layer carries are stored once, only when the JSON gets smaller. Node IDs, hierarchy, text, geometry and state differences stay inline; `detail: "full"` returns the raw payload.
 - **Pure Rust Native Performance**: Single native binary, no runtime or GC. Measure it on your machine with `npm run bench` or the plugin's **Bench** tab (see [Benchmarks](#-benchmarks)).
 - **Scoped In-Memory Index (`figma_read` search)**: Indexes page roots first and loads frame descendants on demand. Search reports the indexed scope and completeness.
 - **Binary IPC & Chunk Streaming**: Powered by **MessagePack** (`rmp-serde`) and progressive subtree chunking for instant transfers of massive design files.
@@ -227,18 +227,17 @@ Every read, search and export. **`operation`**:
 - **Design system**: `rules` (markdown rule sheet of tokens, text styles and components), `get_styles`, `get_variables`, `get_tokens`, `get_local_components`, `get_component_map`, `get_unmapped_components`.
 - **Export**: `screenshot`, `export_image` (png/jpg, `scale`), `export_svg`. Pass `outputPath` to save to disk instead of returning data.
 
-Compact/minimal `get_selection` and `get_design` responses may contain a root
-`_compression` object with `version: 1` and a `styles` dictionary. For each node
-with `styleRef`, merge `_compression.styles[node.styleRef]` into that node and
-remove `styleRef`; remove root `_compression` to reconstruct the plugin payload
-exactly. Style references are dictionary lookups, not inherited CSS. Payloads
-with reserved-field collisions or no net byte savings stay inline. `detail: "full"` bypasses this Rust transformation and queries the plugin rather than a
-compact selection cache. Plugin detail, visibility, precision, depth and node
-budgets still determine the source payload; compression cannot restore fields
-omitted there. Code generation continues to consume inline styles.
-
-No token-reduction or AI-latency percentage is claimed without a tokenizer and
-end-to-end benchmark on real designs.
+Node reads (`read_nodes`, `inspect_node`, `get_selection`, `subtree`, `typography`)
+are compact by default. When it makes the JSON smaller, the response carries a
+root `_compression` object (`version: 2`) with `styles` (exact style bundles shared
+by `styleRef`) and `defaults` (a value every layer carried, stored once). To
+reconstruct the plugin payload exactly: for each layer (object with string `id`,
+`name` and `type`) merge `_compression.styles[styleRef]` and remove `styleRef`,
+then add every `defaults` key the layer lacks; remove `_compression`. Identity,
+geometry, text and hierarchy always stay inline. `detail: "full"` returns the raw
+payload. On one 62-layer production frame read with every field group, the
+response went from 81.5KB to 35.8KB (style sharing alone: 50.3KB); with default
+fields, 19.0KB to 13.4KB. Bytes, not tokens; measure your own files.
 
 ### 3. `figma_write`
 Executes JavaScript draw commands inside the sandboxed VM to build or modify designs on the Figma canvas.
@@ -263,7 +262,7 @@ Compiles a node (or the selection) into component code.
 - **`framework`**: `"react-tailwind"` (default), `"react-shadcn"`, `"react-native"`, `"vue-tailwind"`, `"html"`, `"swiftui"`, `"clean-spec"`.
 - **`outputPath`**, **`componentName`**.
 - **`target: "tokens"`**: export variables and styles. **`format`**: `"css"` (default, `:root` + light/dark modes), `"tailwind"`, `"typescript"`, `"w3c"` (DTCG), `"json"`; **`collection`** / **`mode`** / **`prefix`**; **`outputPath`**.
-- **`target: "project"`**: scaffold a design system — `globals.css` (Tailwind layers + CSS variables), `tailwind.config.ts` and one component per local component / component set (first variant) in `componentDir`. Existing files and components already in the codebase are skipped unless **`overwrite`**. Options: **`projectDir`**, **`componentDir`** (`src/components/ui`), **`stylesPath`** (`src/styles/globals.css`), **`tailwindConfigPath`** (`tailwind.config.ts`), **`limit`** (30, max 100); frameworks `react-tailwind`, `react-shadcn`, `vue-tailwind`, `html`.
+- **`target: "project"`**: scaffold a design system — `globals.css` (Tailwind layers + CSS variables), `tailwind.config.ts` and one component per local component / component set in `componentDir`. For React, a component set becomes one component whose props (`size`, `state`, ...) pick the variant, each variant generated from its own node (up to 24); Vue/HTML use the default variant. Existing files and components already in the codebase are skipped unless **`overwrite`**. Options: **`projectDir`**, **`componentDir`** (`src/components/ui`), **`stylesPath`** (`src/styles/globals.css`), **`tailwindConfigPath`** (`tailwind.config.ts`), **`limit`** (30, max 100); frameworks `react-tailwind`, `react-shadcn`, `vue-tailwind`, `html`.
 
 Token exports use schema v2 and preserve full paint/effect stacks, alpha, gradient
 transforms, collection modes and raw alias values. CSS, Tailwind, TypeScript and
@@ -440,8 +439,18 @@ cargo build --release
 
 # Rebuild Figma plugin bundle (if plugin-src/ is modified)
 node scripts/build-plugin.js
+
+# Codegen accuracy: render html output in headless Chrome and compare every
+# layer (size, padding, gap, radius, typography, colors) with the spec
+npm run accuracy                                  # bundled fixture
+npm run accuracy -- path/to/context.json --all    # your own get_design_context dump
 ```
 
+`npm run accuracy` needs Chrome (`CHROME_PATH` to override) and network access
+for the Tailwind play CDN and Google Fonts. `--min <percent>` fails below a
+threshold. The bundled checkout fixture currently matches 98.9% of 981 checks;
+remaining misses are sub-pixel text metrics.
+
 ---
 
 ## 📄 License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "figma-rust-mcp",
-  "version": "7.0.0",
+  "version": "8.0.0",
   "description": "Claude Code to Figma — Bidirectional MCP bridge. AI draws UI on Figma canvas, reads designs back. Works with Claude, Cursor, VS Code, Windsurf, Antigravity. No API key needed.",
   "mcpName": "io.github.BuiHung1612/figma-rust-mcp",
   "type": "module",
@@ -21,7 +21,8 @@
     "test:tokens": "node --test scripts/test-plugin-tokens.mjs && cargo test",
     "dev": "cargo run",
     "bench": "cargo build --release && node scripts/bench.mjs",
-    "test:sessions": "cargo build && node --test scripts/test-bridge-sessions.mjs"
+    "test:sessions": "cargo build && node --test scripts/test-bridge-sessions.mjs",
+    "accuracy": "cargo build && node scripts/codegen-accuracy.mjs"
   },
   "engines": {
     "node": ">=18"

package/scripts/codegen-accuracy.mjs

@@ -0,0 +1,182 @@
+// Measures figma_to_code accuracy: renders html-annotated output in headless Chrome
+// and compares every layer's box and styles with the get_design_context spec.
+//   node scripts/codegen-accuracy.mjs [context.json ...] [--min <percent>] [--all]
+// Default context: tests/fixtures/design-context-checkout.json. Needs Chrome and
+// network access for the Tailwind play CDN and Google Fonts.
+import { execFileSync, spawn } from 'node:child_process';
+import { mkdtempSync, readFileSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+const args = process.argv.slice(2);
+const minIndex = args.indexOf('--min');
+const min = minIndex >= 0 ? Number(args.splice(minIndex, 2)[1]) : null;
+const showAll = args.includes('--all') && args.splice(args.indexOf('--all'), 1);
+const files = args.length ? args : ['tests/fixtures/design-context-checkout.json'];
+const binary = process.env.FIGMA_TEST_BINARY || 'target/debug/figma-rust-mcp';
+const chromePath = process.env.CHROME_PATH || {
+  darwin: '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+  win32: 'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe',
+}[process.platform] || 'google-chrome';
+
+const px = v => (typeof v === 'number' ? v : parseFloat(v));
+const box = v => { const p = String(v ?? '').trim().split(/\s+/).map(px); return [p[0], p[1] ?? p[0], p[2] ?? p[0], p[3] ?? p[1] ?? p[0]]; };
+const rgb = hex => { const h = hex.replace('#', ''); return `rgb(${parseInt(h.slice(0, 2), 16)}, ${parseInt(h.slice(2, 4), 16)}, ${parseInt(h.slice(4, 6), 16)})`; };
+const WEIGHTS = { thin: 100, extralight: 200, light: 300, regular: 400, normal: 400, medium: 500, semibold: 600, bold: 700, extrabold: 800, black: 900 };
+
+function walk(node, out = []) {
+  out.push(node);
+  for (const child of node.children || []) walk(child, out);
+  return out;
+}
+
+// Tokens resolve through the layer's own solid paint, so colors compare as rendered.
+function tokenCss(layers) {
+  const vars = new Map();
+  for (const n of layers) {
+    const color = n.paintData?.find(p => p.type === 'SOLID' && p.color)?.color;
+    for (const ref of [n.fill, n.text?.color]) {
+      const name = /^var\((--[^)]+)\)$/.exec(ref || '')?.[1];
+      if (name && color && /^#[0-9a-f]{6}$/i.test(color)) vars.set(name, color);
+    }
+  }
+  return `:root{${[...vars].map(([k, v]) => `${k}:${v}`).join(';')}}`;
+}
+
+function resolveColor(value, layer) {
+  if (!value) return null;
+  if (value.startsWith('var(')) value = layer.paintData?.find(p => p.type === 'SOLID')?.color;
+  return value && /^#[0-9a-f]{6}$/i.test(value) ? rgb(value) : null;
+}
+
+// One entry per measurable property: [group, expected, actual, tolerance].
+function checks(layer, got) {
+  const out = [];
+  const num = (group, expected, actual, tol = 1) => {
+    if (Number.isFinite(expected)) out.push([group, expected, actual, tol]);
+  };
+  num('width', layer.size?.width, got.width);
+  num('height', layer.size?.height, got.height);
+  const layout = layer.layout;
+  if (layout?.padding) box(layout.padding).forEach((v, i) => num('padding', v, got.padding[i], 0.5));
+  if (layout?.display === 'flex' && layout.gap != null) {
+    num('gap', px(layout.gap), layout.flexDirection === 'column' ? got.rowGap : got.columnGap, 0.5);
+  }
+  // Browsers clamp radii to half the shorter side (rounded-full is 9999px); compare what renders.
+  const clamp = v => Math.min(v, Math.min(got.width, got.height) / 2);
+  if (layer.borderRadius) box(layer.borderRadius).forEach((v, i) => num('radius', clamp(v), clamp(got.radius[i]), 0.5));
+  const text = layer.text;
+  if (layer.type === 'TEXT' && text) {
+    num('fontSize', text.fontSize, got.fontSize, 0.1);
+    num('fontWeight', text.fontWeightNumeric ?? WEIGHTS[String(text.fontWeight).toLowerCase().replace(/\s/g, '')], got.fontWeight, 0);
+    if (String(text.lineHeight).endsWith('%')) num('lineHeight', text.fontSize * px(text.lineHeight) / 100, got.lineHeight, 0.5);
+    else if (text.lineHeight != null && text.lineHeight !== 'auto') num('lineHeight', px(text.lineHeight), got.lineHeight, 0.5);
+    const color = resolveColor(text.color, layer);
+    if (color) out.push(['color', color, got.color, 0]);
+  } else if (layer.backgroundCss?.property === 'background-color') {
+    const bg = resolveColor(layer.backgroundCss.value, layer);
+    if (bg) out.push(['background', bg, got.background, 0]);
+  }
+  return out;
+}
+
+async function launchChrome() {
+  const profile = mkdtempSync(join(tmpdir(), 'codegen-accuracy-'));
+  const chrome = spawn(chromePath, ['--headless=new', '--remote-debugging-port=0', `--user-data-dir=${profile}`, '--hide-scrollbars', 'about:blank'], { stdio: ['ignore', 'ignore', 'pipe'] });
+  const port = await new Promise((resolve, reject) => {
+    let log = '';
+    chrome.stderr.on('data', b => { log += b; const m = /DevTools listening on ws:\/\/[^:]+:(\d+)/.exec(log); if (m) resolve(m[1]); });
+    chrome.on('exit', code => reject(new Error(`Chrome exited (${code}): ${log.slice(-500)}`)));
+  });
+  return { chrome, port };
+}
+
+async function cdpPage(port) {
+  const target = await (await fetch(`http://127.0.0.1:${port}/json/new?about:blank`, { method: 'PUT' })).json();
+  const ws = new WebSocket(target.webSocketDebuggerUrl);
+  await new Promise((resolve, reject) => { ws.onopen = resolve; ws.onerror = reject; });
+  let id = 0;
+  const pending = new Map();
+  const events = [];
+  ws.onmessage = e => {
+    const msg = JSON.parse(e.data);
+    if (msg.id && pending.has(msg.id)) { pending.get(msg.id)(msg); pending.delete(msg.id); } else events.push(msg);
+  };
+  const send = (method, params = {}) => new Promise((resolve, reject) => {
+    const msgId = ++id;
+    pending.set(msgId, msg => (msg.error ? reject(new Error(`${method}: ${msg.error.message}`)) : resolve(msg.result)));
+    ws.send(JSON.stringify({ id: msgId, method, params }));
+  });
+  return { send, events, close: () => ws.close() };
+}
+
+const MEASURE = `(() => [...document.querySelectorAll('[data-node-id]')].map(el => {
+  const r = el.getBoundingClientRect(), s = getComputedStyle(el), n = v => parseFloat(v) || 0;
+  return { id: el.dataset.nodeId, width: r.width, height: r.height,
+    padding: [n(s.paddingTop), n(s.paddingRight), n(s.paddingBottom), n(s.paddingLeft)],
+    rowGap: n(s.rowGap), columnGap: n(s.columnGap),
+    radius: [n(s.borderTopLeftRadius), n(s.borderTopRightRadius), n(s.borderBottomRightRadius), n(s.borderBottomLeftRadius)],
+    fontSize: n(s.fontSize), fontWeight: n(s.fontWeight), lineHeight: s.lineHeight === 'normal' ? NaN : n(s.lineHeight),
+    color: s.color, background: s.backgroundColor };
+}))()`;
+
+async function measure(page, file) {
+  const raw = JSON.parse(readFileSync(file, 'utf8'));
+  const root = raw.context || raw;
+  const layers = walk(root);
+  const html = execFileSync(binary, ['--codegen', 'html-annotated', file], { encoding: 'utf8' });
+  const families = [...new Set(layers.map(n => n.text?.fontFamily).filter(Boolean))];
+  const fonts = families.map(f => `family=${encodeURIComponent(f)}:ital,wght@0,100;0,300;0,400;0,700;0,900;1,400`).join('&');
+  const doc = `<!doctype html><html><head><meta charset="utf-8">
+<script src="https://cdn.tailwindcss.com/3.4.17"></script>
+${fonts ? `<link rel="stylesheet" href="https://fonts.googleapis.com/css2?${fonts}&display=block">` : ''}
+<style>${tokenCss(layers)} body{margin:0}</style></head><body>${html}</body></html>`;
+  const path = join(mkdtempSync(join(tmpdir(), 'codegen-page-')), 'index.html');
+  writeFileSync(path, doc);
+  const width = Math.ceil(root.size?.width || 1440);
+  await page.send('Emulation.setDeviceMetricsOverride', { width, height: Math.ceil(root.size?.height || 900), deviceScaleFactor: 1, mobile: false });
+  await page.send('Page.navigate', { url: `file://${path}` });
+  await page.send('Runtime.evaluate', { expression: 'new Promise(r => (document.readyState === "complete" ? r() : addEventListener("load", r))).then(() => document.fonts.ready).then(() => new Promise(r => setTimeout(r, 300)))', awaitPromise: true });
+  const { result } = await page.send('Runtime.evaluate', { expression: MEASURE, returnByValue: true });
+  const rendered = new Map(result.value.map(m => [m.id, m]));
+  const byGroup = new Map();
+  const misses = [];
+  let missing = 0;
+  for (const layer of layers) {
+    const got = rendered.get(layer.id);
+    if (!got) { if (layer.id && !layer.isMask) missing++; continue; }
+    for (const [group, expected, actual, tol] of checks(layer, got)) {
+      const ok = typeof expected === 'number' ? Math.abs(expected - actual) <= tol : expected === actual;
+      const g = byGroup.get(group) || { pass: 0, total: 0 };
+      g.total++; if (ok) g.pass++;
+      byGroup.set(group, g);
+      if (!ok) misses.push({ group, layer: `${layer.name} (${layer.id})`, expected, actual: typeof actual === 'number' ? Math.round(actual * 100) / 100 : actual });
+    }
+  }
+  return { byGroup, misses, missing, layers: layers.length };
+}
+
+const { chrome, port } = await launchChrome();
+let worst = 100;
+try {
+  const page = await cdpPage(port);
+  await page.send('Page.enable');
+  for (const file of files) {
+    const { byGroup, misses, missing, layers } = await measure(page, file);
+    const pass = [...byGroup.values()].reduce((a, g) => a + g.pass, 0);
+    const total = [...byGroup.values()].reduce((a, g) => a + g.total, 0);
+    const pct = total ? (pass * 100) / total : 0;
+    worst = Math.min(worst, pct);
+    console.log(`\n${file}: ${pct.toFixed(1)}% of ${total} checks match (${layers} layers${missing ? `, ${missing} not rendered` : ''})`);
+    for (const [group, g] of [...byGroup].sort()) console.log(`  ${group.padEnd(11)} ${String(g.pass).padStart(4)}/${String(g.total).padEnd(4)} ${((g.pass * 100) / g.total).toFixed(1)}%`);
+    for (const m of showAll ? misses : misses.slice(0, 12)) console.log(`  ✗ ${m.group} ${m.layer}: expected ${m.expected}, got ${m.actual}`);
+    if (!showAll && misses.length > 12) console.log(`  … ${misses.length - 12} more`);
+  }
+  page.close();
+} finally {
+  chrome.kill();
+}
+if (min != null && worst < min) {
+  console.error(`\nAccuracy ${worst.toFixed(1)}% is below --min ${min}%`);
+  process.exit(1);
+}

package/scripts/test-plugin-tokens.mjs

@@ -54,6 +54,17 @@ test('compact tree and scan preserve mixed typography instead of using the first
   assert.equal(r.resolveTextStyle(node).fontWeight, undefined);
 });
 
+test('text list formatting is reported only when every paragraph shares it', () => {
+  const r = runtime({ root: { id: '0:0' }, currentPage: { id: '0:1' } });
+  vm.runInContext(readFileSync('plugin-src/read-helpers.js', 'utf8'), r);
+  const text = lists => ({ type: 'TEXT', characters: 'Account', fontSize: 16, fontName: { family: 'Lato', style: 'Regular' },
+    getStyledTextSegments: () => lists.map(type => ({ listOptions: { type } })) });
+  assert.equal(r.resolveTextStyle(text(['UNORDERED'])).listType, 'UNORDERED');
+  assert.equal(r.resolveTextStyle(text(['ORDERED', 'ORDERED'])).listType, 'ORDERED');
+  assert.equal(r.resolveTextStyle(text(['UNORDERED', 'NONE'])).listType, undefined);
+  assert.equal(r.resolveTextStyle(text(['NONE'])).listType, undefined);
+});
+
 test('scan_design expands instances by default and flags opaque ones as incomplete', async () => {
   const text = { id: '1:3', name: 'Label', type: 'TEXT', characters: 'Hi', fontSize: 12, fontName: { family: 'Inter', style: 'Regular' }, visible: true };
   const inst = { id: '1:2', name: 'Button', type: 'INSTANCE', visible: true, children: [text], getMainComponentAsync: async () => null };