figma-rust-mcp 3.2.7 → 3.2.9

package/README.md

@@ -8,7 +8,7 @@ Enables AI agents (Google Antigravity, Claude Code, Cursor, Windsurf, VS Code, Z
 
 ## ⚡ Highlights
 
-- **State & Screen Variant Aggregation (`Context-Preserving Deduplication`)**: Automatically groups frames/sections containing multiple screen states (Default, Typing, Success, Error, Disabled) or repeated list items into a single Base Template + Diffs. Cuts LLM token consumption by **80–90%** while preserving 100% of typography, autolayout, tokens, and button styling.
+- **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**: Starts in `< 1ms`, uses `~3MB RAM`, zero GC pauses.
 - **In-Memory Deep Indexing (`figma_index`)**: Queries layers, components, styles, and tokens in `< 1ms` without slow canvas roundtrips.
 - **Binary IPC & Chunk Streaming**: Powered by **MessagePack** (`rmp-serde`) and progressive subtree chunking for instant transfers of massive design files.
@@ -107,6 +107,25 @@ npx -y figma-rust-mcp@latest --uninstall-service
 
 ---
 
+### Windows background mode
+
+Double-clicking `figma-mcp.exe` starts the server in a detached process and closes
+its launcher console. From PowerShell or Command Prompt, use:
+
+```powershell
+.\figma-mcp.exe --background
+```
+
+The server keeps running after the terminal closes. Logs are appended to
+`%LOCALAPPDATA%\figma-mcp\logs\server.log`. Use `--server` for the foreground
+terminal dashboard, or `--stdio` for an MCP client subprocess.
+
+`--install-service` through the npm runner configures background startup at login.
+Re-run the installation command to update an existing Windows task. Removing the
+task disables future login startup; stop an already detached server through Task
+Manager (`figma-mcp.exe`). The launcher console may appear briefly when opening
+the executable; the server itself does not retain a console window.
+
 ### 4. Build from Source (Optional)
 
 If you prefer building directly with the [Rust toolchain](https://rustup.rs/) (`cargo >= 1.80`):
@@ -215,9 +234,43 @@ Exports Figma Variables (Design Tokens), Color Styles, Typography Styles, and El
 - **`outputPath`**: Writes directly to disk (e.g. `src/styles/tokens.css` or `tailwind.config.js`).
 - **`collection`** / **`mode`** / **`prefix`**: Optional filters and naming prefixes.
 
+Token exports use schema v2 and preserve full paint/effect stacks, alpha, gradient
+transforms, collection modes and raw alias values. CSS, Tailwind, TypeScript and
+JSON share one normalized model. The `w3c` output uses DTCG 2025.10 color,
+dimension, gradient-stop and shadow values, with Figma-specific geometry and
+unsupported values retained in `$extensions`.
+
+Linear gradients on a node are projected using its actual dimensions. A diagonal
+gradient style has no target aspect ratio: use `get_css` on its consuming node.
+Radial/angular/diamond paints, unsupported blend modes and progressive blurs
+retain their raw data and report diagnostics recommending SVG instead of emitting
+approximate CSS. Unknown modes, unresolved aliases and sanitized name collisions
+fail explicitly. CSS exports include non-default modes under `data-theme`
+selectors; opacity/font-weight variables stay unitless.
+
+The plugin UI badge is stamped from the build version and updated from the
+connected server handshake. Package/Cargo/tag mismatches fail the build pipeline.
+Run `npm run build:plugin` after changing plugin source, and `npm run test:tokens`
+for the token/contract/version regression suite. Existing background servers need
+a restart with the new binary to load the updated runtime.
+
+
 ### 5. `figma_get_selection`
-Token-compressed inspection of currently selected layers/frames on the Figma canvas. Returns compacted layout and typography hierarchy with **60–80% fewer tokens**.
-- **`detail`**: `"compact"` (recommended), `"minimal"`, `"full"`.
+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`
@@ -291,6 +344,43 @@ Scans your local codebase directories (`src/components`, `components/ui`) to dis
 
 ---
 
+### Multiple tabs and frame tasks
+
+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"`,
+`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.
+
+Tools on one tab run sequentially, including every awaited operation in a
+`figma_write` call. Different tabs run independently. `npm run test:sessions`
+(Node >=22) checks real WebSocket/HTTP transport with a simulated plugin canvas;
+it does not replace validation in Figma Desktop.
+
+### Startup indexing
+
+Opening the bridge indexes top-level nodes on the active page and local tokens.
+It does not preload every page or scan the document-wide component catalogue.
+`figma_index` status exposes `components_indexed: false` until a full reindex;
+this means deferred, not an empty catalogue. Live component queries populate
+the Rust cache for subsequent reads while the index remains valid. Component reads/searches and rules
+that require the complete catalogue fall back to a live query.
+
+The plugin listens to active-page `nodechange` and global `stylechange` events,
+and rebuilds the lightweight index when the active page changes. It does not
+subscribe to document-wide node changes by preloading the whole file. Explicit
+reindexing still includes all local components; discovery loads pages one at a
+time and yields after at most 100 nodes or an 8ms traversal slice. Figma's native
+page load itself cannot be interrupted by the plugin. Concurrent identical
+index requests share one scan, and results from a previously active page are
+not published as the current index.
+
 ## 💻 Development & Testing
 
 ```bash

package/bin/figma-mcp.js

@@ -6,7 +6,7 @@
  * caches it locally, and executes it transparently.
  */
 
-import { spawn, execSync } from 'node:child_process';
+import { spawn, execSync, execFileSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
@@ -19,7 +19,7 @@ const __dirname = path.dirname(__filename);
 
 // Read package.json version
 const pkgPath = path.resolve(__dirname, '../package.json');
-let pkgVersion = '2.9.5';
+let pkgVersion = null;
 let repoOwner = 'BuiHung1612';
 let repoName = 'figma-mcp';
 
@@ -36,6 +36,7 @@ try {
     }
   }
 } catch (_) {}
+if (!pkgVersion) throw new Error(`Cannot read package version from ${pkgPath}`);
 
 function getPlatformArch() {
   const platform = process.platform;
@@ -293,8 +294,10 @@ WantedBy=default.target
   } else if (platform === 'win32') {
     const taskName = 'FigmaMCPServer';
     // Use schtasks to create a task that runs at login
-    const cmd = `schtasks /Create /F /TN "${taskName}" /TR "${binPath}" /SC ONLOGON /RL HIGHEST`;
-    execSync(cmd, { stdio: 'inherit' });
+    // The native launcher detaches the server and redirects output to a log file.
+    const taskCommand = `"${binPath}" --background`;
+    execFileSync('schtasks', ['/Create', '/F', '/TN', taskName,
+      '/TR', taskCommand, '/SC', 'ONLOGON'], { stdio: 'inherit', windowsHide: true });
 
     // Start it immediately too
     try { execSync(`schtasks /Run /TN "${taskName}"`, { stdio: 'pipe' }); } catch (_) {}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "figma-rust-mcp",
-  "version": "3.2.7",
-  "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.",
+  "version": "3.2.9",
+  "description": "Claude Code to Figma \u2014 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-mcp",
   "type": "module",
   "bin": {
@@ -16,10 +16,12 @@
     "LICENSE"
   ],
   "scripts": {
-    "build": "cargo build --release",
+    "build": "npm run build:plugin && cargo build --release",
     "build:plugin": "node scripts/build-plugin.js",
     "test": "./scripts/test-rust-mcp.sh",
-    "dev": "cargo run"
+    "test:tokens": "node --test scripts/test-plugin-tokens.mjs && cargo test",
+    "dev": "cargo run",
+    "test:sessions": "cargo build && node --test scripts/test-bridge-sessions.mjs"
   },
   "engines": {
     "node": ">=18"

package/plugin/code.js

@@ -1,4 +1,4 @@
-// ─── FIGMA MCP BRIDGE — DYNAMIC THIN LOADER (v3.0.0) ───────────────────────────
+// ─── FIGMA MCP BRIDGE — DYNAMIC THIN LOADER ───────────────────────────
 // This file is a permanent micro-stub. You never need to reinstall or edit this file.
 // The actual runtime is loaded dynamically from the local figma-mcp Rust engine.
 

package/scripts/build-plugin.js

@@ -1,13 +1,19 @@
-// Build script — concatenate src/plugin/*.js into plugin/code.js
+// Build script — concatenate plugin-src/*.js into plugin-runtime/code.js
 // No module system used: files are plain JS sharing a single scope when concatenated.
 import { readFileSync, writeFileSync } from "fs";
 
 const { version } = JSON.parse(readFileSync("package.json", "utf8"));
+const cargoVersion = readFileSync("Cargo.toml", "utf8").match(/^version\s*=\s*"([^"]+)"/m)?.[1];
+if (version !== cargoVersion) throw new Error(`Version mismatch: package.json ${version}, Cargo.toml ${cargoVersion}`);
+if (process.env.GITHUB_REF_TYPE === "tag" && process.env.GITHUB_REF_NAME !== `v${version}`) {
+  throw new Error(`Release tag ${process.env.GITHUB_REF_NAME} does not match build version v${version}`);
+}
 
 const files = [
   "plugin-src/utils.js",
   "plugin-src/svg-path-helpers.js",
   "plugin-src/paint-and-effects.js",
+  "plugin-src/token-helpers.js",
   "plugin-src/read-helpers.js",
   "plugin-src/handlers-write.js",
   "plugin-src/handlers-library.js",
@@ -15,13 +21,13 @@ const files = [
   "plugin-src/handlers-read-detail.js",
   "plugin-src/handlers-tokens.js",
   "plugin-src/handlers-write-ops.js",
+  "plugin-src/task-scope.js",
   "plugin-src/main.js",
 ];
 
-const banner = `// figma-mcp — Figma Plugin main thread v1.2.1
+const banner = `// figma-mcp — Figma Plugin main thread v${version}
 // Handles both WRITE (draw UI) and READ (extract design) operations.
 // AUTO-GENERATED by scripts/build-plugin.js — edit plugin-src/*.js instead
-// Generated: ${new Date().toISOString()}
 `;
 
 const parts = files.map(f => {
@@ -30,5 +36,17 @@ const parts = files.map(f => {
 });
 
 const output = (banner + parts.join("\n")).replace(/\{\{PLUGIN_VERSION\}\}/g, version);
-writeFileSync("plugin-runtime/code.js", output);
+
+const uiPath = "plugin-runtime/ui.html";
+const ui = readFileSync(uiPath, "utf8").replace(/(<span class="brand-ver"[^>]*>)[^<]*(<\/span>)/,
+  `$1v${version}$2`);
+if (!ui.includes(`id="runtime-version">v${version}</span>`)) throw new Error("Missing runtime version badge");
+if (process.argv.includes('--check')) {
+  if (readFileSync("plugin-runtime/code.js", "utf8") !== output || readFileSync(uiPath, "utf8") !== ui) {
+    throw new Error("Plugin bundle is stale; run npm run build:plugin");
+  }
+} else {
+  writeFileSync("plugin-runtime/code.js", output);
+  writeFileSync(uiPath, ui);
+}
 console.log(`✓ plugin-runtime/code.js written (${output.length} chars, ${output.split("\n").length} lines)`);

package/scripts/test-bridge-sessions.mjs

@@ -0,0 +1,155 @@
+import { test } from 'node:test';
+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 vm from 'node:vm';
+
+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) {
+  const deadline = Date.now() + 5000;
+  while (!await predicate()) { if (Date.now() > deadline) throw new Error('Timed out'); await delay(10); }
+}
+const decode = result => JSON.parse(result.content[0].text);
+const ok = result => { assert.notEqual(result.isError, true, result.content?.[0]?.text); return result; };
+
+// Uses only Node built-ins (Node >=22 supplies WebSocket) and the actual Rust
+// daemon. The canvas is simulated; this verifies transport/agent isolation.
+test('multiple tabs, reconnect ownership and independent frame tasks across MCP clients', { timeout: 20000 }, async t => {
+  assert.equal(typeof WebSocket, 'function', 'This integration check requires Node >=22');
+  const reservation = createServer();
+  await new Promise(resolve => reservation.listen(0, '127.0.0.1', resolve));
+  const port = reservation.address().port;
+  await new Promise(resolve => reservation.close(resolve));
+  const binary = process.env.FIGMA_TEST_BINARY || 'target/debug/figma-mcp';
+  const server = spawn(binary, ['--server', '--port', String(port)], { stdio: ['ignore', 'ignore', 'pipe'], env: { ...process.env, FIGMA_MCP_PORT: String(port) } });
+  let stderr = ''; server.stderr.on('data', bytes => { stderr = (stderr + bytes).slice(-4000); });
+  const processes = [server], sockets = [], latest = new Map(), actions = [];
+  t.after(() => { for (const socket of sockets) socket.close(); for (const process of processes) process.kill(); });
+  const base = `http://127.0.0.1:${port}`;
+  await until(async () => { try { return (await fetch(`${base}/health`)).ok; } catch { assert.equal(server.exitCode, null, stderr); return false; } });
+  let rpcId = 0;
+  async function rpc(name, args) {
+    const response = await fetch(`${base}/mcp`, { method: 'POST', headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ jsonrpc: '2.0', id: ++rpcId, method: 'tools/call', params: { name, arguments: args } }) });
+    return (await response.json()).result;
+  }
+  function agent() {
+    const process = spawn(binary, ['--stdio', '--port', String(port)], { env: { ...globalThis.process.env, FIGMA_MCP_PORT: String(port) } });
+    processes.push(process); process.stderr.resume();
+    let id = 0;
+    const pending = new Map();
+    createInterface({ input: process.stdout }).on('line', line => {
+      const response = JSON.parse(line); const resolve = pending.get(response.id);
+      if (resolve) { pending.delete(response.id); resolve(response.result); }
+    });
+    return (name, args) => new Promise(resolve => {
+      pending.set(++id, resolve);
+      process.stdin.write(JSON.stringify({ jsonrpc: '2.0', id, method: 'tools/call', params: { name, arguments: args } }) + '\n');
+    });
+  }
+  const paused = deferred(), resume = deferred();
+  async function plugin(sid, existing) {
+    const state = existing || {};
+    if (!state.runtime) {
+      const page = { id: 'page', type: 'PAGE' };
+      const nodes = new Map();
+      for (const suffix of ['a', 'b', 'c']) {
+        const root = { id: `frame-${suffix}`, name: suffix, type: 'FRAME', parent: page, children: [] };
+        const child = { id: `child-${suffix}`, type: 'TEXT', parent: root }; root.children.push(child);
+        nodes.set(root.id, root); nodes.set(child.id, child);
+      }
+      state.runtime = vm.createContext({ handlers: {}, findNodeByIdAsync: async id => nodes.get(id), yieldToUI: async () => {} });
+      vm.runInContext(readFileSync('plugin-src/task-scope.js', 'utf8'), state.runtime);
+      state.runtime.handlers.get_design = async params => ({ id: params.id, type: 'FRAME', name: params.id, tab: sid });
+      state.runtime.handlers.status = async () => ({ tab: sid });
+      state.runtime.handlers.modify = async params => {
+        actions.push(params.note);
+        if (params.note === 'paused') { paused.resolve(); await resume.promise; }
+        return { id: params.id, note: params.note };
+      };
+      state.tail = Promise.resolve();
+    }
+    const socket = new WebSocket(`ws://127.0.0.1:${port}/ws?sessionId=${sid}&fileName=SameFile&documentId=same-document`);
+    sockets.push(socket); state.socket = socket; latest.set(sid, state);
+    socket.addEventListener('message', event => {
+      const message = JSON.parse(event.data);
+      if (message.type === 'server-hello') {
+        for (const id of state.runtime.frameTasks.keys()) if (!message.activeTaskIds.includes(id)) state.runtime.frameTasks.delete(id);
+        return;
+      }
+      if (!message.operation) return;
+      if (state.ignoreNext) { state.ignoreNext = false; state.ignored.resolve(message); return; }
+      socket.send(JSON.stringify({ type: 'ack', id: message.id }));
+      state.tail = state.tail.then(async () => {
+        try {
+          const checked = await state.runtime.validateTaskOperation(message.operation, message.params);
+          const data = await state.runtime.handlers[checked.operation](checked.params);
+          latest.get(sid).socket.send(JSON.stringify({ id: message.id, sessionId: sid, success: true, data }));
+        } catch (error) { latest.get(sid).socket.send(JSON.stringify({ id: message.id, sessionId: sid, success: false, error: error.message })); }
+      });
+    });
+    await new Promise((resolve, reject) => { socket.addEventListener('open', resolve, { once: true }); socket.addEventListener('error', reject, { once: true }); });
+    socket.send(JSON.stringify({ type: 'runtime-capabilities', runtimeVersion: 'test', protocolVersion: 2, documentId: 'same-document', operations: Object.keys(state.runtime.handlers) }));
+    return state;
+  }
+  const tabA = await plugin('tab-a'), tabB = await plugin('tab-b');
+  const first = agent(), second = agent();
+  const ambiguous = await rpc('figma_read', { operation: 'get_design', nodeId: 'frame-a' });
+  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' });
+  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' })));
+  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"});' });
+  await paused.promise;
+  const writeB = second('figma_write', { taskId: taskB.taskId, code: 'await figma.modify({id:"child-b",note:"other-task"});' });
+  ok(await rpc('figma_write', { taskId: taskC.taskId, code: 'await figma.modify({id:"child-c",note:"other-tab"});' }));
+  assert.deepEqual(actions, ['paused', 'other-tab']);
+  resume.resolve(); ok(await writeA); ok(await writeB);
+  assert.deepEqual(actions, ['paused', 'other-tab', 'second', 'other-task']);
+  const returned = ok(await first('figma_write', { taskId: taskA.taskId,
+    code: 'await figma.modify({id:"child-a",note:"settled"}); return "done";' }));
+  assert.equal(returned.content[0].text, 'Result: "done"');
+  const rejected = await first('figma_write', { taskId: taskA.taskId,
+    code: 'await figma.modify({id:"child-a",note:"before-error"}); throw new Error("after-await");' });
+  assert.equal(rejected.isError, true); assert.match(rejected.content[0].text, /after-await/);
+  const outside = await first('figma_write', { taskId: taskA.taskId, code: 'await figma.modify({id:"child-b",note:"escape"});' });
+  assert.equal(outside.isError, true); assert.ok(!actions.includes('escape'));
+  const rawWrite = await fetch(`${base}/exec?sessionId=tab-b`, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ operation: 'modify', params: { id: 'child-a' } }) });
+  assert.equal((await rawWrite.json()).success, false);
+
+  // A replacement socket recovers an op that the old socket never ACKed.
+  tabA.ignoreNext = true; tabA.ignored = deferred(); const oldSocket = tabA.socket;
+  const recovering = rpc('figma_read', { operation: 'get_design', nodeId: 'frame-a', sessionId: 'tab-a' });
+  const ignored = await tabA.ignored.promise;
+  await plugin('tab-a', tabA); oldSocket.close();
+  assert.equal(decode(ok(await recovering)).tab, 'tab-a');
+  await delay(30);
+  assert.equal(decode(ok(await rpc('figma_read', { operation: 'get_design', nodeId: 'frame-b', sessionId: 'tab-a' }))).id, 'frame-b');
+  // Cross-tab response spoofing cannot consume another tab's pending request.
+  tabA.ignoreNext = true; tabA.ignored = deferred();
+  const routed = rpc('figma_read', { operation: 'get_design', nodeId: 'frame-a', sessionId: 'tab-a' });
+  const waiting = await tabA.ignored.promise;
+  tabB.socket.send(JSON.stringify({ id: waiting.id, success: true, data: { hijacked: true } }));
+  const wrongHttp = await fetch(`${base}/response`, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ id: waiting.id, sessionId: 'tab-b', success: true, data: { hijacked: true } }) });
+  assert.equal((await wrongHttp.json()).ok, false);
+  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 }));
+  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);
+  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 }));
+});

package/scripts/test-plugin-tokens.mjs

@@ -0,0 +1,360 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import vm from 'node:vm';
+import { spawnSync } from 'node:child_process';
+
+function runtime(figma = {}) {
+  const context = vm.createContext({ figma, handlers: {}, console, setTimeout, Map, Set, Uint8Array });
+  for (const file of ['utils', 'token-helpers', 'handlers-read-detail', 'handlers-read', 'handlers-tokens', 'handlers-write-ops']) {
+    vm.runInContext(readFileSync(`plugin-src/${file}.js`, 'utf8'), context, { filename: file });
+  }
+  return context;
+}
+const plain = value => JSON.parse(JSON.stringify(value));
+const gradient = (transform = [[1, 0, 0], [0, 1, 0]]) => ({
+  type: 'GRADIENT_LINEAR', gradientTransform: transform, opacity: .5,
+  gradientStops: [{ position: 0, color: { r: 1, g: 0, b: 0, a: .5 } }, { position: 1, color: { r: 0, g: 0, b: 1, a: 1 } }],
+});
+const shadow = type => ({ type, color: { r: 0, g: 0, b: 0, a: .125 }, offset: { x: -1, y: 3 }, radius: 6, spread: -2, visible: true });
+
+test('equivalent CSS syntaxes preserve alpha in reads and writes', () => {
+  const r = runtime();
+  for (const color of ['rgba(255, 0, 0, .5)', 'rgb(100% 0% 0% / 50%)', 'hsl(0 100% 50% / .5)', 'hsla(0, 100%, 50%, .5)']) {
+    assert.deepEqual(plain(r.parseColorValue(color)), { r: 1, g: 0, b: 0, a: .5 });
+    assert.equal(r.hexToRgbA(color).a, .5);
+    assert.equal(r.solidFill(color)[0].opacity, .5);
+  }
+  assert.equal(r.parseColorValue('#f008').a, 136 / 255);
+  assert.equal(r.parseColorValue('transparent').a, 0);
+  assert.equal(r.colorToCss({ r: 0, g: 0, b: 0, a: .9999 }), 'rgba(0, 0, 0, 0.9999)');
+  assert.throws(() => r.parseColorValue('rgba(garbage)'), /Invalid/);
+});
+
+test('gradient projection includes translations, aspect ratio, stop and paint alpha', () => {
+  const r = runtime();
+  const p = r.serializePaint(gradient());
+  assert.deepEqual(plain(p.gradientTransform), [[1, 0, 0], [0, 1, 0]]);
+  assert.match(r.paintToCss(p, 200, 100), /^linear-gradient\(90deg, rgba\(255, 0, 0, 0.25\) 0%, rgba\(0, 0, 255, 0.5\) 100%\)$/);
+  const diagonal = r.paintToCss(r.serializePaint(gradient([[1, 1, 0], [0, 1, 0]])), 200, 100);
+  assert.match(diagonal, /153\.434948/);
+  assert.match(diagonal, /50%/);
+  const shifted = r.paintToCss(r.serializePaint(gradient([[.5, 0, .25], [0, 1, 0]])), 200, 100);
+  assert.match(shifted, /-50%/);
+  assert.match(shifted, /150%/);
+  assert.throws(() => r.paintToCss({ ...p, type: 'GRADIENT_DIAMOND' }, 100, 100), /SVG/);
+});
+
+test('get_css uses the numeric paint, never hex slicing a serialized rgba', async () => {
+  const node = { id: '1:2', name: 'alpha', type: 'RECTANGLE', x: 0, y: 0, width: 200, height: 100,
+    fills: [{ type: 'SOLID', color: { r: 1, g: 0, b: 0 }, opacity: .25 }], effects: [shadow('DROP_SHADOW'), shadow('INNER_SHADOW')] };
+  const r = runtime();
+  r.findNodeByIdAsync = async () => node;
+  const result = await r.handlers.get_css({ id: node.id });
+  assert.match(result.css, /background-color: rgba\(255, 0, 0, 0.25\);/);
+  assert.doesNotMatch(result.css, /NaN|0.0625/);
+  assert.match(result.css, /inset -1px 3px 6px -2px rgba\(0, 0, 0, 0.125\)/);
+  assert.equal(result.detail.effects.length, 2);
+});
+
+test('styles retain full paints, effects, units and disabled layers', async () => {
+  const r = runtime({
+    getLocalPaintStylesAsync: async () => [{ id: 'p', name: 'Gradient', paints: [gradient()] }],
+    getLocalTextStylesAsync: async () => [{ id: 't', name: 'Body', fontName: { family: 'Inter', style: 'Regular' }, fontSize: 16, lineHeight: { unit: 'PERCENT', value: 150 }, letterSpacing: { unit: 'PERCENT', value: 2 } }],
+    getLocalEffectStylesAsync: async () => [{ id: 's', name: 'Card', effects: [shadow('DROP_SHADOW'), shadow('INNER_SHADOW'), { type: 'LAYER_BLUR', radius: 8, visible: false }] }],
+    getLocalGridStylesAsync: async () => [],
+  });
+  const styles = await r.handlers.get_styles();
+  assert.equal(styles.schemaVersion, 2);
+  assert.equal(styles.paintStyles[0].paints[0].gradientStops[0].rgba.a, .5);
+  assert.equal(styles.effectStyles[0].effects.length, 3);
+  assert.equal(styles.textStyles[0].lineHeightUnit, 'PERCENT');
+  assert.equal(r.effectsToCss(styles.effectStyles[0].effects).filter, '');
+});
+
+test('aliases use mode names across collections and retain false/zero values', async () => {
+  const cols = [
+    { id: 'semantic', name: 'Semantic', defaultModeId: 's-light', modes: [{ modeId: 's-light', name: 'Light' }, { modeId: 's-dark', name: 'Dark' }], variableIds: ['alias', 'zero'] },
+    { id: 'primitive', name: 'Primitive', defaultModeId: 'p-light', modes: [{ modeId: 'p-light', name: 'Light' }, { modeId: 'p-dark', name: 'Dark' }], variableIds: ['base'] },
+  ];
+  const variables = [
+    { id: 'alias', name: 'semantic', variableCollectionId: 'semantic', resolvedType: 'BOOLEAN', valuesByMode: { 's-light': { type: 'VARIABLE_ALIAS', id: 'base' }, 's-dark': { type: 'VARIABLE_ALIAS', id: 'base' } } },
+    { id: 'zero', name: 'zero', variableCollectionId: 'semantic', resolvedType: 'FLOAT', valuesByMode: { 's-light': 0, 's-dark': 1 } },
+    { id: 'base', name: 'base', variableCollectionId: 'primitive', resolvedType: 'BOOLEAN', valuesByMode: { 'p-light': false, 'p-dark': true } },
+  ];
+  const r = runtime({ variables: {
+    getLocalVariableCollectionsAsync: async () => cols, getLocalVariablesAsync: async () => variables,
+    getVariableByIdAsync: async id => variables.find(v => v.id === id),
+    getVariableCollectionByIdAsync: async id => cols.find(c => c.id === id),
+  } });
+  const result = await r.handlers.get_variables();
+  const alias = result.collections[0].variables[0];
+  assert.equal(alias.values['s-light'].resolvedValue, false);
+  assert.equal(alias.values['s-dark'].resolvedValue, true);
+  assert.equal(result.resolvedTokens.semantic, false);
+  assert.equal(result.resolvedTokens.zero, 0);
+  assert.equal(result.collections[0].defaultModeId, 's-light');
+  assert.deepEqual(plain(result.diagnostics), []);
+  const consumer = { resolvedVariableModes: { semantic: 's-dark', primitive: 'p-light' } };
+  variables[0].resolveForConsumer = () => ({ value: false, resolvedType: 'BOOLEAN' });
+  assert.equal((await r.resolveVariableValueAsync(variables[0], consumer)).resolvedValue, false);
+});
+
+test('export_node validates format and works through batch and aliases', async () => {
+  const r = runtime();
+  r.handlers.export_svg = async () => ({ svg: '<svg/>' });
+  r.handlers.export_image = async params => ({ format: params.format });
+  assert.equal((await r.resolveOperationHandler('exportNode')({ format: 'svg' })).svg, '<svg/>');
+  assert.equal((await r.handlers.export_node({ format: 'jpeg' })).format, 'JPG');
+  const batch = await r.handlers.batch({ operations: [{ operation: 'export_node', params: { format: 'SVG' } }, { operation: 'export_node', params: { format: 'bad' } }] });
+  assert.equal(batch.succeeded, 1);
+  assert.match(batch.results[1].error, /supports PNG/);
+});
+
+test('multiple paints preserve top-first ordering and node opacity stays separate', () => {
+  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\)$/);
+});
+
+test('UI badge uses release version initially and follows the server on reconnect', () => {
+  const pkg = JSON.parse(readFileSync('package.json', 'utf8'));
+  const html = readFileSync('plugin-runtime/ui.html', 'utf8');
+  assert.ok(html.includes(`id="runtime-version">v${pkg.version}</span>`));
+  const start = html.indexOf('    function updateRuntimeVersion(');
+  const end = html.indexOf('    var runtimeCapabilities', start);
+  const badge = {};
+  const context = vm.createContext({ document: { getElementById: () => badge } });
+  vm.runInContext(html.slice(start, end), context);
+  context.updateRuntimeVersion('3.2.7');
+  assert.equal(badge.textContent, 'v3.2.7');
+  context.updateRuntimeVersion('3.3.0');
+  assert.equal(badge.textContent, 'v3.3.0');
+  assert.ok(html.includes('updateRuntimeVersion(serverVer)'));
+  assert.ok(html.includes('type: "runtime-ready"'));
+});
+
+test('build rejects wrong release tags and checked-in bundle matches source', () => {
+  const check = spawnSync(process.execPath, ['scripts/build-plugin.js', '--check'], { encoding: 'utf8' });
+  assert.equal(check.status, 0, check.stderr);
+  const rejected = spawnSync(process.execPath, ['scripts/build-plugin.js'], {
+    encoding: 'utf8', env: { ...process.env, GITHUB_REF_TYPE: 'tag', GITHUB_REF_NAME: 'v0.0.0-invalid' },
+  });
+  assert.notEqual(rejected.status, 0);
+  assert.match(rejected.stderr, /does not match build version/);
+});
+
+
+test('tree reads preserve same-size screens and all repeated siblings', () => {
+  const r = runtime();
+  vm.runInContext(readFileSync('plugin-src/read-helpers.js', 'utf8'), r);
+  const screens = Array.from({ length: 12 }, (_, i) => ({
+    id: `screen:${i}`, name: `Screen ${i}`, type: 'FRAME', width: 402, height: 800,
+    layoutMode: 'VERTICAL', itemSpacing: i,
+    children: [{ id: `item:${i}`, name: `Item ${i}`, type: 'FRAME', width: 100, height: 40 }],
+  }));
+  const root = { id: 'root', name: 'Screens', type: 'SECTION', children: screens };
+  for (const detail of ['compact', 'full']) {
+    const tree = plain(r.extractDesignTree(root, 0, 10, detail, true));
+    assert.equal(tree.children.length, 12);
+    assert.deepEqual(tree.children.map(node => node.id), screens.map(node => node.id));
+    assert.equal(tree.children[11].layout.itemSpacing, 11);
+    assert.equal(tree.children[11].children[0].id, 'item:11');
+  }
+});
+
+
+test('startup index defers document-wide components and coalesces duplicate scans', async () => {
+  let componentQueries = 0, styleQueries = 0;
+  const page = { id: 'page:1', children: [{ id: 'frame:1', name: 'Frame', type: 'FRAME' }] };
+  const r = runtime({ currentPage: page, root: { name: 'File', getPluginData: () => '' } });
+  r.handlers.get_styles = async () => { styleQueries++; return { schemaVersion: 2 }; };
+  r.handlers.get_variables = async () => ({ schemaVersion: 2 });
+  r.handlers.get_local_components = async () => { componentQueries++; return { components: [], componentSets: [] }; };
+  const [a, b] = await Promise.all([
+    r.handlers.index_scan({ deferComponents: true }),
+    r.handlers.index_scan({ deferComponents: true }),
+  ]);
+  assert.equal(componentQueries, 0);
+  assert.equal(styleQueries, 1);
+  assert.equal(a, b);
+  assert.equal(a.pageId, page.id);
+  assert.equal(a.componentsDeferred, true);
+  assert.equal(a.pageNodes[0].id, 'frame:1');
+  const [light, full] = await Promise.all([
+    r.handlers.index_scan({ deferComponents: true }), r.handlers.index_scan({}),
+  ]);
+  assert.equal(light.components, null);
+  assert.equal(full.componentsDeferred, false);
+  assert.equal(componentQueries, 1);
+});
+
+test('component catalogue walks pages cooperatively without bulk loading or root searches', async () => {
+  let loaded = 0, yields = 0, reads = 0, lastYieldReads = 0, maxSliceReads = 0;
+  const page = { type: 'PAGE', name: 'Components', loadAsync: async () => { loaded++; } };
+  page.children = Array.from({ length: 1000 }, (_, i) => ({
+    id: `c:${i}`, name: `Component ${i}`, parent: page, width: 10, height: 10,
+    get type() { reads++; return i % 2 ? 'COMPONENT_SET' : 'COMPONENT'; },
+  }));
+  const r = runtime({
+    root: { children: [page], findAllWithCriteria: () => assert.fail('root-wide search') },
+    loadAllPagesAsync: () => assert.fail('bulk page load'),
+  });
+  r.yieldToUI = async () => {
+    yields++; maxSliceReads = Math.max(maxSliceReads, reads - lastYieldReads); lastYieldReads = reads;
+  };
+  const result = await r.handlers.get_local_components();
+  assert.equal(loaded, 1);
+  assert.equal(result.components.length, 500);
+  assert.equal(result.componentSets.length, 500);
+  assert.ok(yields >= 10, 'large traversal must yield before finishing');
+  assert.ok(maxSliceReads <= 200, 'no more than 100 nodes between traversal yields');
+});
+
+test('startup subscribes to active-page changes without loading the whole file', async () => {
+  const events = new Map(), timers = [], messages = [];
+  let pageListener;
+  const page = {
+    id: 'page:1', children: [], selection: [],
+    on: (name, callback) => { assert.equal(name, 'nodechange'); pageListener = callback; },
+    off: () => {},
+  };
+  const r = runtime({
+    currentPage: page, root: { name: 'File', getPluginData: () => 'session' },
+    clientStorage: { getAsync: async () => null }, ui: { postMessage: msg => messages.push(msg) },
+    on: (name, callback) => { events.set(name, callback); },
+    loadAllPagesAsync: () => assert.fail('startup bulk page load'),
+  });
+  r.setTimeout = (callback, delay) => { timers.push({ callback, delay }); return timers.length; };
+  r.clearTimeout = () => {};
+  vm.runInContext(readFileSync('plugin-src/main.js', 'utf8'), r);
+  assert.ok(pageListener);
+  assert.ok(events.has('stylechange'));
+  assert.ok(!events.has('documentchange'));
+  let scanOptions;
+  r.handlers.index_scan = async options => { scanOptions = options; return { pageId: page.id }; };
+  await timers.find(timer => timer.delay === 1800).callback();
+  await new Promise(resolve => setTimeout(resolve, 0));
+  assert.equal(scanOptions.deferComponents, true);
+  pageListener({ nodeChanges: [{ type: 'PROPERTY_CHANGE', node: { id: 'changed:1' } }] });
+  assert.ok(r.pendingChangedNodeIds.has('changed:1'));
+  assert.ok(messages.some(msg => msg.type === 'document-change'));
+  const next = { id: 'page:2', on: () => {}, off: () => {} };
+  r.figma.currentPage = next;
+  r.handlers.index_scan = async () => ({ pageId: 'page:1' });
+  const previousUpdates = messages.filter(msg => msg.type === 'index-update').length;
+  await r.publishIndex(true);
+  assert.equal(messages.filter(msg => msg.type === 'index-update').length, previousUpdates);
+});
+
+
+function taskRuntime() {
+  const page = { id: 'page', type: 'PAGE' };
+  const a = { id: 'a', name: 'A', type: 'FRAME', parent: page, children: [] };
+  const b = { id: 'b', name: 'B', type: 'FRAME', parent: page, children: [] };
+  const child = { id: 'a:child', type: 'TEXT', parent: a };
+  a.children.push(child);
+  const nodes = new Map([page, a, b, child].map(node => [node.id, node]));
+  const r = runtime();
+  vm.runInContext(readFileSync('plugin-src/task-scope.js', 'utf8'), r);
+  r.findNodeByIdAsync = async id => nodes.get(id);
+  return { r, nodes, a, b, page };
+}
+
+test('frame tasks reject outside/global writes and batch escape before mutations', async () => {
+  const { r, a, b } = taskRuntime();
+  await r.handlers.task_start({ taskId: 'task-a', frameId: a.id });
+  await r.handlers.task_start({ taskId: 'task-b', frameId: b.id });
+  await assert.rejects(r.handlers.task_start({ taskId: 'task-c', frameId: a.id }), /reserved/);
+  const create = await r.validateTaskOperation('create', { _taskId: 'task-a', type: 'TEXT', content: 'Hello' });
+  assert.equal(create.params.parentId, a.id);
+  const read = await r.validateTaskOperation('get_selection', { _taskId: 'task-a' });
+  assert.equal(read.operation, 'get_design');
+  assert.equal(read.params.id, a.id);
+  assert.equal((await r.validateTaskOperation('screenshot', { _taskId: 'task-a', keepViewport: false })).params.keepViewport, true);
+  await r.validateTaskOperation('modify', { _taskId: 'task-a', id: 'a:child', name: 'Updated' });
+  for (const [operation, params] of [
+    ['modify', { id: b.id }], ['create', { type: 'TEXT', parentId: b.id }],
+    ['delete', { id: a.id, force: true }], ['clone', { id: a.id }],
+    ['append', { parentId: b.id, childId: 'a:child' }],
+    ['set_selection', { nodeIds: [a.id] }], ['setPage', { id: 'page' }],
+    ['setVariableValue', { id: 'variable' }], ['createPaintStyle', { name: 'Global' }],
+    ['create', { type: 'COMPONENT' }],
+    ['batch', { operations: [{ operation: 'modify', params: { id: 'a:child' } }, { operation: 'delete', params: { id: b.id } }] }],
+  ]) {
+    await assert.rejects(r.validateTaskOperation(operation, { ...params, _taskId: 'task-a' }));
+  }
+  await assert.rejects(r.validateTaskOperation('modify', { id: 'a:child' }), /require taskId/);
+  await r.handlers.task_end({ taskId: 'task-a' });
+  await assert.rejects(r.validateTaskOperation('modify', { _taskId: 'task-a', id: 'a:child' }), /Unknown task/);
+});
+
+test('task roots cannot be shared masters or nested layout frames', async () => {
+  const { r, nodes, a } = taskRuntime();
+  const nested = { id: 'nested', type: 'FRAME', parent: a, children: [] };
+  nodes.set(nested.id, nested);
+  await assert.rejects(r.handlers.task_start({ taskId: 'nested-task', frameId: nested.id }), /independent FRAME/);
+  a.children.push({ id: 'master', type: 'COMPONENT', parent: a });
+  await assert.rejects(r.handlers.task_start({ taskId: 'master-task', frameId: a.id }), /shared component/);
+});
+
+test('plugin tab IDs differ for the same document and request replay does not write twice', async () => {
+  const messages = [];
+  function boot() {
+    const r = runtime({
+      fileKey: 'same-file', root: { name: 'File', getPluginData: () => 'same-file' },
+      currentPage: { id: 'page', selection: [], on: () => {} },
+      clientStorage: { getAsync: async () => null }, ui: { postMessage: msg => messages.push(msg) }, on: () => {},
+    });
+    r.setTimeout = () => 0; r.clearTimeout = () => {};
+    r.validateTaskOperation = async (operation, params) => ({ operation, params });
+    vm.runInContext(readFileSync('plugin-src/main.js', 'utf8'), r);
+    return r;
+  }
+  const first = boot(), second = boot();
+  assert.notEqual(first.currentSessionId, second.currentSessionId);
+  assert.equal(first.currentDocumentId, second.currentDocumentId);
+  let release;
+  const blocked = new Promise(resolve => { release = resolve; });
+  const entered = [];
+  first.handlers.modify = async params => { entered.push(params.id); if (params.id === 'first') await blocked; return params; };
+  const call1 = first.figma.ui.onmessage({ id: 'request-1', operation: 'modify', params: { id: 'first' } });
+  const replay = first.figma.ui.onmessage({ id: 'request-1', operation: 'modify', params: { id: 'first' } });
+  const call2 = first.figma.ui.onmessage({ id: 'request-2', operation: 'modify', params: { id: 'second' } });
+  await new Promise(resolve => setTimeout(resolve, 0));
+  assert.deepEqual(entered, ['first']);
+  release(); await Promise.all([call1, replay, call2]);
+  assert.deepEqual(entered, ['first', 'second']);
+  assert.equal(messages.filter(msg => msg.id === 'request-1' && msg.success).length, 2);
+  assert.ok(messages.filter(msg => msg.id).every(msg => msg.sessionId === first.currentSessionId));
+});
+
+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()'));
+  const sockets = [], dispatched = [];
+  class Socket {
+    static OPEN = 1;
+    constructor(url) { this.url = url; this.readyState = 1; sockets.push(this); }
+    close() {} send() {}
+  }
+  const r = vm.createContext({
+    ws: null, wsConnected: false, sessionId: null, fileName: 'File', documentId: 'doc', BRIDGE: 'http://localhost:38451',
+    WebSocket: Socket, setInterval: () => 1, clearInterval: () => {}, setTimeout: () => 1, clearTimeout: () => {},
+    sendRuntimeCapabilities: () => {}, consecutiveErrors: 0, everConnected: false, retryTimer: null, polling: true,
+    setStatus: () => {}, log: () => {}, currentPort: 38451, READ_OPS: [],
+    startLongPoll: () => assert.fail('stale socket started poll'), dispatchToMain: req => dispatched.push(req),
+  });
+  vm.runInContext(source, r);
+  r.connectWs(); assert.equal(sockets.length, 0);
+  r.sessionId = 'tab-a'; r.connectWs(); const old = sockets[0];
+  old.onopen(); r.connectWs(); const replacement = sockets[1]; replacement.onopen();
+  old.onclose(); old.onmessage({ data: JSON.stringify({ id: 'old', operation: 'modify' }) });
+  assert.equal(r.wsConnected, true);
+  assert.equal(r.ws, replacement);
+  assert.equal(dispatched.length, 0);
+  replacement.onmessage({ data: JSON.stringify({ id: 'new', operation: 'modify' }) });
+  assert.equal(dispatched[0].id, 'new');
+});