figma-rust-mcp 3.2.8 → 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.
@@ -256,8 +256,21 @@ 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`
@@ -331,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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "figma-rust-mcp",
-  "version": "3.2.8",
-  "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": {
@@ -20,7 +20,8 @@
     "build:plugin": "node scripts/build-plugin.js",
     "test": "./scripts/test-rust-mcp.sh",
     "test:tokens": "node --test scripts/test-plugin-tokens.mjs && cargo test",
-    "dev": "cargo run"
+    "dev": "cargo run",
+    "test:sessions": "cargo build && node --test scripts/test-bridge-sessions.mjs"
   },
   "engines": {
     "node": ">=18"

package/scripts/build-plugin.js

@@ -21,6 +21,7 @@ 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",
 ];
 

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

@@ -145,3 +145,216 @@ test('build rejects wrong release tags and checked-in bundle matches source', ()
   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');
+});