figma-rust-mcp 4.0.1 → 5.0.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.
@@ -18,7 +18,7 @@ Enables AI agents (Google Antigravity, Claude Code, Cursor, Windsurf, VS Code, Z
 - **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.
 - **Sandboxed JS Drawing Engine (`figma_write`)**: Powered by **Boa** (pure Rust ECMAScript engine) with built-in asset resolvers and 7 icon packs (*Ionicons, Lucide, Tabler, Bootstrap, Fluent, Phosphor*).
 - **Multi-Tab / Multi-Session Support**: Seamlessly connects to multiple open Figma files simultaneously.
-- **100% Localhost Privacy**: All communication stays strictly on `127.0.0.1:38451`.
+- **100% Localhost Privacy**: All communication stays strictly on `127.0.0.1:41730`.
 
 ---
 
@@ -30,13 +30,13 @@ 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)                        │
 │  • Binary MessagePack & Progressive Subtree Chunk Receiver             │
 └───────────────▲────────────────────────────────────────▲───────────────┘
-                │ (ws://127.0.0.1:38451/ws)              │ (http://127.0.0.1:38451/mcp)
+                │ (ws://127.0.0.1:41730/ws)              │ (http://127.0.0.1:41730/mcp)
                 │ (Dynamic Code Streaming & Hot-Reload)  │ (JSON-RPC 2.0 / Streamable HTTP)
       ┌─────────┴─────────┐                    ┌─────────┴─────────┐
       │   Figma Desktop   │                    │ AI Assistant(s)   │
@@ -50,9 +50,10 @@ Enables AI agents (Google Antigravity, Claude Code, Cursor, Windsurf, VS Code, Z
 
 ### 🔌 How the Zero-Touch Connection Works:
 1. **Permanent Thin Loader**: You only import the Figma plugin **once** (`~/.figma-rust-mcp/plugin/manifest.json`).
-2. **Dynamic Runtime Streaming**: Upon launch, the Thin Loader contacts `http://127.0.0.1:38451/plugin/code.js` to fetch and execute the latest runtime in memory.
-3. **Live WebSocket Hot-Reload**: The plugin connects to `ws://127.0.0.1:38451/ws`. When you upgrade `figma-rust-mcp` or restart the daemon, the plugin automatically detects the new server version and hot-reloads seamlessly — **no need to re-import or restart the plugin in Figma**.
+2. **Dynamic Runtime Streaming**: Upon launch, the Thin Loader contacts `http://127.0.0.1:41730/plugin/code.js` to fetch and execute the latest runtime in memory.
+3. **Live WebSocket Hot-Reload**: The plugin connects to `ws://127.0.0.1:41730/ws`. When you upgrade `figma-rust-mcp` or restart the daemon, the plugin automatically detects the new server version and hot-reloads seamlessly — **no need to re-import or restart the plugin in Figma**.
 4. **Auto-Reconnect & Offline Buffer**: If Figma is opened before the Rust service starts, the plugin displays a waiting screen and connects automatically the instant the service is up.
+5. **Port Range & Auto-Switch**: The bridge uses ports `41730–41739`. On start it reuses a running server of the same version, skips any port held by another app or a different figma-rust-mcp version, and starts on the first free port. The plugin scans the same range, so it follows automatically. MCP clients configured by URL point at `41730`; the server prints a warning with the new port if it had to move.
 
 ---
 
@@ -148,13 +149,13 @@ Use the `/mcp` endpoint. It accepts `POST` JSON-RPC requests directly:
 
 ```toml
 [mcp_servers.figma-rust-mcp]
-url = "http://127.0.0.1:38451/mcp"
+url = "http://127.0.0.1:41730/mcp"
 ```
 
 For Codex CLI, the equivalent command is:
 
 ```bash
-codex mcp add figma-rust-mcp --url http://127.0.0.1:38451/mcp
+codex mcp add figma-rust-mcp --url http://127.0.0.1:41730/mcp
 ```
 
 #### Google Antigravity (SSE Transport)
@@ -163,7 +164,7 @@ Add to your `~/.gemini/config/mcp_config.json` or project `.agents/mcp_config.js
 {
   "mcpServers": {
     "figma-rust-mcp": {
-      "serverUrl": "http://127.0.0.1:38451/sse"
+      "serverUrl": "http://127.0.0.1:41730/sse"
     }
   }
 }
@@ -176,7 +177,7 @@ These clients can use the Streamable HTTP `/mcp` endpoint:
 {
   "mcpServers": {
     "figma-rust-mcp": {
-      "url": "http://127.0.0.1:38451/mcp"
+      "url": "http://127.0.0.1:41730/mcp"
     }
   }
 }
@@ -200,7 +201,7 @@ Alternatively, configure a stdio subprocess via NPX:
 Check the runtime bundle currently served to Figma Desktop:
 
 ```bash
-curl http://127.0.0.1:38451/plugin/version
+curl http://127.0.0.1:41730/plugin/version
 ```
 
 The response includes `version` and `runtimeHash`. If the hash changes after an
@@ -283,7 +284,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 +316,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 +420,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/agent-config.js

@@ -4,7 +4,7 @@ import os from 'node:os';
 import { applyEdits, modify, parse } from 'jsonc-parser';
 
 const SERVER_NAME = 'figma-rust-mcp';
-const HTTP_URL = 'http://127.0.0.1:38451/mcp';
+const HTTP_URL = 'http://127.0.0.1:41730/mcp';
 
 function existsAny(paths) {
   return paths.some(candidate => candidate && fs.existsSync(candidate));
@@ -78,7 +78,7 @@ function upsertCodex(filePath) {
 
 export function configureAgent(agent) {
   const entry = agent.id === 'antigravity'
-    ? { serverUrl: 'http://127.0.0.1:38451/sse' }
+    ? { serverUrl: 'http://127.0.0.1:41730/sse' }
     : agent.id === 'claude' || agent.id === 'vscode'
       ? { type: 'http', url: HTTP_URL }
       : { url: HTTP_URL };

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": "5.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",
@@ -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/plugin/manifest.json

@@ -5,21 +5,33 @@
   "main": "code.js",
   "ui": "ui.html",
   "documentAccess": "dynamic-page",
-  "editorType": ["figma", "dev"],
+  "editorType": [
+    "figma",
+    "dev"
+  ],
   "networkAccess": {
     "allowedDomains": [
-      "http://localhost:38451",
-      "http://localhost:38452",
-      "http://localhost:38453",
-      "http://localhost:38454",
-      "http://localhost:38455",
-      "ws://localhost:38451",
-      "ws://localhost:38452",
-      "ws://localhost:38453",
-      "ws://localhost:38454",
-      "ws://localhost:38455"
+      "http://localhost:41730",
+      "http://localhost:41731",
+      "http://localhost:41732",
+      "http://localhost:41733",
+      "http://localhost:41734",
+      "http://localhost:41735",
+      "http://localhost:41736",
+      "http://localhost:41737",
+      "http://localhost:41738",
+      "http://localhost:41739",
+      "ws://localhost:41730",
+      "ws://localhost:41731",
+      "ws://localhost:41732",
+      "ws://localhost:41733",
+      "ws://localhost:41734",
+      "ws://localhost:41735",
+      "ws://localhost:41736",
+      "ws://localhost:41737",
+      "ws://localhost:41738",
+      "ws://localhost:41739"
     ],
-    "reasoning": "Thin loader connecting dynamically to the local figma-rust-mcp Rust engine on ports 38451-38455."
+    "reasoning": "Thin loader connecting dynamically to the local figma-rust-mcp Rust engine on ports 41730-41739."
   }
 }
-

package/plugin/ui.html

@@ -6,18 +6,18 @@
   <title>Figma Rust MCP Loader</title>
   <style>
     :root {
-      --bg: #0d0e12;
-      --surface-base: #12141a;
-      --surface-card: #171922;
-      --border-subtle: rgba(255, 255, 255, 0.08);
-      --border-ghost: rgba(147, 129, 255, 0.35);
-      --text-primary: #f4f4f7;
-      --text-secondary: #9aa1b2;
-      --text-muted: #52596d;
-      --ghost-lavender: #9381ff;
-      --ghost-mint: #34d399;
-      --font-ui: -apple-system, BlinkMacSystemFont, 'Inter', 'SF Pro Text', sans-serif;
-      --font-mono: 'JetBrains Mono', 'SF Mono', Menlo, monospace;
+      --bg: #fdf1dc;
+      --surface-base: #fffaf0;
+      --surface-card: #fffdf7;
+      --border-subtle: #1c1a17;
+      --border-ghost: #1c1a17;
+      --text-primary: #1c1a17;
+      --text-secondary: #4a453d;
+      --text-muted: #7d7567;
+      --ghost-lavender: #f4532c;
+      --ghost-mint: #2f8f3a;
+      --font-ui: ui-rounded, 'SF Pro Rounded', -apple-system, BlinkMacSystemFont, 'Inter', sans-serif;
+      --font-mono: ui-monospace, 'SF Mono', 'JetBrains Mono', Menlo, monospace;
     }
     *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
     html, body { width: 100%; height: 100%; overflow: hidden; background: var(--bg); color: var(--text-primary); font-family: var(--font-ui); font-size: 11px; }
@@ -58,7 +58,7 @@
       height: 14px;
       border-radius: 50%;
       background: var(--ghost-lavender);
-      box-shadow: 0 0 16px var(--ghost-lavender);
+      border: 2px solid #1c1a17;
     }
 
     @keyframes pulse {
@@ -85,7 +85,8 @@
       gap: 6px;
       padding: 4px 10px;
       background: var(--surface-card);
-      border: 1px solid var(--border-subtle);
+      border: 2px solid var(--border-subtle);
+      box-shadow: 2px 2px 0 #1c1a17;
       border-radius: 9999px;
       font-family: var(--font-mono);
       font-size: 10px;
@@ -94,7 +95,8 @@
     }
     .hint-box {
       background: var(--surface-base);
-      border: 1px solid var(--border-subtle);
+      border: 2px solid var(--border-subtle);
+      box-shadow: 2px 2px 0 #1c1a17;
       border-radius: 8px;
       padding: 10px 12px;
       max-width: 280px;
@@ -108,7 +110,7 @@
       color: var(--ghost-lavender);
       display: block;
       margin-top: 4px;
-      background: rgba(0,0,0,0.3);
+      background: rgba(28,26,23,0.06);
       padding: 3px 6px;
       border-radius: 4px;
     }
@@ -123,9 +125,9 @@
       <div class="radar-core"></div>
     </div>
     <div class="title">Connecting to figma-rust-mcp</div>
-    <div id="status" class="status-text">Scanning local ports (38451-38455)...</div>
+    <div id="status" class="status-text">Scanning local ports (41730-41739)...</div>
     <div class="badge">
-      <span>●</span> <span id="port-label">localhost:38451</span>
+      <span>●</span> <span id="port-label">localhost:41730</span>
     </div>
     <div class="hint-box">
       Ensure the local Rust server is running:
@@ -134,7 +136,8 @@
   </div>
 
   <script>
-    const PORTS = [38451, 38452, 38453, 38454, 38455];
+    // Must match DEFAULT_PORT / PORT_RANGE in src/bridge/server.rs and manifest.json.
+    const PORTS = Array.from({ length: 10 }, (_, i) => 41730 + i);
     let attempts = 0;
 
     async function checkPort(port) {
@@ -148,8 +151,9 @@
         clearTimeout(timeoutId);
         if (res.ok) {
           const data = await res.json();
-          return { ok: true, data };
+          if (data && data.name === "figma-rust-mcp") return { ok: true, data };
         }
+        return { ok: false, answered: true };
       } catch (_) {
         clearTimeout(timeoutId);
       }
@@ -174,7 +178,8 @@
         if (!uiRes.ok) throw new Error("Failed to load plugin UI: " + uiRes.status);
         const uiHtml = await uiRes.text();
 
-        // 3. Inject full UI cleanly
+        // 3. Inject full UI cleanly; the runtime reads the port from here (globals survive document.open).
+        window.__FIGMA_MCP_PORT = port;
         document.open();
         document.write(uiHtml);
         document.close();
@@ -190,17 +195,20 @@
       const statusEl = document.getElementById("status");
       const portEl = document.getElementById("port-label");
 
-      for (const port of PORTS) {
-        if (portEl) portEl.textContent = `localhost:${port}`;
-        const result = await checkPort(port);
-        if (result.ok) {
-          await bootstrapFromPort(port);
-          return;
-        }
+      if (portEl) portEl.textContent = `localhost:${PORTS[0]}-${PORTS[PORTS.length - 1]}`;
+      const results = await Promise.all(PORTS.map(checkPort));
+      const hit = results.findIndex(r => r.ok);
+      if (hit >= 0) {
+        if (portEl) portEl.textContent = `localhost:${PORTS[hit]}`;
+        await bootstrapFromPort(PORTS[hit]);
+        return;
       }
 
       if (statusEl) {
-        statusEl.textContent = `Waiting for server (attempt #${attempts})...`;
+        const busy = PORTS.filter((_, i) => results[i].answered);
+        statusEl.textContent = busy.length
+          ? `Port ${busy.join(", ")} answered but is not a compatible figma-rust-mcp. Run: npx -y figma-rust-mcp@latest --install-service (attempt #${attempts})`
+          : `Waiting for server (attempt #${attempts})...`;
       }
       setTimeout(findAndConnect, 1000);
     }

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();
+}

package/scripts/test-plugin-tokens.mjs

@@ -53,6 +53,20 @@ test('compact tree and scan preserve mixed typography instead of using the first
   assert.equal(r.resolveTextStyle(node).fontWeight, undefined);
 });
 
+test('scan_design expands instances by default and flags opaque ones as incomplete', async () => {
+  const text = { id: '1:3', name: 'Label', type: 'TEXT', characters: 'Hi', fontSize: 12, fontName: { family: 'Inter', style: 'Regular' }, visible: true };
+  const inst = { id: '1:2', name: 'Button', type: 'INSTANCE', visible: true, children: [text], getMainComponentAsync: async () => null };
+  const frame = { id: '1:1', name: 'Frame', type: 'FRAME', visible: true, children: [inst] };
+  const r = runtime({ root: { id: '0:0' }, currentPage: { id: '0:1' }, getNodeByIdAsync: async () => frame });
+  const full = plain(await r.handlers.scan_design({ id: '1:1' }));
+  assert.equal(full.totals.textNodes, 1);
+  assert.equal(full.complete, true);
+  const opaque = plain(await r.handlers.scan_design({ id: '1:1', expandInstances: false }));
+  assert.equal(opaque.totals.textNodes, 0);
+  assert.equal(opaque.totals.opaqueInstances, 1);
+  assert.equal(opaque.complete, false);
+});
+
 test('equivalent CSS syntaxes preserve alpha in reads and writes', () => {
   const r = runtime();
   for (const color of ['rgba(255, 0, 0, .5)', 'rgb(100% 0% 0% / 50%)', 'hsl(0 100% 50% / .5)', 'hsla(0, 100%, 50%, .5)']) {
@@ -204,8 +218,8 @@ test('agent setup detects installed clients and preserves existing JSONC and TOM
       configureAgent(agent);
       const config = parseJsonc(readFileSync(agent.configPath, 'utf8')).mcpServers['figma-rust-mcp'];
       assert.ok(config);
-      if (id === 'antigravity') assert.equal(config.serverUrl, 'http://127.0.0.1:38451/sse');
-      else assert.equal(config.url, 'http://127.0.0.1:38451/mcp');
+      if (id === 'antigravity') assert.equal(config.serverUrl, 'http://127.0.0.1:41730/sse');
+      else assert.equal(config.url, 'http://127.0.0.1:41730/mcp');
     }
 
     const cursor = agents.find(agent => agent.id === 'cursor');
@@ -215,21 +229,21 @@ test('agent setup detects installed clients and preserves existing JSONC and TOM
     const cursorConfig = parseJsonc(cursorText);
     assert.match(cursorText, /keep this note/);
     assert.equal(cursorConfig.mcpServers.other.url, 'http://example.test');
-    assert.equal(cursorConfig.mcpServers['figma-rust-mcp'].url, 'http://127.0.0.1:38451/mcp');
+    assert.equal(cursorConfig.mcpServers['figma-rust-mcp'].url, 'http://127.0.0.1:41730/mcp');
     assert.equal(configureAgent(cursor), false);
 
     const zed = agents.find(agent => agent.id === 'zed');
     writeFileSync(zed.configPath, '{\n  "theme": "One Dark",\n}\n');
     configureAgent(zed);
     assert.equal(parseJsonc(readFileSync(zed.configPath, 'utf8')).theme, 'One Dark');
-    assert.equal(parseJsonc(readFileSync(zed.configPath, 'utf8')).context_servers['figma-rust-mcp'].url, 'http://127.0.0.1:38451/mcp');
+    assert.equal(parseJsonc(readFileSync(zed.configPath, 'utf8')).context_servers['figma-rust-mcp'].url, 'http://127.0.0.1:41730/mcp');
 
     const codex = agents.find(agent => agent.id === 'codex');
     writeFileSync(codex.configPath, '[mcp_servers.other]\nurl = "http://other.test"\n');
     configureAgent(codex);
     const codexText = readFileSync(codex.configPath, 'utf8');
     assert.match(codexText, /\[mcp_servers\.other\]/);
-    assert.match(codexText, /\[mcp_servers\.figma-rust-mcp\]\nurl = "http:\/\/127\.0\.0\.1:38451\/mcp"/);
+    assert.match(codexText, /\[mcp_servers\.figma-rust-mcp\]\nurl = "http:\/\/127\.0\.0\.1:41730\/mcp"/);
     assert.equal(configureAgent(codex), false);
   } finally {
     rmSync(home, { recursive: true, force: true });
@@ -525,10 +539,10 @@ 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:38451',
+    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: 38451, READ_OPS: [],
+    setStatus: () => {}, log: () => {}, currentPort: 41730, READ_OPS: [],
     startLongPoll: () => assert.fail('stale socket started poll'), dispatchToMain: req => dispatched.push(req),
   });
   vm.runInContext(source, r);