figma-rust-mcp 5.1.1 → 7.0.0

package/README.md

@@ -10,12 +10,12 @@ Enables AI agents (Google Antigravity, Claude Code, Cursor, Windsurf, VS Code, Z
 
 - **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.
 - **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,58 @@ 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_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.
+### 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.
 
-### 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.
+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.
+
+### 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`.
+
+### 4. `figma_docs`
+Built-in documentation, design rules, layout guidelines and examples for `figma_write`.
+- **`section`**: `"rules"` | `"layout"` | `"api"` | `"tokens"` | `"icons"`
+
+### 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 (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`.
 
 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 +285,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"`.
+### Legacy tool names
 
-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.
+Tools from v6 and earlier are hidden from `tools/list` but still accepted, so existing prompts keep working:
 
-### 12. `figma_docs`
-Fetches built-in documentation, design rules, layout guidelines, and code examples for `figma_write`.
-- **`section`**: `"rules"` | `"layout"` | `"api"` | `"tokens"` | `"icons"`
-
-### 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 +314,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 +333,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 +366,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "figma-rust-mcp",
-  "version": "5.1.1",
+  "version": "7.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",

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

@@ -10,7 +10,7 @@ import { configureAgent, detectAgents } from '../bin/agent-config.js';
 import { parse as parseJsonc } from 'jsonc-parser';
 
 function runtime(figma = {}) {
-  const context = vm.createContext({ figma, handlers: {}, console, setTimeout, Map, Set, Uint8Array });
+  const context = vm.createContext({ figma, handlers: {}, console, setTimeout, clearTimeout, Map, Set, Uint8Array });
   for (const file of ['utils', 'token-helpers', 'read-helpers', 'handlers-read-detail', 'handlers-read', 'handlers-tokens', 'handlers-write-ops', 'node-reader']) {
     vm.runInContext(readFileSync(`plugin-src/${file}.js`, 'utf8'), context, { filename: file });
   }
@@ -161,12 +161,13 @@ test('export_node validates format and works through batch and aliases', async (
   assert.match(batch.results[1].error, /supports PNG/);
 });
 
-test('multiple paints preserve top-first ordering and node opacity stays separate', () => {
+test('multiple paints: Figma bottom→top becomes CSS top-first; top-most solid wins', () => {
   const r = runtime();
-  const paints = [{ type: 'SOLID', color: { r: 1, g: 0, b: 0 }, opacity: .5 }, { type: 'SOLID', color: { r: 0, g: 0, b: 1 }, opacity: 1 }].map(r.serializePaint);
-  const css = r.paintsToCss(paints, 200, 100);
-  assert.match(css.value, /^linear-gradient\(rgba\(255, 0, 0, 0.5\)/);
-  assert.match(css.value, /linear-gradient\(#0000ff, #0000ff\)$/);
+  const raw = [{ type: 'SOLID', color: { r: 1, g: 0, b: 0 }, opacity: .5 }, { type: 'SOLID', color: { r: 0, g: 0, b: 1 }, opacity: 1 }];
+  const css = r.paintsToCss(raw.map(r.serializePaint), 200, 100);
+  assert.match(css.value, /^linear-gradient\(#0000ff, #0000ff\)/);
+  assert.match(css.value, /linear-gradient\(rgba\(255, 0, 0, 0.5\), rgba\(255, 0, 0, 0.5\)\)$/);
+  assert.equal(r.firstSolidHex(raw), '#0000ff');
 });
 
 test('UI badge uses release version initially and follows the server on reconnect', () => {
@@ -600,6 +601,32 @@ test('plugin tab IDs differ for the same document and request replay does not wr
   assert.ok(messages.filter(msg => msg.id).every(msg => msg.sessionId === first.currentSessionId));
 });
 
+test('a runtime hash change hot-reloads once, not on every later server-hello', () => {
+  const html = readFileSync('plugin-runtime/ui.html', 'utf8');
+  const source = html.slice(html.indexOf('    function connectWs()'), html.indexOf('    async function startLongPoll()'));
+  const sockets = [];
+  let reloads = 0;
+  class Socket {
+    static OPEN = 1;
+    constructor(url) { this.url = url; this.readyState = 1; sockets.push(this); }
+    close() {} send() {}
+  }
+  const r = vm.createContext({
+    uiDisposed: false, ws: null, wsConnected: false, sessionId: 'tab-a', fileName: 'File', documentId: 'doc', BRIDGE: 'http://localhost:41730',
+    WebSocket: Socket, setInterval: () => 1, clearInterval: () => {}, setTimeout: () => { reloads++; return 1; }, clearTimeout: () => {},
+    sendRuntimeCapabilities: () => {}, consecutiveErrors: 0, everConnected: false, retryTimer: null, polling: true,
+    setStatus: () => {}, log: () => {}, currentPort: 41730, READ_OPS: [], updateRuntimeVersion: () => {},
+    activeIndexScan: null, startLongPoll: () => {}, dispatchToMain: () => {}, window: {},
+  });
+  vm.runInContext(source, r);
+  r.connectWs(); sockets[0].onopen();
+  const hello = hash => sockets[0].onmessage({ data: JSON.stringify({ type: 'server-hello', version: '5.1.0', runtimeHash: hash }) });
+  hello('a'); assert.equal(reloads, 0);
+  hello('b'); assert.equal(reloads, 1);
+  // window survives the reload's document.write; the same server must not reload it again.
+  hello('b'); hello('b'); assert.equal(reloads, 1);
+});
+
 test('old UI socket callbacks cannot clear or dispatch through a replacement socket', () => {
   const html = readFileSync('plugin-runtime/ui.html', 'utf8');
   const source = html.slice(html.indexOf('    function connectWs()'), html.indexOf('    async function startLongPoll()'));
@@ -634,7 +661,7 @@ test('tree reads preserve Regular font weight, collect Regular font tokens, and
     getLocalTextStylesAsync: async () => [{ id: 'S:text-1', name: 'Lato/18px/regular' }],
     getLocalEffectStylesAsync: async () => [],
   };
-  const context = vm.createContext({ figma, handlers: {}, console, setTimeout, Map, Set, Uint8Array });
+  const context = vm.createContext({ figma, handlers: {}, console, setTimeout, clearTimeout, Map, Set, Uint8Array });
   for (const file of ['utils', 'svg-path-helpers', 'paint-and-effects', 'token-helpers', 'read-helpers', 'handlers-read-detail', 'handlers-read']) {
     vm.runInContext(readFileSync(`plugin-src/${file}.js`, 'utf8'), context, { filename: file });
   }
@@ -832,3 +859,86 @@ test('byte-bounded reads paginate without dropping unicode, oversized nodes or d
   assert.equal(all[5].content,'漢'.repeat(2000));
   await assert.rejects(r.handlers.read_nodes({id:'frame',maxBytes:0}),/maxBytes/);
 });
+
+test('letter spacing PERCENT converts to px; line-height percent keeps decimals', () => {
+  const r = runtime();
+  const node = { id: '1:1', type: 'TEXT', characters: 'Hi', fontSize: 20, fontName: { family: 'Inter', style: 'Regular' },
+    letterSpacing: { unit: 'PERCENT', value: -2.5 }, lineHeight: { unit: 'PERCENT', value: 137.456 } };
+  const style = r.resolveTextStyle(node);
+  assert.equal(style.letterSpacing, -0.5);
+  assert.equal(style.lineHeight, '137.46%');
+  assert.equal(r.resolveTextStyle({ ...node, letterSpacing: { unit: 'PIXELS', value: 1.2 } }).letterSpacing, 1.2);
+});
+
+test('blur effects emit half the Figma radius', () => {
+  const r = runtime();
+  const css = r.effectsToCss([{ type: 'LAYER_BLUR', radius: 8 }, { type: 'BACKGROUND_BLUR', radius: 20 }]);
+  assert.equal(css.filter, 'blur(4px)');
+  assert.equal(css.backdropFilter, 'blur(10px)');
+});
+
+test('findNodeByIdAsync returns null for a missing instance sublayer, not its parent instance', async () => {
+  const instance = { id: '2715:40862', type: 'INSTANCE' };
+  const r = runtime({ root: { id: '0:0' }, currentPage: { id: '0:1', selection: [] },
+    getNodeByIdAsync: async id => (id === instance.id ? instance : null) });
+  assert.equal(await r.findNodeByIdAsync('I2715:40862;123:456'), null);
+  assert.equal(await r.findNodeByIdAsync('2715:40862'), instance);
+});
+
+test('bound variables resolve in the node mode and report library aliases', async () => {
+  const cols = [{ id: 'sem', defaultModeId: 'light' }, { id: 'lib', defaultModeId: 'l1' }];
+  const local = [{ id: 'bg', name: 'bg/surface', variableCollectionId: 'sem', resolvedType: 'COLOR',
+    valuesByMode: { light: { type: 'VARIABLE_ALIAS', id: 'white' }, dark: { type: 'VARIABLE_ALIAS', id: 'black' } } }];
+  const library = [
+    { id: 'white', name: 'gray/0', variableCollectionId: 'lib', resolvedType: 'COLOR', valuesByMode: { l1: { r: 1, g: 1, b: 1, a: 1 } } },
+    { id: 'black', name: 'gray/900', variableCollectionId: 'lib', resolvedType: 'COLOR', valuesByMode: { l1: { r: 0, g: 0, b: 0, a: 1 } } },
+  ];
+  const r = runtime({ variables: {
+    getLocalVariablesAsync: async () => local, getLocalVariableCollectionsAsync: async () => cols.slice(0, 1),
+    getVariableByIdAsync: async id => library.find(v => v.id === id) || local.find(v => v.id === id),
+    getVariableCollectionByIdAsync: async id => cols.find(c => c.id === id),
+  } });
+  const node = { id: '1:1', name: 'Card', type: 'RECTANGLE', width: 10, height: 10, x: 0, y: 0,
+    fills: [{ type: 'SOLID', color: { r: 0, g: 0, b: 0 } }], boundVariables: { fills: [{ id: 'bg' }] },
+    resolvedVariableModes: { sem: 'dark' } };
+  const map = await r.buildVariableResolverMapAsync(true);
+  const walkState = { variableMap: map, remaining: 10, budget: 10 };
+  const tree = r.extractDesignTree(node, 0, 5, 'full', true, null, null, walkState);
+  await r.resolvePendingVariablesAsync(walkState);
+  const entry = plain(tree.boundVariables.fills[0]);
+  assert.equal(entry.name, 'bg/surface');
+  assert.equal(entry.aliasTarget, 'gray/900');
+  assert.equal(entry.value, '#000000');
+  assert.equal(tree.fillToken, 'bg/surface');
+  // Second walk: library variables are cached, resolved synchronously.
+  const light = r.extractDesignTree({ ...node, resolvedVariableModes: { sem: 'light' } }, 0, 5, 'full', true, null, null, { variableMap: map, remaining: 10, budget: 10 });
+  assert.equal(light.boundVariables.fills[0].value, '#ffffff');
+  assert.equal(light.boundVariables.fills[0].aliasTarget, 'gray/0');
+});
+
+test('resolveVariableValueAsync reports alias names for node consumers', async () => {
+  const cols = [{ id: 'sem', defaultModeId: 'light' }, { id: 'prim', defaultModeId: 'p' }];
+  const vars = [
+    { id: 'a', name: 'text/primary', variableCollectionId: 'sem', resolvedType: 'COLOR', valuesByMode: { light: { type: 'VARIABLE_ALIAS', id: 'b' }, dark: { type: 'VARIABLE_ALIAS', id: 'c' } },
+      resolveForConsumer: () => ({ value: { r: 1, g: 1, b: 1, a: 1 } }) },
+    { id: 'b', name: 'gray/900', variableCollectionId: 'prim', resolvedType: 'COLOR', valuesByMode: { p: { r: 0, g: 0, b: 0, a: 1 } } },
+    { id: 'c', name: 'gray/0', variableCollectionId: 'prim', resolvedType: 'COLOR', valuesByMode: { p: { r: 1, g: 1, b: 1, a: 1 } } },
+  ];
+  const r = runtime({ variables: { getVariableByIdAsync: async id => vars.find(v => v.id === id), getVariableCollectionByIdAsync: async id => cols.find(c => c.id === id) } });
+  const res = await r.resolveVariableValueAsync(vars[0], { resolvedVariableModes: { sem: 'dark', prim: 'p' } });
+  assert.equal(res.type, 'ALIAS');
+  assert.equal(res.primitiveName, 'gray/0');
+  assert.equal(res.hex, '#ffffff');
+});
+
+test('get_variables finishes when Figma never answers a library alias lookup', async () => {
+  const sem = { id: 'V:2', name: 'bg/primary', resolvedType: 'COLOR', variableCollectionId: 'C:2',
+    valuesByMode: { l: { type: 'VARIABLE_ALIAS', id: 'VariableID:lib/1' } }, scopes: [] };
+  const col = { id: 'C:2', name: 'Sem', defaultModeId: 'l', modes: [{ modeId: 'l', name: 'Light' }], variableIds: ['V:2'] };
+  const r = runtime({ variables: {
+    getLocalVariableCollectionsAsync: async () => [col], getLocalVariablesAsync: async () => [sem],
+    getVariableByIdAsync: () => new Promise(() => {}), getVariableCollectionByIdAsync: async () => col } });
+  const out = plain(await r.handlers.get_variables());
+  assert.equal(out.collections[0].variables[0].values.l.resolvedValue, null);
+  assert.ok(out.diagnostics.some(d => /did not answer variable VariableID:lib\/1/.test(d.message)), JSON.stringify(out.diagnostics));
+});

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