figma-rust-mcp 6.0.0 → 8.0.0

package/README.md

@@ -8,14 +8,14 @@ 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_index`)**: Indexes page roots first and loads frame descendants on demand. Search reports the indexed scope and completeness.
+- **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.
 - **Revisioned Updates**: Property patches update affected nodes; revision gaps trigger a fresh snapshot.
 - **Instant Design-to-Code (`figma_to_code`)**: Compiles Figma frames into clean, semantic components (**React + Tailwind**, **React Native**, **Vue 3 + Tailwind**, **HTML**, **SwiftUI**).
-- **Design Token Exporter (`figma_get_tokens`)**: Exports variables and styles to **Tailwind config**, **CSS custom properties** (`:root` & dark mode), **TypeScript consts**, or **W3C DTCG Token Studio JSON**.
-- **Batch Asset Extractor (`figma_export_assets` / `figma_export_asset`)**: Extracts SVG icons and raster images directly to project folders (`outputPath`) with auto-generated TypeScript barrel exports (`index.ts`) — zero chat token bloating.
+- **Design Token Exporter (`figma_to_code` `target: "tokens"`)**: Exports variables and styles to **Tailwind config**, **CSS custom properties** (`:root` & dark mode), **TypeScript consts**, or **W3C DTCG Token Studio JSON**.
+- **Batch Asset Extractor (`figma_prepare_design` `only: "assets"`)**: Extracts SVG icons and raster images directly to project folders (`outputPath`) with auto-generated TypeScript barrel exports (`index.ts`) — zero chat token bloating.
 - **Sandboxed JS Drawing Engine (`figma_write`)**: Powered by **Boa** (pure Rust ECMAScript engine) with built-in asset resolvers and 7 icon packs (*Ionicons, Lucide, Tabler, Bootstrap, Fluent, Phosphor*).
 - **Multi-Tab / Multi-Session Support**: Seamlessly connects to multiple open Figma files simultaneously.
 - **100% Localhost Privacy**: All communication stays strictly on `127.0.0.1:41730`.
@@ -212,25 +212,57 @@ Figma plugin only if the reported hash does not change.
 
 ## 🛠️ MCP Tools Reference
 
-`figma-rust-mcp` provides **15 first-class MCP tools**:
+`figma-rust-mcp` exposes **7 tools**. Each covers one job; modes select the
+variant (`operation`, `task`, `only`, `target`). The plugin **Usage** tab shows
+how often each tool and mode is called.
 
 ### 1. `figma_status`
-Checks live bridge connection status, connected Figma tabs/files, in-memory index health, queue length, and latency statistics.
+Bridge connection, connected tabs (`sessionId`), index health, queue length and latency.
+- **`task`**: `"start"` (with `frameId`) reserves a frame and returns a `taskId`; `"end"` (with `taskId`) releases it; `"list"` shows reservations. See [Multiple tabs and frame tasks](#multiple-tabs-and-frame-tasks).
+
+### 2. `figma_read`
+Every read, search and export. **`operation`**:
+- **Nodes**: `read_nodes` (canonical flat API), `inspect_node` (one node with CSS, layout, tokens, typography; defaults to the selection), `get_selection`, `get_spec`, `get_page_nodes`, `scan_design`, `get_css`.
+- **Search** (in-memory index): `search_nodes` (`query`, `nodeType`), `search_components`, `search_styles` (`styleType`), `search_variables` (`collection`), `subtree`, `typography` (text/font table with mixed runs), `index_status` (index health, cache hits, tool timings), `refresh` (page roots, or expand `nodeId`; `includeComponents`).
+- **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.
+
+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.
+- Supports Auto-layout (`layoutMode`, `itemSpacing`, `padding`), typography, fills, strokes, corner radius, drop shadows, and component creation.
+- Supports icon loading: `figma.loadIcon("ionicons", "heart", { size: 24, fill: "#ff4757" })`.
+- Supports image insertion: `figma.loadImage(url, { width: 300, height: 200 })`.
+- Supports Design Tokens: `createVariableCollection`, `createVariable`, `addVariableMode`, `applyVariable`.
+- Supports Prototyping & Reactions: `setReactions`, `getReactions`, `setScrollBehavior`.
 
-### 2. `figma_inspect_node`
-Reads a specific node by ID or name through the canonical flat `read_nodes` response. Select fields explicitly to control the work performed.
+### 4. `figma_docs`
+Built-in documentation, design rules, layout guidelines and examples for `figma_write`.
+- **`section`**: `"rules"` | `"layout"` | `"api"` | `"tokens"` | `"icons"`
 
-### 3. `figma_to_code`
-Compiles any Figma node (Frame, Component, Section, or selection) directly into clean, production-ready component code.
-- **`framework`**: `"react-tailwind"` (default), `"react-native"`, `"vue-tailwind"`, `"html"`, `"swiftui"`.
-- **`outputPath`**: Directly saves the generated component to your codebase (e.g. `src/components/UserProfileCard.tsx`).
-- **`componentName`**: Custom component name override.
+### 5. `figma_prepare_design`
+**Start here for design-to-code.** One call returns a grounding pack: screenshot, every visible text (through expanded instances, with coverage), SVG icons exported to `iconDir` with import statements, matched codebase components and an implementation checklist.
+- **`nodeId`**, **`iconDir`** (default `src/assets/icons`), **`projectDir`** (default `.`), **`detail`**, **`outputPath`**.
+- **`only: "assets"`**: just export SVG icons (`iconDir`) and raster images (`imageDir`, default `public/images`) with an `index.ts` barrel (`createBarrel`).
+- **`only: "components"`**: just list codebase components (`src/components`, `components`, ...) and match `nodeId` against them.
 
-### 4. `figma_get_tokens`
-Exports Figma Variables (Design Tokens), Color Styles, Typography Styles, and Elevation/Shadow Styles directly into frontend code.
-- **`format`**: `"tailwind"` (`tailwind.config.js` theme.extend), `"css"` (`:root` CSS custom properties with light/dark theme modes), `"typescript"` (`tokens.ts`), `"w3c"` (W3C DTCG Token Studio JSON), or `"json"`.
-- **`outputPath`**: Writes directly to disk (e.g. `src/styles/tokens.css` or `tailwind.config.js`).
-- **`collection`** / **`mode`** / **`prefix`**: Optional filters and naming prefixes.
+### 6. `figma_to_code`
+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 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
@@ -252,99 +284,26 @@ Run `npm run build:plugin` after changing plugin source, and `npm run test:token
 for the token/contract/version regression suite. Existing background servers need
 a restart with the new binary to load the updated runtime.
 
+### 7. `figma_verify_ui`
+Compares rendered HTML/React styles against the Figma spec: size, per-side padding, gap, colors, per-corner radius and typography. Returns a match percentage, discrepancies and CSS/Tailwind fixes.
+- **`nodeId`** / **`nodeName`**, **`computedStyles`**, **`url`** / **`selector`**.
+- Typography: pass a text `nodeId` and browser `computedStyles` (`font-size` in px, numeric `font-weight`, `font-family`). Mixed text accepts `computedStyles.segments`, an ordered array matching the Figma runs. Fractional pixels are preserved.
 
-### 5. `figma_get_selection`
-Inspection of currently selected layers/frames, with shared-style compression when it reduces response size.
-- **`detail`**: `"compact"` (default), `"minimal"`, `"full"`.
-
-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.
-- **`depth`**: Tree depth limit or `"full"`.
-
-### 6. `figma_export_asset`
-Exports any Figma node/layer directly into PNG, JPG, or SVG.
-- **`outputPath`**: When specified (e.g. `src/assets/logo.png`), saves directly to disk and returns minimal JSON metadata instead of bloating context with large base64 strings.
-- **`format`**: `"png"` (default), `"jpg"`, `"svg"`.
-- **`scale`**: Scaling factor (default `2` for high-res).
-
-### 7. `figma_export_assets`
-Batch extracts all SVG icons and PNG images from a Figma frame/page directly into project directories.
-- **`iconDir`**: Directory path for SVG icons (e.g. `src/assets/icons`).
-- **`imageDir`**: Directory path for raster images (e.g. `public/images`).
-- **`createBarrel`**: Automatically creates an `index.ts` barrel export file in `iconDir`.
-
-### 8. `figma_index`
-In-memory queries against pre-indexed Figma file structures (latency for your file: plugin **Bench** tab).
-- **`operation`**:
-  - `"status"`: View index health and node counts.
-  - `"search_nodes"`: Search nodes by text name, query, and type (`FRAME`, `TEXT`, `COMPONENT`, `INSTANCE`).
-  - `"get_node"`: Instant node lookup by ID.
-  - `"search_components"`: Find component sets and variants.
-  - `"search_styles"`: Find paint, text, and effect styles.
-  - `"search_variables"`: Find design token variables by name or collection.
-  - `"refresh"`: Refresh page roots, or expand the frame specified by `nodeId`.
-  - `"subtree"`: Read/cache one `nodeId`, default depth 2 and 1000 nodes. Increase `depth` or `maxNodes` only for the section you need; check `meta` for truncation.
-  - `"typography"`: Rust-generated text/font table for one `nodeId`, with mixed-style runs preserved. Default limit 200 rows. Null font fields mean unknown/mixed, not a guessed default.
-
-`status` includes per-tab dispatch cache hits/misses, bridge calls and total bridge wait time, plus process-wide tool call counts and total/average milliseconds. Node changes invalidate related subtrees; style changes, unknown events and global writes invalidate the whole cache. Detailed subtree data is loaded on demand. The initial index remains shallow.
-
-For typography verification, call `figma_verify_ui` with a text `nodeId` and browser `computedStyles` (`font-size` in px, numeric `font-weight`, `font-family`). Mixed text accepts `computedStyles.segments`, an ordered array of CSS objects matching the Figma runs. Size checks preserve fractional pixels.
-
-### 9. `figma_read`
-Universal reader for advanced queries:
-- **Design-to-code**: `read_nodes`, `get_css`, `get_component_map`, `get_unmapped_components`.
-- **Inspection & Hierarchy**: `read_nodes`, `get_selection`, `get_page_nodes`, `scan_design`, `search_nodes`.
-- **Design Systems**: `get_styles`, `get_variables`, `get_local_components`, `get_tokens`.
-- **Visuals & Canvas**: `screenshot`, `export_svg`, `export_image`, `get_viewport`.
-
-### 10. `figma_write`
-Executes JavaScript draw commands inside the sandboxed VM to build or modify designs on the Figma canvas.
-- Supports Auto-layout (`layoutMode`, `itemSpacing`, `padding`), typography, fills, strokes, corner radius, drop shadows, and component creation.
-- Supports icon loading: `figma.loadIcon("ionicons", "heart", { size: 24, fill: "#ff4757" })`.
-- Supports image insertion: `figma.loadImage(url, { width: 300, height: 200 })`.
-- Supports Design Tokens: `createVariableCollection`, `createVariable`, `addVariableMode`, `applyVariable`.
-- Supports Prototyping & Reactions: `setReactions`, `getReactions`, `setScrollBehavior`.
-
-### 11. `figma_rules`
-Audits the current Figma document and generates a complete design system rule sheet (color tokens, typography styles, variables, component catalog) from the in-memory cache.
+### Legacy tool names
 
-### 12. `figma_docs`
-Fetches built-in documentation, design rules, layout guidelines, and code examples for `figma_write`.
-- **`section`**: `"rules"` | `"layout"` | `"api"` | `"tokens"` | `"icons"`
+Tools from v6 and earlier are hidden from `tools/list` but still accepted, so existing prompts keep working:
 
-### 13. `figma_verify_ui`
-Validates and compares actual rendered HTML/React UI styles and layout against Figma design specifications.
-- Checks dimensions, padding, flex gap, colors, border-radius, and typography.
-- Returns an exact match percentage (`match_percentage`), discrepancy breakdown, and actionable CSS/Tailwind fixes.
-- **`nodeId`** / **`nodeName`**: Target Figma node spec.
-- **`computedStyles`**: Key-value pairs of computed CSS properties from browser/component inspection.
-- **`url`** / **`selector`**: Contextual target URL or CSS selector inspected.
-
-### 14. `figma_match_components`
-Scans your local codebase directories (`src/components`, `components/ui`) to discover existing React/Vue components and matches them directly against Figma design layers, preventing duplicate component creation and ensuring reuse of existing design systems.
-- **`projectDir`**: Base directory of your project (default: current directory `"."`).
-- **`nodeId`**: Optional Figma node ID to check specific match against local components.
-
-### 15. `figma_prepare_design`
-**All-In-One Multimodal Grounding Pack for AI**: The ultimate single-call tool for code generation that eliminates missing UI elements and icon guesswork.
-- Simultaneously extracts **100% of visible text elements** (greeting, badges, timestamps, labels).
-- Automatically **exports all SVG vector icons** into your local project directory (`iconDir`) and provides exact TypeScript import statements.
-- Captures high-res **visual canvas screenshots** saved locally for immediate multimodal LLM inspection.
-- Discovers existing components in your codebase for direct reuse.
-- Generates an actionable **Implementation Checklist** ensuring complete design fidelity in 1 single shot.
-- **`nodeId`**: Target Figma screen/frame ID.
-- **`iconDir`**: Target directory for SVG icons (e.g. `src/assets/icons` or `assets/images`).
-- **`projectDir`**: Base directory for component discovery.
+| v6 tool | v7 call |
+|---|---|
+| `figma_get_selection` | `figma_read` `operation: "get_selection"` |
+| `figma_inspect_node` | `figma_read` `operation: "inspect_node"` |
+| `figma_export_asset` | `figma_read` `operation: "export_image"` / `"export_svg"` |
+| `figma_index` | `figma_read` search operations, `index_status`, `refresh` |
+| `figma_rules` | `figma_read` `operation: "rules"` |
+| `figma_get_tokens` | `figma_to_code` `target: "tokens"` |
+| `figma_export_assets` | `figma_prepare_design` `only: "assets"` |
+| `figma_match_components` | `figma_prepare_design` `only: "components"` |
+| `figma_task` | `figma_status` `task: "start" \| "end" \| "list"` |
 
 ---
 
@@ -354,13 +313,13 @@ Each plugin runtime has its own `sessionId`; tabs of the same file share a
 `documentId`. Use `figma_status` to discover tabs. With multiple connected tabs,
 pass an exact `sessionId`; the server rejects ambiguous routing.
 
-For multiple agents editing one file, call `figma_task` with `action: "start"`,
+For multiple agents editing one file, call `figma_status` with `task: "start"`,
 `sessionId` and `frameId`, then pass the returned `taskId` on subsequent tools.
 Each task reserves a separate FRAME directly under a PAGE or SECTION, without
 shared component definitions. Writes stay inside that frame; global styles,
 variables, page and selection changes are blocked. A frame cannot be reserved
-twice, including across tabs of the same document. Release it with `figma_task`
-using `action: "end"` and `taskId`; restart tasks after a plugin reload.
+twice, including across tabs of the same document. Release it with `figma_status`
+using `task: "end"` and `taskId`; restart tasks after a plugin reload.
 
 Tools on one tab run sequentially, including every awaited operation in a
 `figma_write` call. Different tabs run independently. `npm run test:sessions`
@@ -373,14 +332,14 @@ Version 4 requires both server and plugin runtime protocol 3. Update both and
 restart the plugin. Opening the bridge indexes only visible top-level nodes on
 the active page, plus local styles and variables. Selection expands the selected
 frame. Component catalogue discovery is deferred; request it with
-`figma_index({ operation: "refresh", includeComponents: true })`.
+`figma_read({ operation: "refresh", includeComponents: true })`.
 
 Search covers indexed scopes only. Inspect `scope` and `complete` in search
 responses; an empty result does not prove a layer is absent from the file.
 Refresh a specific frame to expand its scope:
 
 ```js
-figma_index({ operation: "refresh", nodeId: "123:456", expandInstances: true })
+figma_read({ operation: "refresh", nodeId: "123:456", expandInstances: true })
 figma_read({ operation: "read_nodes", nodeId: "123:456",
   fields: ["geometry", "content", "text", "style", "layout", "tokens", "component"],
   limit: 200, expandInstances: true })
@@ -406,9 +365,9 @@ options; no master component is substituted for an instance.
 
 Breaking output changes: public `get_design`, `get_design_context` and
 `get_node_detail` aliases now return the same envelope as `read_nodes`.
-`figma_inspect_node` and index `get_node`, `subtree`, `typography` also return
+`figma_read` `inspect_node`, `subtree` and `typography` also return
 that envelope. Replace nested `children` consumers with `nodes` and parent/child
-IDs. Replace index `maxNodes` with `limit` and cursor pagination. Internal
+IDs. Replace `subtree` `maxNodes` with `limit` and cursor pagination. Internal
 script helpers used for code generation retain their specialized formats.
 
 Canvas traversal reads each child list once, yields after an 8ms slice, and
@@ -480,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": "6.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-bridge-sessions.mjs

@@ -3,9 +3,14 @@ import assert from 'node:assert/strict';
 import { spawn } from 'node:child_process';
 import { createServer } from 'node:net';
 import { createInterface } from 'node:readline';
-import { readFileSync } from 'node:fs';
+import { mkdtempSync, readFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
 import vm from 'node:vm';
 
+// Spawned servers persist tool usage under HOME; keep the user's real file untouched.
+process.env.HOME = process.env.USERPROFILE = mkdtempSync(join(tmpdir(), 'figma-mcp-test-'));
+
 const delay = ms => new Promise(resolve => setTimeout(resolve, ms));
 const deferred = () => { let resolve; const promise = new Promise(r => { resolve = r; }); return { promise, resolve }; };
 async function until(predicate) {
@@ -106,11 +111,11 @@ test('multiple tabs, reconnect ownership and independent frame tasks across MCP
   assert.equal(ambiguous.isError, true); assert.match(ambiguous.content[0].text, /Ambiguous/);
   const missing = await rpc('figma_read', { operation: 'get_design', sessionId: 'missing' });
   assert.equal(missing.isError, true);
-  const taskA = decode(ok(await first('figma_task', { action: 'start', sessionId: 'tab-a', frameId: 'frame-a' })));
-  const collision = await second('figma_task', { action: 'start', sessionId: 'tab-b', frameId: 'frame-a' });
+  const taskA = decode(ok(await first('figma_status', { task: 'start', sessionId: 'tab-a', frameId: 'frame-a' })));
+  const collision = await second('figma_status', { task: 'start', sessionId: 'tab-b', frameId: 'frame-a' });
   assert.equal(collision.isError, true); assert.match(collision.content[0].text, /reserved/);
-  const taskB = decode(ok(await second('figma_task', { action: 'start', sessionId: 'tab-a', frameId: 'frame-b' })));
-  const taskC = decode(ok(await rpc('figma_task', { action: 'start', sessionId: 'tab-b', frameId: 'frame-c' })));
+  const taskB = decode(ok(await second('figma_status', { task: 'start', sessionId: 'tab-a', frameId: 'frame-b' })));
+  const taskC = decode(ok(await rpc('figma_status', { task: 'start', sessionId: 'tab-b', frameId: 'frame-c' })));
   assert.equal(decode(ok(await first('figma_get_selection', { taskId: taskA.taskId }))).id, 'frame-a');
   assert.equal(decode(ok(await second('figma_get_selection', { taskId: taskB.taskId }))).id, 'frame-b');
   const writeA = first('figma_write', { taskId: taskA.taskId, code: 'await figma.modify({id:"child-a",note:"paused"}); await figma.modify({id:"child-a",note:"second"});' });
@@ -149,14 +154,14 @@ test('multiple tabs, reconnect ownership and independent frame tasks across MCP
   tabA.socket.send(JSON.stringify({ id: waiting.id, sessionId: 'tab-a', success: true, data: { id: 'frame-a', tab: 'tab-a' } }));
   assert.equal(decode(ok(await routed)).tab, 'tab-a');
   assert.ok(ignored.id);
-  ok(await first('figma_task', { action: 'end', taskId: taskA.taskId }));
-  ok(await second('figma_task', { action: 'end', taskId: taskB.taskId }));
+  ok(await first('figma_status', { task: 'end', taskId: taskA.taskId }));
+  ok(await second('figma_status', { task: 'end', taskId: taskB.taskId }));
   tabB.socket.close();
   await until(async () => !(await (await fetch(`${base}/sessions`)).json()).sessions.find(session => session.id === 'tab-b').connected);
-  assert.equal(decode(ok(await rpc('figma_task', { action: 'end', taskId: taskC.taskId }))).pluginDisconnected, true);
+  assert.equal(decode(ok(await rpc('figma_status', { task: 'end', taskId: taskC.taskId }))).pluginDisconnected, true);
   await plugin('tab-b', tabB);
-  const restarted = decode(ok(await rpc('figma_task', { action: 'start', sessionId: 'tab-b', frameId: 'frame-c' })));
-  ok(await rpc('figma_task', { action: 'end', taskId: restarted.taskId }));
+  const restarted = decode(ok(await rpc('figma_status', { task: 'start', sessionId: 'tab-b', frameId: 'frame-c' })));
+  ok(await rpc('figma_status', { task: 'end', taskId: restarted.taskId }));
 });
 
 test('index sync travels from plugin through UI to bridge and returns a matching confirmation', { timeout: 20000 }, async t => {

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 };

package/scripts/test-rust-mcp.sh

@@ -22,13 +22,13 @@ INPUT=$(cat << 'JSON'
 JSON
 )
 
-OUTPUT=$(echo "$INPUT" | $BIN_PATH --port 38499 2>/dev/null)
+OUTPUT=$(echo "$INPUT" | HOME="$(mktemp -d)" $BIN_PATH --port 38499 2>/dev/null)
 echo "$OUTPUT" | head -n 4
 
 # Verify tool registration in JSON-RPC output
-echo "--- Test 3: Verify Tool Registrations (15 tools) ---"
-for TOOL in figma_status figma_get_selection figma_inspect_node figma_to_code figma_get_tokens figma_export_asset figma_export_assets figma_index figma_read figma_write figma_rules figma_docs figma_match_components figma_prepare_design figma_verify_ui; do
-  echo "$OUTPUT" | grep -q "\"name\":\"$TOOL\"" && echo "✓ $TOOL registered"
+echo "--- Test 3: Verify Tool Registrations (7 tools) ---"
+for TOOL in figma_status figma_read figma_write figma_docs figma_prepare_design figma_to_code figma_verify_ui; do
+  echo "$OUTPUT" | grep -q "\"name\":\"$TOOL\"" && echo "✓ $TOOL registered" || { echo "✗ $TOOL missing"; exit 1; }
 done
 
 # Test 4: Node/NPX wrapper test