figma-rust-mcp 5.0.0 → 5.0.2

package/README.md

@@ -422,21 +422,49 @@ recently used entry when its 64-entry capacity is reached.
 
 ## 📏 Benchmarks
 
-`npm run bench` builds the release binary, spawns it on a random port and prints:
+`npm run bench` builds the release binary and prints a JSON report from a fresh
+server: cold start, process startup, server RAM and MCP dispatch latency. A fresh
+server has no Figma session, so plugin and index measurements are explicitly
+skipped.
 
-| Metric | How it is measured |
+To measure real work, connect the Figma plugin and use the existing server:
+
+```bash
+# Server report, including its current index and plugin round trip
+node scripts/bench.mjs --url http://127.0.0.1:41730
+
+# Read all descendants of a frame, index that frame, and export it as a 1x PNG
+node scripts/bench.mjs --url http://127.0.0.1:41730 \
+  --target 'SESSION_ID=FRAME_ID' --samples 3 > benchmark.json
+
+# Run the same workloads concurrently on two tabs
+node scripts/bench.mjs --url http://127.0.0.1:41730 \
+  --target 'FIRST_SESSION=FIRST_FRAME' --target 'SECOND_SESSION=SECOND_FRAME'
+```
+
+Find session IDs at `GET /sessions` and frame IDs in the plugin selection card.
+Use one frame per session and 1–10 samples per workload. Workloads read Figma
+content; they do not modify canvas nodes. Indexing updates the bridge's cache,
+and PNG export may briefly move the viewport before restoring it.
+
+| Measurement | What it includes |
 |---|---|
-| Cold start | `spawn` → first successful `GET /health`, from outside the process |
-| Startup | `main()` entry → HTTP listener bound |
-| RAM | Resident set size (macOS/Linux; not reported on Windows) |
 | MCP `tools/list` | 200 in-process dispatches, p50/p95 |
-| Index search | 200 searches over the current tab's index, p50/p95 (plugin tab only) |
-| Plugin round trip | 10 `get_viewport` calls through Figma, p50/p95 (plugin tab only) |
-
-The plugin's **Bench** tab runs the same report (`POST /benchmark`) against the
-live server, so index and plugin numbers reflect your real file. Sample run on an
-Apple Silicon Mac (v4.0.1): cold start 45–530ms, startup 26–126ms, RSS ~7.6MB,
-`tools/list` p50 0.07ms. Your numbers will differ; quote your own.
+| Index search | 200 searches over the current index, when available |
+| Plugin round trip | 10 `get_viewport` calls, when connected |
+| Frame read | All paginated `read_nodes` responses, node/page counts and JSON bytes |
+| Frame index | Plugin scan and response time; bridge commit acknowledgement is separate |
+| PNG export | Figma export, transfer and decoded image bytes |
+| Concurrent tabs | Workloads run sequentially per tab and concurrently across tabs |
+| RAM | Server RSS before/after workloads, not peak RAM or Figma's memory |
+
+Reports contain each sample plus p50/p95/max. Reads use the normal cache, so the
+samples are not guaranteed cold reads. Truncated reads remain marked incomplete;
+failed workloads retain their error and the CLI exits with status 1. Real Figma
+results depend on your file; simulated integration tests only verify the path.
+
+The plugin's existing **Bench** tab retains the basic `POST /benchmark` report.
+Use the CLI for the heavier frame and concurrent-tab workloads.
 
 ## 💻 Development & Testing
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "figma-rust-mcp",
-  "version": "5.0.0",
+  "version": "5.0.2",
   "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/bench-workloads.mjs

@@ -0,0 +1,85 @@
+// Read-only live workloads. The server and Figma plugin must already be running.
+export async function requestJson(base, route, body) {
+  const response = await fetch(new URL(route, base), {
+    method: body === undefined ? 'GET' : 'POST',
+    headers: body === undefined ? {} : { 'Content-Type': 'application/json' },
+    body: body === undefined ? undefined : JSON.stringify(body),
+    signal: AbortSignal.timeout(120000),
+  });
+  if (!response.ok) throw new Error(`${route}: HTTP ${response.status}`);
+  return response.json();
+}
+
+export function summarize(samples) {
+  const times = samples.map(sample => sample.durationMs).sort((a, b) => a - b);
+  const pick = q => times[Math.round((times.length - 1) * q)];
+  return { n: times.length, p50Ms: pick(.5), p95Ms: pick(.95), maxMs: times.at(-1), samples };
+}
+
+export async function benchmarkTargets(base, targets, samples = 3) {
+  if (!Number.isInteger(samples) || samples < 1 || samples > 10) throw new Error('samples must be from 1 to 10');
+  if (!targets.length || targets.some(target => !target.sessionId || !target.nodeId)) throw new Error('Each target needs sessionId and nodeId');
+  if (new Set(targets.map(target => target.sessionId)).size !== targets.length) throw new Error('Use one target per session for concurrent tab measurements');
+  const memoryBefore = (await requestJson(base, '/health')).stats?.memoryMb ?? null;
+  const started = performance.now();
+  const results = await Promise.all(targets.map(async ({ sessionId, nodeId }) => {
+    const workloads = {};
+    const exec = async (operation, params) => {
+      const result = await requestJson(base, `/exec?sessionId=${encodeURIComponent(sessionId)}`, { operation, params });
+      if (!result.success) throw new Error(result.error || `${operation} failed`);
+      return result.data;
+    };
+    const runs = {
+      readFrame: async () => {
+        let cursor, nodes = 0, pages = 0, responseBytes = 0, complete;
+        const cursors = new Set();
+        do {
+          const data = await exec('read_nodes', cursor ? { cursor, limit: 500 } :
+            { id: nodeId, depth: 'full', expandInstances: true, fields: ['geometry', 'content', 'style', 'text'], limit: 500 });
+          if (!Array.isArray(data.nodes)) throw new Error('read_nodes returned no node list');
+          nodes += data.nodes.length; pages++;
+          responseBytes += Buffer.byteLength(JSON.stringify(data));
+          complete = data.complete === true;
+          cursor = data.nextCursor;
+          if (cursor && cursors.has(cursor)) throw new Error('read_nodes repeated a cursor');
+          if (cursor) cursors.add(cursor);
+          if (cursor && pages >= 100) throw new Error('read_nodes exceeded 100 pages');
+        } while (cursor);
+        return { nodes, pages, responseBytes, complete };
+      },
+      indexFrame: async () => {
+        const data = await exec('index_scan', { id: nodeId, depth: 'full', expandInstances: true, deferComponents: true });
+        if (data.cancelled) throw new Error('Index cancelled by a document or page change');
+        return { complete: data.complete === true, nodesTruncated: data.nodesTruncated === true };
+      },
+      exportPng: async () => {
+        const data = await exec('export_image', { id: nodeId, format: 'PNG', scale: 1 });
+        if (typeof data.base64 !== 'string') throw new Error('export_image returned no image');
+        return { imageBytes: Buffer.from(data.base64, 'base64').length, width: data.width, height: data.height };
+      },
+    };
+    for (const [name, run] of Object.entries(runs)) {
+      const timings = [];
+      try {
+        for (let i = 0; i < samples; i++) {
+          const start = performance.now();
+          const data = await run();
+          timings.push({ durationMs: performance.now() - start, ...data });
+        }
+        workloads[name] = summarize(timings);
+      } catch (error) {
+        workloads[name] = { error: error.message, completedSamples: timings.length, samples: timings };
+        break; // Do not keep loading a tab after a timeout or disconnect.
+      }
+    }
+    return { sessionId, nodeId, workloads };
+  }));
+  const memoryAfter = (await requestJson(base, '/health')).stats?.memoryMb ?? null;
+  return {
+    mode: 'live', concurrentTabs: targets.length, samplesPerWorkload: samples,
+    wallTimeMs: performance.now() - started,
+    serverRssBeforeMb: memoryBefore, serverRssAfterMb: memoryAfter,
+    note: 'RSS is server memory at the boundaries, not peak memory or Figma memory. Reads may use the normal cache. Index timing includes plugin scan/response, not bridge commit acknowledgement.',
+    targets: results,
+  };
+}

package/scripts/bench.mjs

@@ -1,37 +1,59 @@
-// Benchmark: cold start measured from outside (spawn → /health answers), then the
-// server's in-process report from POST /benchmark (same numbers as the plugin "Bench" tab).
-// Usage: npm run bench   or   node scripts/bench.mjs [path/to/figma-rust-mcp]
-import { spawn } from "node:child_process";
-import { statSync } from "node:fs";
+// Cold: node scripts/bench.mjs [binary]
+// Live: node scripts/bench.mjs --url http://127.0.0.1:41730 --target SESSION=NODE [--target SESSION=NODE] [--samples 3]
+import { spawn } from 'node:child_process';
+import { createServer } from 'node:net';
+import { statSync } from 'node:fs';
+import { benchmarkTargets, requestJson } from './bench-workloads.mjs';
 
-const bin = process.argv[2] ?? `target/release/figma-rust-mcp${process.platform === "win32" ? ".exe" : ""}`;
-const port = 40000 + Math.floor(Math.random() * 10000);
-const base = `http://127.0.0.1:${port}`;
-
-const t0 = performance.now();
-const child = spawn(bin, ["--server", "--port", String(port)], { stdio: "ignore" });
-let coldStartMs;
+const args = process.argv.slice(2), targets = [];
+let base, samples = 3, bin = `target/release/figma-rust-mcp${process.platform === 'win32' ? '.exe' : ''}`;
+for (let i = 0; i < args.length; i++) {
+  const arg = args[i];
+  if (arg === '--url') base = args[++i];
+  else if (arg === '--samples') samples = Number(args[++i]);
+  else if (arg === '--target') {
+    const target = args[++i] || '', separator = target.indexOf('=');
+    if (separator < 1 || separator === target.length - 1) throw new Error('--target must be SESSION=NODE');
+    targets.push({ sessionId: target.slice(0, separator), nodeId: target.slice(separator + 1) });
+  } else if (!arg.startsWith('-') && i === 0) bin = arg;
+  else throw new Error(`Unknown argument: ${arg}`);
+}
+if (args.includes('--url') && !base) throw new Error('--url needs a server URL');
+if (!Number.isInteger(samples) || samples < 1 || samples > 10) throw new Error('--samples must be from 1 to 10');
+if (targets.length && !base) throw new Error('--target requires --url for an existing Figma connection');
+if (base && !['http:', 'https:'].includes(new URL(base).protocol)) throw new Error('--url must use HTTP or HTTPS');
+let child, coldStartMs;
 try {
-  while (coldStartMs === undefined) {
-    if (performance.now() - t0 > 10_000) throw new Error("server did not answer /health within 10s");
-    try {
-      if ((await fetch(`${base}/health`)).ok) coldStartMs = performance.now() - t0;
-    } catch {
-      await new Promise((r) => setTimeout(r, 2));
+  if (!base) {
+    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));
+    base = `http://127.0.0.1:${port}`;
+    const start = performance.now();
+    let spawnError;
+    child = spawn(bin, ['--server', '--port', String(port)], { stdio: 'ignore' });
+    child.on('error', error => { spawnError = error; });
+    while (coldStartMs === undefined) {
+      if (spawnError) throw spawnError;
+      if (child.exitCode !== null) throw new Error(`Server exited: ${child.exitCode}`);
+      if (performance.now() - start > 10000) throw new Error('Server did not answer /health within 10s');
+      try {
+        const response = await fetch(`${base}/health`, { signal: AbortSignal.timeout(500) });
+        if (response.ok) coldStartMs = performance.now() - start;
+      } catch {}
+      if (coldStartMs === undefined) await new Promise(resolve => setTimeout(resolve, 2));
     }
   }
-  const r = await (await fetch(`${base}/benchmark`, { method: "POST" })).json();
-  const lat = (s) => (s ? `p50 ${s.p50Ms.toFixed(3)}ms · p95 ${s.p95Ms.toFixed(3)}ms (n=${s.n})` : "skipped");
-  const rows = {
-    version: `v${r.version}`,
-    "binary size": `${(statSync(bin).size / 1024 / 1024).toFixed(1)}MB`,
-    "cold start (spawn → /health)": `${coldStartMs.toFixed(1)}ms`,
-    "startup (main → listening)": r.startupMs != null ? `${r.startupMs.toFixed(2)}ms` : "—",
-    "RAM (RSS)": r.memoryMb != null ? `${r.memoryMb.toFixed(1)}MB` : "n/a on this OS",
-    "MCP tools/list (in-process)": lat(r.mcpToolsList),
-    "plugin round trip": r.pluginRoundTrip ? lat(r.pluginRoundTrip) : "skipped (fresh server has no Figma session)",
-  };
-  for (const [k, v] of Object.entries(rows)) console.log(`${k.padEnd(30)} ${v}`);
+  const report = await requestJson(base, '/benchmark', {});
+  report.mode = child ? 'cold-start' : 'live';
+  if (child) {
+    report.coldStartMs = coldStartMs;
+    report.binarySizeMb = statSync(bin).size / 1024 / 1024;
+  }
+  if (targets.length) report.workloads = await benchmarkTargets(base, targets, samples);
+  console.log(JSON.stringify(report, null, 2));
+  if (report.workloads?.targets.some(target => Object.values(target.workloads).some(workload => workload.error || workload.samples?.some(sample => sample.complete === false)))) process.exitCode = 1;
 } finally {
-  child.kill();
+  child?.kill();
 }

package/scripts/helpers/index-sync-ui.mjs

@@ -0,0 +1,22 @@
+import { readFileSync } from 'node:fs';
+import vm from 'node:vm';
+
+export function indexSyncUi(socket = { readyState: 1, send() {} }) {
+  const html = readFileSync('plugin-runtime/ui.html', 'utf8');
+  const element = () => {
+    const classes = new Set();
+    return { disabled: false, title: 'Sync index', attributes: {},
+      setAttribute(name, value) { this.attributes[name] = value; },
+      classList: { add: name => classes.add(name), remove: name => classes.delete(name),
+        contains: name => classes.has(name), toggle: (name, active) => active ? classes.add(name) : classes.delete(name) } };
+  };
+  const timers = new Map();
+  let timerId = 0;
+  const ui = vm.createContext({ reindexBtn: element(), indexProgressWrap: element(), indexProgressText: element(),
+    ws: socket, WebSocket: { OPEN: 1 }, log() {},
+    setTimeout(callback, delay) { timers.set(++timerId, { callback, delay }); return timerId; },
+    clearTimeout(id) { timers.delete(id); } });
+  vm.runInContext(html.slice(html.indexOf('    var activeIndexScan ='), html.indexOf('    function focusSelection()')), ui);
+  ui.fireTimers = delay => { for (const [id, timer] of timers) if (timer.delay === delay) { timers.delete(id); timer.callback(); } };
+  return ui;
+}

package/scripts/test-bench.mjs

@@ -0,0 +1,98 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createServer } from 'node:http';
+import { spawn } from 'node:child_process';
+import { benchmarkTargets, summarize } from './bench-workloads.mjs';
+
+async function fixture(t, exec) {
+  const calls = [];
+  const server = createServer(async (request, response) => {
+    try {
+      const url = new URL(request.url, 'http://localhost');
+      response.setHeader('Content-Type', 'application/json');
+      if (url.pathname === '/health') return response.end(JSON.stringify({ stats: { memoryMb: 12 } }));
+      if (url.pathname === '/benchmark') return response.end(JSON.stringify({ version: 'test', pluginRoundTrip: null }));
+      let body = '';
+      for await (const chunk of request) body += chunk;
+      const call = { sessionId: url.searchParams.get('sessionId'), ...JSON.parse(body) };
+      calls.push(call);
+      response.end(JSON.stringify(await exec(call)));
+    } catch (error) {
+      response.statusCode = 500; response.end(JSON.stringify({ error: error.message }));
+    }
+  });
+  await new Promise(resolve => server.listen(0, '127.0.0.1', resolve));
+  t.after(() => { server.closeAllConnections(); server.close(); });
+  return { base: `http://127.0.0.1:${server.address().port}`, calls };
+}
+
+const result = data => ({ success: true, data });
+function success(call) {
+  if (call.operation === 'read_nodes') return result({ nodes: [{ id: call.params.cursor ? 'child' : call.params.id }],
+    nextCursor: call.params.cursor ? null : `${call.sessionId}:next`, complete: !!call.params.cursor });
+  if (call.operation === 'index_scan') return result({ complete: true, nodesTruncated: false });
+  if (call.operation === 'export_image') return result({ base64: Buffer.from('png').toString('base64'), width: 100, height: 80 });
+  throw new Error(`Unexpected operation: ${call.operation}`);
+}
+
+function cli(args) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, ['scripts/bench.mjs', ...args]);
+    let stdout = '', stderr = '';
+    child.stdout.on('data', chunk => { stdout += chunk; });
+    child.stderr.on('data', chunk => { stderr += chunk; });
+    child.on('error', reject);
+    child.on('exit', code => resolve({ code, stdout, stderr }));
+  });
+}
+
+test('live benchmark paginates reads, measures all workloads and runs tabs concurrently', { timeout: 5000 }, async t => {
+  let active = 0, peak = 0;
+  const { base, calls } = await fixture(t, async call => {
+    active++; peak = Math.max(peak, active);
+    await new Promise(resolve => setTimeout(resolve, 5));
+    active--;
+    return success(call);
+  });
+  const report = await benchmarkTargets(base, [{ sessionId: 'one', nodeId: 'frame:1' }, { sessionId: 'two', nodeId: 'frame:2' }], 2);
+  assert.equal(report.concurrentTabs, 2);
+  assert.ok(peak >= 2);
+  assert.equal(report.serverRssBeforeMb, 12);
+  for (const target of report.targets) {
+    assert.equal(target.workloads.readFrame.n, 2);
+    assert.equal(target.workloads.readFrame.samples[0].nodes, 2);
+    assert.equal(target.workloads.readFrame.samples[0].pages, 2);
+    assert.equal(target.workloads.readFrame.samples[0].complete, true);
+    assert.ok(target.workloads.readFrame.samples[0].responseBytes > 0);
+    assert.equal(target.workloads.indexFrame.samples[0].complete, true);
+    assert.equal(target.workloads.exportPng.samples[0].imageBytes, 3);
+  }
+  assert.equal(calls.length, 16);
+  assert.ok(calls.filter(call => call.params.cursor).every(call => call.params.cursor.startsWith(call.sessionId)));
+});
+
+test('live benchmark exposes bridge failures and stops loading the failed tab', async t => {
+  const { base, calls } = await fixture(t, () => ({ success: false, error: 'Plugin disconnected' }));
+  const report = await benchmarkTargets(base, [{ sessionId: 'one', nodeId: 'frame' }]);
+  assert.equal(report.targets[0].workloads.readFrame.error, 'Plugin disconnected');
+  assert.equal(calls.length, 1);
+  await assert.rejects(benchmarkTargets(base, [{ sessionId: 'one', nodeId: 'a' }, { sessionId: 'one', nodeId: 'b' }]), /one target per session/);
+  await assert.rejects(benchmarkTargets(base, [{ sessionId: 'one', nodeId: 'a' }], 0), /samples/);
+});
+
+test('benchmark rejects repeated cursors and CLI preserves failure status in JSON', async t => {
+  const { base } = await fixture(t, () => result({ nodes: [], nextCursor: 'same', complete: false }));
+  const output = await cli(['--url', base, '--target', 'one=frame', '--samples', '1']);
+  assert.equal(output.code, 1, output.stderr);
+  const report = JSON.parse(output.stdout);
+  assert.match(report.workloads.targets[0].workloads.readFrame.error, /repeated a cursor/);
+  const invalid = await cli(['--target', 'invalid']);
+  assert.equal(invalid.code, 1);
+  assert.match(invalid.stderr, /SESSION=NODE/);
+});
+
+test('benchmark reports sorted percentile samples', () => {
+  const report = summarize([5, 1, 3, 2, 4].map(durationMs => ({ durationMs })));
+  assert.equal(report.p50Ms, 3);
+  assert.equal(report.p95Ms, 5);
+});

package/scripts/test-bridge-sessions.mjs

@@ -158,3 +158,121 @@ test('multiple tabs, reconnect ownership and independent frame tasks across MCP
   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 }));
 });
+
+test('index sync travels from plugin through UI to bridge and returns a matching confirmation', { timeout: 20000 }, async t => {
+  const { indexSyncUi } = await import('./helpers/index-sync-ui.mjs');
+  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 server = spawn(process.env.FIGMA_TEST_BINARY || 'target/debug/figma-rust-mcp',
+    ['--server', '--port', String(port)], { stdio: ['ignore', 'ignore', 'pipe'] });
+  let stderr = ''; server.stderr.on('data', bytes => { stderr = (stderr + bytes).slice(-4000); });
+  const sockets = [];
+  t.after(() => { sockets.forEach(socket => socket.close()); server.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; } });
+  const ui = indexSyncUi(null);
+  const page = { id: 'page', children: [{ id: 'frame', name: 'Frame', type: 'FRAME', width: 100, height: 100 }] };
+  const runtime = vm.createContext({ figma: { currentPage: page, root: { name: 'Sync test' },
+    ui: { postMessage: msg => ui.handleIndexMessage(msg) } }, handlers: {}, console, setTimeout, 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'), runtime);
+  }
+  runtime.handlers.get_styles = async () => ({});
+  runtime.handlers.get_variables = async () => ({});
+  const html = readFileSync('plugin-runtime/ui.html', 'utf8');
+  Object.assign(ui, { WebSocket, BRIDGE: base, sessionId: 'sync-test', fileName: 'Sync test', documentId: 'sync-doc',
+    uiDisposed: false, wsConnected: false, everConnected: false, retryTimer: null, polling: false, consecutiveErrors: 0,
+    currentPort: port, window: {}, READ_OPS: [], setInterval: () => 1, clearInterval() {},
+    sendRuntimeCapabilities() {}, setStatus() {}, updateRuntimeVersion() {}, startLongPoll() {},
+    dispatchToMain() {}, showSetupGuide() {}, parent: { postMessage: () => runtime.handlers.index_scan({ deferComponents: true }) } });
+  vm.runInContext(html.slice(html.indexOf('    function connectWs()'), html.indexOf('    async function startLongPoll()')), ui);
+  const connect = async () => { ui.connectWs(); sockets.push(ui.ws); await until(() => ui.wsConnected); };
+  await connect();
+  const confirmed = ui.receiveIndexAck;
+  const acks = [];
+  ui.receiveIndexAck = ack => acks.push(ack);
+  await runtime.handlers.index_scan({ deferComponents: true });
+  await until(() => acks.length === 1);
+  assert.equal(acks[0].success, true);
+  assert.equal(ui.reindexBtn.disabled, true, 'local scan completion must wait for bridge ack');
+  confirmed({ ...acks[0], scanId: 'older-scan' });
+  assert.equal(ui.reindexBtn.disabled, true);
+  confirmed(acks.shift());
+  assert.equal(ui.reindexBtn.disabled, false);
+  assert.match(ui.reindexBtn.title, /Last synced/);
+  const lastSuccess = ui.reindexBtn.title;
+  ui.receiveIndexAck = ack => { acks.push(ack); confirmed(ack); };
+  const unmatched = { type: 'index-start', pageId: 'page', scanId: 'unmatched', revision: 0, scope: { id: 'page' } };
+  // The UI begins a scan but the bridge never receives its start/chunks.
+  ui.handleIndexMessage({ ...unmatched, type: 'index-progress', stage: 'starting' });
+  ui.handleIndexMessage({ ...unmatched, type: 'index-update', data: {} });
+  await until(() => acks.length === 1);
+  assert.equal(acks[0].success, false);
+  assert.equal(ui.reindexBtn.disabled, false);
+  assert.match(ui.indexProgressText.textContent, /no longer active/);
+  assert.equal(ui.reindexBtn.title, lastSuccess);
+
+  ui.handleIndexMessage({ ...unmatched, scanId: 'disconnect' });
+  ui.ws.close();
+  await until(() => !ui.wsConnected);
+  assert.equal(ui.reindexBtn.disabled, false);
+  assert.match(ui.indexProgressText.textContent, /disconnected/);
+  await connect();
+  acks.length = 0;
+  await ui.triggerManualReindex();
+  await until(() => acks.length === 1);
+  assert.equal(acks[0].success, true);
+  assert.equal(ui.reindexBtn.disabled, false);
+
+  runtime.handlers.get_styles = async () => { throw new Error('Styles unavailable'); };
+  await assert.rejects(runtime.handlers.index_scan({ deferComponents: true }), /Styles unavailable/);
+  assert.equal(ui.reindexBtn.disabled, false);
+  assert.match(ui.indexProgressText.textContent, /Styles unavailable/);
+  runtime.handlers.get_styles = async () => { runtime.figma.currentPage = { id: 'new-page', children: [] }; return {}; };
+  const cancelled = await runtime.handlers.index_scan({ deferComponents: true });
+  assert.equal(cancelled.cancelled, true);
+  assert.equal(ui.reindexBtn.disabled, false);
+  assert.match(ui.indexProgressText.textContent, /Document changed/);
+  runtime.handlers.get_styles = async () => ({});
+  acks.length = 0;
+  await runtime.handlers.index_scan({ deferComponents: true });
+  await until(() => acks.length === 1);
+  assert.equal(acks[0].pageId, 'new-page');
+  assert.equal(acks[0].success, true);
+  assert.equal(ui.reindexBtn.disabled, false);
+
+  const { benchmarkTargets } = await import('./bench-workloads.mjs');
+  page.type = 'PAGE';
+  const frame = page.children[0];
+  frame.parent = page;
+  frame.children = Array.from({ length: 600 }, (_, i) => ({ id: `bench:${i}`, type: 'TEXT',
+    name: `Child ${i}`, characters: `Text ${i}`, parent: frame, width: 10, height: 10 }));
+  let exported = 0;
+  frame.exportAsync = async () => { exported++; return new Uint8Array([1, 2, 3]); };
+  runtime.figma.currentPage = page;
+  runtime.figma.getNodeByIdAsync = async id => id === frame.id ? frame : null;
+  const operations = [];
+  ui.READ_OPS = ['read_nodes', 'index_scan', 'export_image'];
+  ui.dispatchToMain = async req => {
+    if (!req.operation) return;
+    operations.push(req.operation);
+    try {
+      const data = await runtime.handlers[req.operation](req.params);
+      ui.ws.send(JSON.stringify({ id: req.id, sessionId: ui.sessionId, success: true, data }));
+    } catch (error) {
+      ui.ws.send(JSON.stringify({ id: req.id, sessionId: ui.sessionId, success: false, error: error.message }));
+    }
+  };
+  const measurements = await benchmarkTargets(base, [{ sessionId: ui.sessionId, nodeId: frame.id }], 1);
+  const workloads = measurements.targets[0].workloads;
+  assert.equal(workloads.readFrame.samples[0].nodes, 601);
+  assert.equal(workloads.readFrame.samples[0].pages, 2);
+  assert.equal(workloads.readFrame.samples[0].complete, true);
+  assert.equal(workloads.indexFrame.samples[0].complete, true);
+  assert.equal(workloads.exportPng.samples[0].imageBytes, 3);
+  assert.equal(exported, 1);
+  assert.deepEqual(operations, ['read_nodes', 'read_nodes', 'index_scan', 'export_image']);
+
+});

package/scripts/test-plugin-tokens.mjs

@@ -1,4 +1,5 @@
 import { test } from 'node:test';
+import { indexSyncUi } from './helpers/index-sync-ui.mjs';
 import assert from 'node:assert/strict';
 import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import os from 'node:os';
@@ -185,6 +186,76 @@ test('UI badge uses release version initially and follows the server on reconnec
   assert.ok(html.includes('type: "runtime-ready"'));
 });
 
+test('sync waits for a matching bridge confirmation and ignores final and silent progress', async () => {
+  const ui = indexSyncUi(), messages = [];
+  const page = { id: 'page', children: [] };
+  const r = runtime({ currentPage: page, root: { name: 'File' },
+    ui: { postMessage: message => { messages.push(message); ui.handleIndexMessage(message); } } });
+  r.handlers.get_styles = async () => ({});
+  r.handlers.get_variables = async () => ({});
+  for (let i = 0; i < 2; i++) {
+    await r.handlers.index_scan({ deferComponents: true });
+    assert.equal(messages.at(-1).stage, 'done');
+    assert.equal(ui.reindexBtn.disabled, true);
+    assert.match(ui.indexProgressText.textContent, /confirmation/);
+    ui.receiveIndexAck({ scanId: 'old', pageId: 'page', success: true });
+    assert.equal(ui.reindexBtn.disabled, true);
+    const update = messages.findLast(msg => msg.type === 'index-update');
+    ui.receiveIndexAck({ ...update, success: true });
+    assert.equal(ui.reindexBtn.disabled, false);
+    assert.equal(ui.reindexBtn.classList.contains('indexing'), false);
+    assert.match(ui.reindexBtn.title, /Last synced/);
+    ui.handleIndexMessage({ ...update, type: 'index-progress', stage: 'done' });
+    ui.handleIndexMessage({ ...update, type: 'index-progress', stage: 'starting', silent: true });
+    assert.equal(ui.reindexBtn.disabled, false);
+    ui.fireTimers(1200);
+    assert.equal(ui.indexProgressWrap.classList.contains('active'), false);
+  }
+});
+
+test('sync reports read failures, page cancellation, rejection, missing ack and disconnect', async () => {
+  const ui = indexSyncUi();
+  const page = { id: 'page', children: [] };
+  const r = runtime({ currentPage: page, root: { name: 'File' },
+    ui: { postMessage: message => ui.handleIndexMessage(message) } });
+  r.handlers.read_nodes = async () => { throw new Error('Cannot read layers'); };
+  await assert.rejects(r.handlers.index_scan({}), /Cannot read layers/);
+  assert.equal(ui.reindexBtn.disabled, false);
+  assert.match(ui.indexProgressText.textContent, /Cannot read layers/);
+  r.handlers.read_nodes = async () => {
+    r.figma.currentPage = { id: 'next' };
+    return { revision: 0, scope: { id: 'page' }, nodes: [] };
+  };
+  await r.handlers.index_scan({});
+  assert.equal(ui.reindexBtn.disabled, false);
+  assert.match(ui.indexProgressText.textContent, /Document changed/);
+  const start = { type: 'index-start', scanId: 'retry', pageId: 'page' };
+  ui.handleIndexMessage(start);
+  ui.receiveIndexAck({ ...start, success: false, error: 'Rejected stale revision' });
+  assert.match(ui.indexProgressText.textContent, /Rejected stale revision/);
+  ui.handleIndexMessage(start);
+  ui.handleIndexMessage({ ...start, type: 'index-update' });
+  ui.fireTimers(30000);
+  assert.equal(ui.reindexBtn.disabled, false);
+  assert.match(ui.indexProgressText.textContent, /No bridge confirmation/);
+  ui.ws.readyState = 3;
+  ui.handleIndexMessage(start);
+  assert.equal(ui.reindexBtn.disabled, false);
+  assert.match(ui.indexProgressText.textContent, /disconnected/);
+  assert.equal(ui.reindexBtn.title, 'Sync index');
+  ui.ws.readyState = 1;
+  ui.parent = { postMessage() {} };
+  ui.triggerManualReindex();
+  ui.fireTimers(30000);
+  assert.equal(ui.reindexBtn.disabled, false);
+  assert.match(ui.indexProgressText.textContent, /Canvas did not start/);
+  ui.handleIndexMessage(start);
+  ui.receiveIndexAck({ ...start, success: true });
+  ui.handleIndexMessage({ ...start, scanId: 'new' });
+  ui.fireTimers(1200);
+  assert.equal(ui.indexProgressWrap.classList.contains('active'), true);
+});
+
 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);
@@ -539,11 +610,11 @@ test('old UI socket callbacks cannot clear or dispatch through a replacement soc
     close() {} send() {}
   }
   const r = vm.createContext({
-    ws: null, wsConnected: false, sessionId: null, fileName: 'File', documentId: 'doc', BRIDGE: 'http://localhost:41730',
+    uiDisposed: false, ws: null, wsConnected: false, sessionId: null, fileName: 'File', documentId: 'doc', BRIDGE: 'http://localhost:41730',
     WebSocket: Socket, setInterval: () => 1, clearInterval: () => {}, setTimeout: () => 1, clearTimeout: () => {},
     sendRuntimeCapabilities: () => {}, consecutiveErrors: 0, everConnected: false, retryTimer: null, polling: true,
     setStatus: () => {}, log: () => {}, currentPort: 41730, READ_OPS: [],
-    startLongPoll: () => assert.fail('stale socket started poll'), dispatchToMain: req => dispatched.push(req),
+    activeIndexScan: null, startLongPoll: () => assert.fail('stale socket started poll'), dispatchToMain: req => dispatched.push(req),
   });
   vm.runInContext(source, r);
   r.connectWs(); assert.equal(sockets.length, 0);
@@ -588,3 +659,156 @@ test('tree reads preserve Regular font weight, collect Regular font tokens, and
   assert.equal(tree.textStyle, 'Lato/18px/regular');
   assert.ok(tokenCollector.fonts.has('Lato/Regular/18px'));
 });
+
+test('hot reload removes old Figma listeners and timers before installing the next runtime', async () => {
+  const events = new Map(), pageEvents = new Set(), timers = new Map(), messages = [];
+  let timerId = 0;
+  const page = { id: 'page', children: [], selection: [], on: (_, fn) => pageEvents.add(fn), off: (_, fn) => pageEvents.delete(fn) };
+  let styleName = 'Before';
+  const figma = { getLocalTextStylesAsync: async () => [{ id: 'text-style', name: styleName }], currentPage: page, root: { name: 'File', getPluginData: () => 'document' },
+    clientStorage: { getAsync: async () => null }, ui: { postMessage: msg => messages.push(msg) },
+    on: (event, fn) => { if (!events.has(event)) events.set(event, new Set()); events.get(event).add(fn); },
+    off: (event, fn) => events.get(event)?.delete(fn) };
+  const main = readFileSync('plugin-src/main.js', 'utf8');
+  const runtimes = [];
+  for (let i = 0; i < 3; i++) {
+    const r = runtime(figma);
+    r.setTimeout = (fn, delay) => { timers.set(++timerId, { fn, delay }); return timerId; };
+    r.clearTimeout = id => timers.delete(id);
+    r.__html__ = '';
+    vm.runInContext(main, r);
+    runtimes.push(r);
+    for (const listeners of events.values()) assert.equal(listeners.size, 1);
+    assert.equal(pageEvents.size, 1);
+    assert.equal(timers.size, 1, 'only the current startup timer survives');
+  }
+  assert.equal(runtimes[0].runtimeDisposed, true);
+  messages.length = 0;
+  for (const fn of events.get('selectionchange')) fn();
+  assert.equal(messages.filter(msg => msg.type === 'selection-change').length, 1);
+  const live = runtimes.at(-1);
+  assert.equal((await live.getStyleNameMapAsync())['text-style'], 'Before');
+  styleName = 'After';
+  for (const fn of events.get('stylechange')) fn({});
+  assert.equal((await live.getStyleNameMapAsync())['text-style'], 'After');
+  let releaseStyles;
+  live.handlers.get_styles = () => new Promise(resolve => { releaseStyles = resolve; });
+  live.handlers.get_variables = async () => ({});
+  const scan = live.handlers.index_scan({ deferComponents: true });
+  while (!releaseStyles) await new Promise(resolve => setTimeout(resolve, 0));
+  figma.ui.onmessage.dispose();
+  messages.length = 0;
+  releaseStyles({});
+  assert.equal((await scan).cancelled, true);
+  assert.ok(!messages.some(msg => msg.type === 'index-update'));
+  assert.equal(timers.size, 0);
+  assert.equal(pageEvents.size, 0);
+  for (const listeners of events.values()) assert.equal(listeners.size, 0);
+});
+
+test('style names share in-flight reads and refresh after invalidation or a failed getter', async () => {
+  const calls = {};
+  let name = 'Before', failPaint = false;
+  const figma = Object.fromEntries(['Paint', 'Text', 'Effect', 'Grid'].map(kind => [`getLocal${kind}StylesAsync`, async () => {
+    calls[kind] = (calls[kind] || 0) + 1;
+    if (kind === 'Paint' && failPaint) throw new Error('temporary failure');
+    return [{ id: kind, name }];
+  }]));
+  const r = runtime(figma);
+  const [first, second] = await Promise.all([r.makeWalkStateAsync({}), r.makeWalkStateAsync({})]);
+  assert.equal(first.styleMap.Text, 'Before');
+  assert.equal(second.styleMap.Paint, 'Before');
+  assert.deepEqual(Object.values(calls), [1, 1, 1, 1]);
+  name = 'After'; r.invalidateStyleNameMap();
+  assert.equal((await r.makeWalkStateAsync({})).styleMap.Text, 'After');
+  assert.deepEqual(Object.values(calls), [2, 2, 2, 2]);
+  failPaint = true; r.invalidateStyleNameMap();
+  assert.equal((await r.makeWalkStateAsync({})).styleMap.Paint, undefined);
+  failPaint = false;
+  assert.equal((await r.makeWalkStateAsync({})).styleMap.Paint, 'After');
+  assert.equal(calls.Paint, 4);
+  let release;
+  r.figma.getLocalPaintStylesAsync = () => new Promise(resolve => { release = resolve; });
+  r.invalidateStyleNameMap();
+  const old = r.getStyleNameMapAsync();
+  r.invalidateStyleNameMap();
+  r.figma.getLocalPaintStylesAsync = async () => [{ id: 'Paint', name: 'Newest' }];
+  assert.equal((await r.getStyleNameMapAsync()).Paint, 'Newest');
+  release([{ id: 'Paint', name: 'Obsolete' }]);
+  await old;
+  assert.equal((await r.getStyleNameMapAsync()).Paint, 'Newest');
+});
+
+for (const lineEnding of ['\n', '\r\n']) test(`UI reload clears previous timers, listeners and socket while keeping inline controls available (${lineEnding === '\n' ? 'LF' : 'CRLF'})`, () => {
+  const html = readFileSync('plugin-runtime/ui.html', 'utf8');
+  const source = html.match(/<script>([\s\S]*?)<\/script>/)[1].replace(/\r?\n/g, lineEnding);
+  const timers = new Set();
+  let timerId = 0, socketCloses = 0, cancelledRaf = 0;
+  const elements = new Map();
+  const target = () => {
+    const listeners = new Map();
+    return {
+      listeners, style: {}, dataset: {}, classList: { add() {}, remove() {}, contains: () => false, toggle() {} },
+      addEventListener(name, fn, options) {
+        if (options?.signal?.aborted) return;
+        if (!listeners.has(name)) listeners.set(name, new Set());
+        listeners.get(name).add(fn);
+        options?.signal?.addEventListener('abort', () => listeners.get(name).delete(fn), { once: true });
+      },
+      removeEventListener(name, fn) { listeners.get(name)?.delete(fn); },
+      setPointerCapture() {}, releasePointerCapture() {},
+      setAttribute() {}, querySelectorAll: () => [], querySelector: () => null,
+    };
+  };
+  const window = { ...target(), innerWidth: 360, innerHeight: 600,
+    setTimeout() { timers.add(++timerId); return timerId; }, clearTimeout: id => timers.delete(id),
+    setInterval() { timers.add(++timerId); return timerId; }, clearInterval: id => timers.delete(id),
+  };
+  const document = { ...target(), getElementById: id => {
+    if (!elements.has(id)) elements.set(id, target());
+    return elements.get(id);
+  }, querySelectorAll: () => [] };
+  class Socket {
+    static OPEN = 1;
+    constructor() { this.readyState = 1; }
+    close() { socketCloses++; }
+    send() {}
+  }
+  const r = vm.createContext({ window, document, WebSocket: Socket, AbortController, AbortSignal,
+    console, navigator: {}, fetch: () => new Promise(() => {}), parent: { postMessage() {} },
+    requestAnimationFrame: () => 42, cancelAnimationFrame: () => cancelledRaf++ });
+  for (let i = 0; i < 3; i++) {
+    const entryPoint = /^( {4})initConnection\(\);(?=\r?$)/m;
+    assert.match(source, entryPoint, 'startup entry point must be replaced by the socket fixture');
+    vm.runInContext(source.replace(entryPoint, "$1sessionId = 's'; connectWs();"), r);
+    assert.equal(timers.size, 1, 'only current stats interval remains');
+    assert.equal(window.listeners.get('focus').size, 1);
+    assert.equal(document.listeners.get('keydown').size, 1);
+    assert.equal(document.listeners.get('visibilitychange').size, 1);
+    for (const name of [...html.matchAll(/onclick="([A-Za-z][A-Za-z0-9_]*)\(/g)].map(match => match[1]).filter(name => name !== 'document')) {
+      assert.equal(typeof window[name], 'function', `${name} must remain available to inline controls`);
+    }
+  }
+  // Cleanup also covers a resize in progress.
+  const grip = elements.get('resize-grip');
+  for (const fn of grip.listeners.get('pointerdown')) fn({ preventDefault() {}, pointerId: 1, clientX: 0, clientY: 0 });
+  for (const fn of window.listeners.get('pointermove')) fn({ clientX: 10, clientY: 10 });
+  window.__disposeFigmaMcpUi();
+  assert.equal(timers.size, 0);
+  assert.equal(cancelledRaf, 1);
+  for (const listeners of window.listeners.values()) assert.equal(listeners.size, 0);
+  for (const listeners of document.listeners.values()) assert.equal(listeners.size, 0);
+  window.__disposeFigmaMcpUi();
+  assert.equal(cancelledRaf, 1, 'cleanup is idempotent');
+  assert.equal(socketCloses, 3);
+});
+
+
+test('creating a paint style invalidates the style names before the next design read', async () => {
+  const styles = [];
+  const r = runtime({ getLocalPaintStylesAsync: async () => styles,
+    createPaintStyle: () => { const style = { id: 'new-style' }; styles.push(style); return style; } });
+  assert.equal((await r.getStyleNameMapAsync())['new-style'], undefined);
+  await r.handlers.createPaintStyle({ name: 'Brand/New', color: '#ff0000' });
+  assert.equal((await r.getStyleNameMapAsync())['new-style'], 'Brand/New');
+});