figma-rust-mcp 3.2.15 → 4.0.0

package/README.md

@@ -10,9 +10,9 @@ Enables AI agents (Google Antigravity, Claude Code, Cursor, Windsurf, VS Code, Z
 
 - **Lossless Rust Tree Compression**: Compact/minimal tree responses share identical style bundles when the complete JSON becomes smaller. Node IDs, hierarchy, text, geometry and state differences remain intact. Full detail bypasses Rust compression; no heuristic merging of screens or repeated items.
 - **Pure Rust Native Performance**: 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.
+- **Scoped In-Memory Index (`figma_index`)**: Indexes page roots first and loads frame descendants on demand. Search reports the indexed scope and completeness.
 - **Binary IPC & Chunk Streaming**: Powered by **MessagePack** (`rmp-serde`) and progressive subtree chunking for instant transfers of massive design files.
-- **Incremental Diff Updates**: Sub-millisecond live document sync (`upsert_node`) keeps the server index fresh as you edit in Figma.
+- **Revisioned Updates**: Property patches update affected nodes; revision gaps trigger a fresh snapshot.
 - **Instant Design-to-Code (`figma_to_code`)**: Compiles Figma frames into clean, semantic components (**React + Tailwind**, **React Native**, **Vue 3 + Tailwind**, **HTML**, **SwiftUI**).
 - **Design Token Exporter (`figma_get_tokens`)**: Exports variables and styles to **Tailwind config**, **CSS custom properties** (`:root` & dark mode), **TypeScript consts**, or **W3C DTCG Token Studio JSON**.
 - **Batch Asset Extractor (`figma_export_assets` / `figma_export_asset`)**: Extracts SVG icons and raster images directly to project folders (`outputPath`) with auto-generated TypeScript barrel exports (`index.ts`) — zero chat token bloating.
@@ -217,7 +217,7 @@ Figma plugin only if the reported hash does not change.
 Checks live bridge connection status, connected Figma tabs/files, in-memory index health, queue length, and latency statistics.
 
 ### 2. `figma_inspect_node`
-Inspects a specific node by ID or name, returning CSS styles, flex layout rules, tokens, typography, and fills in a clean format (served in `< 1ms` via in-memory index or direct bridge).
+Reads a specific node by ID or name through the canonical flat `read_nodes` response. Select fields explicitly to control the work performed.
 
 ### 3. `figma_to_code`
 Compiles any Figma node (Frame, Component, Section, or selection) directly into clean, production-ready component code.
@@ -291,7 +291,7 @@ Instant `< 1ms` in-memory queries against pre-indexed Figma file structures.
   - `"search_components"`: Find component sets and variants.
   - `"search_styles"`: Find paint, text, and effect styles.
   - `"search_variables"`: Find design token variables by name or collection.
-  - `"refresh"`: Trigger full background re-indexing of the canvas.
+  - `"refresh"`: Refresh page roots, or expand the frame specified by `nodeId`.
   - `"subtree"`: Read/cache one `nodeId`, default depth 2 and 1000 nodes. Increase `depth` or `maxNodes` only for the section you need; check `meta` for truncation.
   - `"typography"`: Rust-generated text/font table for one `nodeId`, with mixed-style runs preserved. Default limit 200 rows. Null font fields mean unknown/mixed, not a guessed default.
 
@@ -301,8 +301,8 @@ For typography verification, call `figma_verify_ui` with a text `nodeId` and bro
 
 ### 9. `figma_read`
 Universal reader for advanced queries:
-- **Design-to-code**: `get_design_context`, `get_css`, `get_component_map`, `get_unmapped_components`.
-- **Inspection & Hierarchy**: `get_selection`, `get_design`, `get_page_nodes`, `get_node_detail`, `scan_design`, `search_nodes`.
+- **Design-to-code**: `read_nodes`, `get_css`, `get_component_map`, `get_unmapped_components`.
+- **Inspection & Hierarchy**: `read_nodes`, `get_selection`, `get_page_nodes`, `scan_design`, `search_nodes`.
 - **Design Systems**: `get_styles`, `get_variables`, `get_local_components`, `get_tokens`.
 - **Visuals & Canvas**: `screenshot`, `export_svg`, `export_image`, `get_viewport`.
 
@@ -366,23 +366,58 @@ Tools on one tab run sequentially, including every awaited operation in a
 (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.
+### Startup indexing and v4 migration
+
+Version 4 requires both server and plugin runtime protocol 3. Update both and
+restart the plugin. Opening the bridge indexes only visible top-level nodes on
+the active page, plus local styles and variables. Selection expands the selected
+frame. Component catalogue discovery is deferred; request it with
+`figma_index({ operation: "refresh", includeComponents: true })`.
+
+Search covers indexed scopes only. Inspect `scope` and `complete` in search
+responses; an empty result does not prove a layer is absent from the file.
+Refresh a specific frame to expand its scope:
+
+```js
+figma_index({ operation: "refresh", nodeId: "123:456", expandInstances: true })
+figma_read({ operation: "read_nodes", nodeId: "123:456",
+  fields: ["geometry", "content", "text", "style", "layout", "tokens", "component"],
+  limit: 200, expandInstances: true })
+// Continue using the returned cursor; do not repeat or change traversal options.
+figma_read({ operation: "read_nodes", cursor: nextCursor, limit: 200 })
+```
+
+`read_nodes` returns a flat envelope:
+`{ schemaVersion: 4, pageId, revision, scope, nodes, nextCursor, complete, totalRead, budgetReached }`.
+Identity and topology are always included. Default fields are geometry and
+content; typography, paints, layout, variable/style references and component
+metadata are opt-in. Token fields contain references, not resolved CSS values.
+Page reads default to depth 0; frame reads default to full traversal (maximum
+256 levels). Limit is 1?500 nodes per response; traversal stops at 50,000 visited
+nodes. `complete` describes the requested scope, including its depth and filters.
+Restart from the root if the page or document revision changes between cursor
+requests. Cursors are single-use and at most 16 traversals can remain open.
+
+Instances are opaque by default: `opaque: true` and no descendant traversal.
+Set `expandInstances: true` to read the actual instance children and overrides.
+Hidden nodes require `includeHidden: true`. Expansion and visibility are separate
+options; no master component is substituted for an instance.
+
+Breaking output changes: public `get_design`, `get_design_context` and
+`get_node_detail` aliases now return the same envelope as `read_nodes`.
+`figma_inspect_node` and index `get_node`, `subtree`, `typography` also return
+that envelope. Replace nested `children` consumers with `nodes` and parent/child
+IDs. Replace index `maxNodes` with `limit` and cursor pagination. Internal
+script helpers used for code generation retain their specialized formats.
+
+Canvas traversal reads each child list once, yields after an 8ms slice, and
+streams chunks of up to 500 nodes. Snapshots commit atomically; frame refreshes
+preserve other indexed frames. Revisioned create/delete/property patches
+invalidate affected cached reads, while unrelated nodes remain queryable.
+Structural additions mark coverage incomplete until the scope is reread.
+Revision gaps request resynchronization. Page switches rebuild the shallow
+index without preloading every page. Exact-read caching evicts one least
+recently used entry when its 64-entry capacity is reached.
 
 ## 💻 Development & Testing
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "figma-rust-mcp",
-  "version": "3.2.15",
+  "version": "4.0.0",
   "description": "Claude Code to Figma — Bidirectional MCP bridge. AI draws UI on Figma canvas, reads designs back. Works with Claude, Cursor, VS Code, Windsurf, Antigravity. No API key needed.",
   "mcpName": "io.github.BuiHung1612/figma-rust-mcp",
   "type": "module",

package/scripts/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/node-reader.js",
   "plugin-src/task-scope.js",
   "plugin-src/main.js",
 ];

package/scripts/test-bridge-sessions.mjs

@@ -64,6 +64,7 @@ test('multiple tabs, reconnect ownership and independent frame tasks across MCP
       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.read_nodes = async params => ({ schemaVersion: 4, pageId: 'page', revision: 0, scope: { id: params.id }, nodes: [{ id: params.id, type: 'FRAME', name: params.id, tab: sid }], nextCursor: null, complete: true });
       state.runtime.handlers.status = async () => ({ tab: sid });
       state.runtime.handlers.modify = async params => {
         actions.push(params.note);
@@ -92,11 +93,15 @@ test('multiple tabs, reconnect ownership and independent frame tasks across MCP
       });
     });
     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) }));
+    socket.send(JSON.stringify({ type: 'runtime-capabilities', runtimeVersion: 'test', protocolVersion: 3, 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 scopedSearch = decode(ok(await rpc('figma_read', { operation: 'search_nodes', query: 'child', sessionId: 'tab-a' })));
+  assert.equal(scopedSearch.complete, false);
+  assert.deepEqual(scopedSearch.nodes, []);
+
   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' });
@@ -131,9 +136,9 @@ test('multiple tabs, reconnect ownership and independent frame tasks across MCP
   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');
+  assert.equal(decode(ok(await recovering)).nodes[0].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');
+  assert.equal(decode(ok(await rpc('figma_read', { operation: 'get_design', nodeId: 'frame-b', sessionId: 'tab-a' }))).nodes[0].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' });

package/scripts/test-plugin-tokens.mjs

@@ -10,7 +10,7 @@ import { parse as parseJsonc } from 'jsonc-parser';
 
 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']) {
+  for (const file of ['utils', 'token-helpers', 'read-helpers', 'handlers-read-detail', 'handlers-read', 'handlers-tokens', 'handlers-write-ops', 'node-reader']) {
     vm.runInContext(readFileSync(`plugin-src/${file}.js`, 'utf8'), context, { filename: file });
   }
   return context;
@@ -281,6 +281,86 @@ test('startup index defers document-wide components and coalesces duplicate scan
   assert.equal(componentQueries, 1);
 });
 
+test('page index is shallow; frame reads paginate and instances expand only on request', async () => {
+  const messages = [];
+  let childReads = 0;
+  const page = { id: 'page', type: 'PAGE', children: [] };
+  const figma = { currentPage: page, skipInvisibleInstanceChildren: false,
+    root: { name: 'File', getPluginData: () => '' }, ui: { postMessage: msg => messages.push(msg) } };
+  const text = i => ({ id: 'text:' + i, name: 'Label ' + i, type: 'TEXT', characters: 'Content ' + i,
+    width: 15.5, height: 20.25, visible: true,
+    get fills() { assert.fail('projected index must not read paints'); },
+    get fontSize() { assert.fail('projected index must not read typography'); } });
+  const visible = Array.from({ length: 1200 }, (_, i) => text(i));
+  const hidden = text('hidden'); hidden.visible = false;
+  const frame = { id:'frame', name:'Frame', type:'FRAME', parent:page };
+  const instance = { id:'instance', name:'Instance', type:'INSTANCE', parent:frame,
+    get children() { childReads++; return figma.skipInvisibleInstanceChildren ? visible : [...visible,hidden]; } };
+  for (const node of [...visible,hidden]) node.parent = instance;
+  frame.children = [instance]; page.children = [frame];
+  figma.getNodeByIdAsync = async id => id === frame.id ? frame : id === instance.id ? instance : null;
+  const r = runtime(figma);
+  r.handlers.get_styles = async () => ({}); r.handlers.get_variables = async () => ({});
+  r.yieldToUI = async () => assert.equal(figma.skipInvisibleInstanceChildren, false);
+  const startup = await r.handlers.index_scan({ deferComponents:true });
+  assert.equal(startup.scope.id, page.id);
+  assert.equal(startup.scope.depth, 0);
+  assert.deepEqual(messages.filter(msg => msg.type === 'index-chunk').flatMap(msg => msg.nodes.map(n => n.id)), ['frame']);
+  assert.equal(childReads, 0);
+  const opaque = await r.handlers.read_nodes({ id:frame.id });
+  assert.equal(opaque.nodes.length, 2); assert.equal(opaque.nodes[1].opaque, true); assert.equal(childReads, 0);
+  messages.length = 0;
+  const result = await r.handlers.index_scan({ id:frame.id, expandInstances:true, deferComponents:true });
+  const chunks = messages.filter(msg => msg.type === 'index-chunk');
+  assert.deepEqual(chunks.map(msg => msg.nodes.length), [500,500,202]);
+  const nodes = chunks.flatMap(msg => plain(msg.nodes));
+  assert.equal(childReads, 1); assert.equal(result.nodesTruncated, false);
+  assert.equal(nodes.at(-1).content, 'Content 1199'); assert.equal(nodes.at(-1).width, 15.5);
+  assert.equal(nodes[1].childIds.length, 1200);
+  assert.equal(figma.skipInvisibleInstanceChildren, false);
+  const first = await r.handlers.read_nodes({ id:frame.id, expandInstances:true, limit:2 });
+  assert.ok(first.nextCursor); assert.equal(first.complete, false);
+  const next = await r.handlers.read_nodes({ cursor:first.nextCursor, limit:2 });
+  assert.deepEqual(plain(next.nodes.map(n => n.id)), ['text:0','text:1']);
+  await assert.rejects(r.handlers.read_nodes({ cursor:first.nextCursor }), /expired/);
+  await assert.rejects(r.handlers.read_nodes({ cursor:next.nextCursor, fields:['style'] }), /options cannot change/);
+  r.nodeRevision++;
+  await assert.rejects(r.handlers.read_nodes({ cursor:next.nextCursor }), /expired/);
+  const full = await r.handlers.read_nodes({ id:instance.id, includeHidden:true, expandInstances:true, limit:500 });
+  let all = [...full.nodes], cursor = full.nextCursor;
+  while(cursor) { const page = await r.handlers.read_nodes({cursor,limit:500}); all.push(...page.nodes); cursor=page.nextCursor; }
+  assert.equal(all.length, 1202); assert.equal(all.at(-1).visible, false);
+  assert.throws(() => r.withInstanceVisibility(false, () => { throw Error('read failed'); }), /read failed/);
+  assert.equal(figma.skipInvisibleInstanceChildren, false);
+});
+
+test('index yields by elapsed time and cancels when the active page changes', async () => {
+  let elapsed = 0, reads = 0, previousReads = 0, yields = 0;
+  const messages = [];
+  const page = { id: 'page', children: Array.from({ length: 30 }, (_, i) => ({
+    id: `${i}`, type: 'FRAME', get width() { elapsed += 2; reads++; return 10; },
+  })) };
+  const r = runtime({ skipInvisibleInstanceChildren: false, currentPage: page,
+    root: { name: 'File', getPluginData: () => '' }, ui: { postMessage: msg => messages.push(msg) } });
+  r.Date = { now: () => elapsed };
+  r.handlers.get_styles = async () => ({});
+  r.handlers.get_variables = async () => ({});
+  r.yieldToUI = async () => {
+    yields++;
+    assert.ok(reads - previousReads <= 4, 'yield after an 8ms slice');
+    previousReads = reads;
+    assert.equal(r.figma.skipInvisibleInstanceChildren, false);
+  };
+  await r.handlers.index_scan({ deferComponents: true });
+  assert.equal(reads, 30);
+  assert.ok(yields >= 7);
+  r.yieldToUI = async () => { r.figma.currentPage = { id: 'other', children: [] }; };
+  messages.length = 0;
+  const result = await r.handlers.index_scan({ deferComponents: true });
+  assert.equal(result.cancelled, true);
+  assert.ok(!messages.some(msg => msg.type === 'index-update'));
+});
+
 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++; } };
@@ -334,19 +414,17 @@ test('startup subscribes to active-page changes without loading the whole file',
   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'));
-  assert.deepEqual(plain(messages.filter(msg => msg.type === 'document-change').at(-1).changedNodeIds), ['changed:1']);
-  r.findNodeByIdAsync = async id => id === 'changed:1'
-    ? { id, parent: page, type: 'TEXT', fontSize: 15.5, fontWeight: 'Semi Bold' } : null;
-  r.extractDesignTree = node => ({ id: node.id, type: node.type, fontSize: node.fontSize, fontWeight: node.fontWeight });
-  pageListener({ nodeChanges: [{ type: 'DELETE', id: 'deleted:1' }] });
+  assert.ok(messages.some(msg => msg.type === 'nodes-invalidated'));
+  const changed = { id:'changed:1', type:'TEXT', parent:page, width:15.5, characters:'New' };
+  r.extractDesignTree = () => assert.fail('patch sync must not extract a tree');
+  pageListener({ nodeChanges:[{ type:'PROPERTY_CHANGE', properties:['width','characters'], node:changed }] });
+  pageListener({ nodeChanges:[{ type:'DELETE', id:'deleted:1' }] });
   await timers.filter(timer => timer.delay === 100).at(-1).callback();
-  const diff = plain(messages.filter(msg => msg.type === 'node-diff').at(-1));
-  assert.deepEqual(diff.deletedIds, ['deleted:1']);
-  assert.equal(diff.nodes[0].fontSize, 15.5);
-  assert.equal(diff.nodes[0].fontWeight, 'Semi Bold');
-  assert.equal(diff.nodes[0].parentId, page.id);
-  assert.deepEqual(diff.nodes[0].childIds, []);
+  const diff = plain(messages.filter(msg => msg.type === 'node-patch').at(-1));
+  assert.equal(diff.baseRevision, 0); assert.equal(diff.revision, 3);
+  assert.equal(diff.patches[0].values.width, 15.5); assert.equal(diff.patches[0].values.content, 'New');
+  assert.deepEqual(diff.patches[1], {kind:'delete',id:'deleted:1'});
+  assert.equal(r.nodeReadCursors.size, 0);
   const next = { id: 'page:2', on: () => {}, off: () => {} };
   r.figma.currentPage = next;
   r.handlers.index_scan = async () => ({ pageId: 'page:1' });