figma-rust-mcp 4.0.1 → 4.1.0

package/README.md

@@ -9,7 +9,7 @@ Enables AI agents (Google Antigravity, Claude Code, Cursor, Windsurf, VS Code, Z
 ## ⚡ Highlights
 
 - **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.
+- **Pure Rust Native Performance**: Single native binary, no runtime or GC. Measure it on your machine with `npm run bench` or the plugin's **Bench** tab (see [Benchmarks](#-benchmarks)).
 - **Scoped In-Memory Index (`figma_index`)**: Indexes page roots first and loads frame descendants on demand. Search reports the indexed scope and completeness.
 - **Binary IPC & Chunk Streaming**: Powered by **MessagePack** (`rmp-serde`) and progressive subtree chunking for instant transfers of massive design files.
 - **Revisioned Updates**: Property patches update affected nodes; revision gaps trigger a fresh snapshot.
@@ -30,7 +30,7 @@ Enables AI agents (Google Antigravity, Claude Code, Cursor, Windsurf, VS Code, Z
 │                       figma-rust-mcp (Pure Rust Engine)                     │
 │  • MCP Streamable HTTP (/mcp) & legacy SSE (/sse, /message)             │
 │  • Dynamic Runtime Server (/plugin/code.js, /plugin/ui.html)           │
-│  • In-Memory Fast Index (<1ms Lookups & Incremental Diffs)             │
+│  • In-Memory Fast Index (Scoped Lookups & Incremental Diffs)           │
 │  • Design-to-Code Compiler (React/Tailwind, Vue, RN, SwiftUI)          │
 │  • Design Token Transformer (CSS, Tailwind, TypeScript, W3C DTCG)      │
 │  • Sandboxed JS Runtime (Boa ECMAScript Engine)                        │
@@ -283,7 +283,7 @@ Batch extracts all SVG icons and PNG images from a Figma frame/page directly int
 - **`createBarrel`**: Automatically creates an `index.ts` barrel export file in `iconDir`.
 
 ### 8. `figma_index`
-Instant `< 1ms` in-memory queries against pre-indexed Figma file structures.
+In-memory queries against pre-indexed Figma file structures (latency for your file: plugin **Bench** tab).
 - **`operation`**:
   - `"status"`: View index health and node counts.
   - `"search_nodes"`: Search nodes by text name, query, and type (`FRAME`, `TEXT`, `COMPONENT`, `INSTANCE`).
@@ -315,7 +315,7 @@ Executes JavaScript draw commands inside the sandboxed VM to build or modify des
 - Supports Prototyping & Reactions: `setReactions`, `getReactions`, `setScrollBehavior`.
 
 ### 11. `figma_rules`
-Audits the current Figma document and generates a complete design system rule sheet (color tokens, typography styles, variables, component catalog) in `< 1ms` from cache.
+Audits the current Figma document and generates a complete design system rule sheet (color tokens, typography styles, variables, component catalog) from the in-memory cache.
 
 ### 12. `figma_docs`
 Fetches built-in documentation, design rules, layout guidelines, and code examples for `figma_write`.
@@ -419,6 +419,24 @@ 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.
 
+## 📏 Benchmarks
+
+`npm run bench` builds the release binary, spawns it on a random port and prints:
+
+| Metric | How it is measured |
+|---|---|
+| 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.
+
 ## 💻 Development & Testing
 
 ```bash

package/bin/figma-rust-mcp.js

@@ -435,6 +435,14 @@ function isNewer(latest, current) {
   return false;
 }
 
+// --upgrade stays on the installed major; a new major is announced but never auto-installed.
+function updateNotice(latest) {
+  if (latest.split('.')[0] !== pkgVersion.split('.')[0]) {
+    return `\n\x1b[36m⚡ v${latest} is a new major release with breaking changes (see CHANGELOG).\x1b[0m\n\x1b[36m   Opt in: npm install -g figma-rust-mcp@latest\x1b[0m\n\n`;
+  }
+  return `\n\x1b[36m⚡ Update available: v${pkgVersion} → v${latest}\x1b[0m\n\x1b[36m   Run: npx figma-rust-mcp --upgrade\x1b[0m\n\n`;
+}
+
 function checkForUpdatesAsync() {
   const updateStateFile = path.join(os.homedir(), '.figma-rust-mcp', 'update-check.json');
   try {
@@ -443,7 +451,7 @@ function checkForUpdatesAsync() {
       const now = Date.now();
       if (state.lastChecked && (now - state.lastChecked < 6 * 3600 * 1000)) {
         if (state.latestVersion && isNewer(state.latestVersion, pkgVersion)) {
-          process.stderr.write(`\n\x1b[36m⚡ Update available: v${pkgVersion} → v${state.latestVersion} (Run: npx figma-rust-mcp --upgrade)\x1b[0m\n\n`);
+          process.stderr.write(updateNotice(state.latestVersion));
         }
         return;
       }
@@ -467,7 +475,7 @@ function checkForUpdatesAsync() {
             latestVersion: latest
           }, null, 2));
           if (latest && isNewer(latest, pkgVersion)) {
-            process.stderr.write(`\n\x1b[36m⚡ Update available: v${pkgVersion} → v${latest}\x1b[0m\n\x1b[36m   Run: npx figma-rust-mcp --upgrade\x1b[0m\n\n`);
+            process.stderr.write(updateNotice(latest));
           }
         }
       } catch (_) {}
@@ -480,8 +488,9 @@ function checkForUpdatesAsync() {
 async function upgrade() {
   console.log('\x1b[36m[figma-rust-mcp]\x1b[0m Checking for updates and upgrading figma-rust-mcp...');
   try {
-    execSync('npm install -g figma-rust-mcp@latest', { stdio: 'inherit' });
-    console.log('\x1b[32m✓ Upgraded figma-rust-mcp to latest version.\x1b[0m');
+    const major = pkgVersion ? pkgVersion.split('.')[0] : 'latest';
+    execSync(`npm install -g figma-rust-mcp@${major}`, { stdio: 'inherit' });
+    console.log(`\x1b[32m✓ Upgraded figma-rust-mcp (${major === 'latest' ? 'latest' : `v${major}.x`}).\x1b[0m`);
     setupPlugin();
     if (isServiceInstalled()) {
       console.log('\x1b[36mUpdating background service binary...\x1b[0m');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "figma-rust-mcp",
-  "version": "4.0.1",
+  "version": "4.1.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",
@@ -20,6 +20,7 @@
     "test": "./scripts/test-rust-mcp.sh",
     "test:tokens": "node --test scripts/test-plugin-tokens.mjs && cargo test",
     "dev": "cargo run",
+    "bench": "cargo build --release && node scripts/bench.mjs",
     "test:sessions": "cargo build && node --test scripts/test-bridge-sessions.mjs"
   },
   "engines": {

package/scripts/bench.mjs

@@ -0,0 +1,37 @@
+// 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";
+
+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;
+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));
+    }
+  }
+  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}`);
+} finally {
+  child.kill();
+}