@sarjallab09/figma-intelligence 1.0.1 → 1.1.0

package/figma-bridge-plugin/bridge-relay.js

@@ -1220,6 +1220,83 @@ function requestFromPlugin(method, params, timeoutMs = 15000) {
   });
 }
 
+// ── UX Researcher: capture current Figma selection as compact context ────────
+
+const SELECTION_CONTEXT_MAX_CHARS = 3000;
+const SELECTION_MAX_NODES = 5;
+
+async function captureSelectionContext() {
+  const selection = await requestFromPlugin("getSelection", {});
+  if (!selection || !Array.isArray(selection) || selection.length === 0) return null;
+
+  const nodesToFetch = selection.slice(0, SELECTION_MAX_NODES);
+  const nodeDetails = await Promise.all(
+    nodesToFetch.map((n) => requestFromPlugin("getNode", { nodeId: n.id }).catch(() => null))
+  );
+
+  const lines = [];
+  for (const node of nodeDetails) {
+    if (!node) continue;
+    lines.push(formatNodeForContext(node, 0));
+  }
+  if (selection.length > SELECTION_MAX_NODES) {
+    lines.push(`[... ${selection.length - SELECTION_MAX_NODES} more selected nodes omitted]`);
+  }
+
+  let body = lines.join("\n");
+  if (body.length > SELECTION_CONTEXT_MAX_CHARS) {
+    body = body.slice(0, SELECTION_CONTEXT_MAX_CHARS) + "\n[... truncated for brevity]";
+  }
+
+  return `=== CURRENT FIGMA SELECTION ===\n${body}\n=== END SELECTION ===`;
+}
+
+function formatNodeForContext(node, depth) {
+  const indent = "  ".repeat(depth);
+  const parts = [`${indent}[${node.type}] "${node.name}"`];
+
+  // Dimensions
+  if (node.width != null && node.height != null) {
+    parts[0] += ` (${Math.round(node.width)}×${Math.round(node.height)})`;
+  }
+
+  // Auto-layout
+  if (node.layoutMode && node.layoutMode !== "NONE") {
+    parts.push(`${indent}  layout: ${node.layoutMode}, spacing: ${node.itemSpacing}px, padding: ${node.paddingTop}/${node.paddingRight}/${node.paddingBottom}/${node.paddingLeft}`);
+  }
+
+  // Text content
+  if (node.characters) {
+    const text = node.characters.length > 120 ? node.characters.slice(0, 120) + "…" : node.characters;
+    parts.push(`${indent}  text: "${text}"`);
+    if (node.fontSize) parts.push(`${indent}  fontSize: ${node.fontSize}`);
+  }
+
+  // Component instance
+  if (node.mainComponentName) {
+    parts.push(`${indent}  component: ${node.mainComponentName}`);
+  }
+
+  // Corner radius
+  if (node.cornerRadius != null && node.cornerRadius > 0) {
+    parts.push(`${indent}  radius: ${node.cornerRadius}`);
+  }
+
+  // Children (1 level deep)
+  if (node.children && node.children.length > 0) {
+    const maxChildren = 10;
+    const shown = node.children.slice(0, maxChildren);
+    for (const child of shown) {
+      parts.push(`${indent}  - [${child.type}] "${child.name}"`);
+    }
+    if (node.children.length > maxChildren) {
+      parts.push(`${indent}  ... +${node.children.length - maxChildren} more children`);
+    }
+  }
+
+  return parts.join("\n");
+}
+
 function sendToVscode(payload, targetWs) {
   if (targetWs && targetWs.readyState === 1) {
     targetWs.send(JSON.stringify(payload));
@@ -2200,6 +2277,38 @@ wss.on("connection", (ws, req) => {
           const anthropicKey = getAnthropicApiKey();
           if (chatMode === "chat" && anthropicKey) {
             // Tier 3: Direct Anthropic API — fast streaming (~200ms first token)
+            const isResearcher = msg.researcherMode === true;
+
+            if (isResearcher) {
+              // UX Researcher mode: async — capture selection, force Haiku, use researcher prompt
+              (async () => {
+                try {
+                  const selectionCtx = await captureSelectionContext();
+                  if (selectionCtx) {
+                    chatMessage = selectionCtx + "\n\n" + chatMessage;
+                    console.log("  🔬 Researcher: attached Figma selection context");
+                  }
+                } catch (e) {
+                  console.error("  ⚠ Researcher selection capture failed:", e.message);
+                }
+
+                const { buildUxResearcherPrompt } = require("./shared-prompt-config");
+                proc = runAnthropicChat({
+                  message: chatMessage,
+                  attachments: msg.attachments,
+                  conversation: msg.conversation,
+                  requestId,
+                  apiKey: anthropicKey,
+                  model: "claude-haiku-4-5-20251001",
+                  systemPrompt: buildUxResearcherPrompt(),
+                  onEvent,
+                });
+                activeChatProcesses.set(requestId, proc);
+                proc.on("close", () => activeChatProcesses.delete(requestId));
+              })();
+              return;
+            }
+
             const { buildChatPrompt } = require("./shared-prompt-config");
             proc = runAnthropicChat({
               message: chatMessage,
@@ -2213,6 +2322,39 @@ wss.on("connection", (ws, req) => {
             });
           } else {
             // Tier 4: Claude CLI subprocess (code/dual mode, or no API key)
+            const cliResearcher = msg.researcherMode === true && chatMode === "chat";
+
+            if (cliResearcher) {
+              // Researcher mode via CLI: async — capture selection, then spawn CLI
+              (async () => {
+                try {
+                  const selectionCtx = await captureSelectionContext();
+                  if (selectionCtx) {
+                    chatMessage = selectionCtx + "\n\n" + chatMessage;
+                    console.log("  🔬 Researcher (CLI): attached Figma selection context");
+                  }
+                } catch (e) {
+                  console.error("  ⚠ Researcher selection capture failed:", e.message);
+                }
+
+                proc = runClaude({
+                  message: chatMessage,
+                  attachments: msg.attachments,
+                  conversation: msg.conversation,
+                  requestId,
+                  model: msg.model,
+                  designSystemId: activeDesignSystemId,
+                  mode: chatMode,
+                  frameworkConfig: msg.frameworkConfig || {},
+                  researcherMode: true,
+                  onEvent,
+                });
+                activeChatProcesses.set(requestId, proc);
+                proc.on("close", () => activeChatProcesses.delete(requestId));
+              })();
+              return;
+            }
+
             proc = runClaude({
               message: chatMessage,
               attachments: msg.attachments,

package/figma-bridge-plugin/chat-runner.js

@@ -19,6 +19,7 @@ const {
   SYSTEM_PROMPT,
   buildSystemPrompt,
   buildChatPrompt,
+  buildUxResearcherPrompt,
   buildDualOutputPrompt,
   buildSkillAddendum,
   detectActiveSkills,
@@ -26,6 +27,7 @@ const {
 } = require("./shared-prompt-config");
 
 const MCP_CONFIG_PATH = join(tmpdir(), "figma-intelligence-chat-mcp.json");
+const EMPTY_MCP_CONFIG_PATH = join(tmpdir(), "figma-intelligence-no-mcp.json");
 const CLAUDE_SETTINGS_PATH = join(homedir(), ".claude", "settings.json");
 
 // Use the absolute claude binary path stored by setup.sh in launchd env.
@@ -118,6 +120,8 @@ function writeMcpConfig(bridgePort) {
 
 // Write initial config (will be rewritten with actual port once relay starts)
 writeMcpConfig();
+// Write empty MCP config for researcher mode (no tools)
+try { writeFileSync(EMPTY_MCP_CONFIG_PATH, JSON.stringify({ mcpServers: {} })); } catch {}
 
 function getCleanEnv() {
   const env = { ...process.env };
@@ -175,17 +179,27 @@ function processAttachments(attachments) {
 const CLAUDE_DEFAULT_MODEL = "claude-opus-4-6";
 const CLAUDE_VALID_MODELS = new Set(["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5-20251001"]);
 
-function runClaude({ message, attachments, conversation, requestId, model, designSystemId, mode, frameworkConfig, onEvent }) {
+function runClaude({ message, attachments, conversation, requestId, model, designSystemId, mode, frameworkConfig, researcherMode, onEvent }) {
   const { imageArgs, extraText, tempFiles } = processAttachments(attachments);
 
-  const resolvedModel = CLAUDE_VALID_MODELS.has(model) ? model : CLAUDE_DEFAULT_MODEL;
+  const isResearcher = researcherMode === true;
+  const resolvedModel = isResearcher ? "claude-haiku-4-5-20251001" : (CLAUDE_VALID_MODELS.has(model) ? model : CLAUDE_DEFAULT_MODEL);
   const sessionMode = mode || "code";
 
   const rawText = (message || "").trim() || (extraText ? "Please analyse the attached image(s) and help me create a Figma design based on them." : "");
   const userText = rawText; // No more expandShortPrompt — Claude handles short prompts natively
 
   // Detect active skills early — needed for session reset decision
-  const skills = (sessionMode === "code" || sessionMode === "dual") ? detectActiveSkills(userText) : [];
+  // Skip skill detection in researcher mode — it's a pure chat persona
+  const skills = (!isResearcher && (sessionMode === "code" || sessionMode === "dual")) ? detectActiveSkills(userText) : [];
+
+  // Force new session when researcher mode is toggled.
+  // The researcher session uses a different system prompt and no MCP tools,
+  // so it cannot share a session with normal chat mode.
+  if (isResearcher && activeSessionIds[sessionMode]) {
+    console.log(`[chat-runner] Researcher mode — resetting ${sessionMode} session for researcher prompt`);
+    activeSessionIds[sessionMode] = null;
+  }
 
   // Force new session when Component Doc Generator skill is detected.
   // This ensures the system prompt includes the spec-type reference and
@@ -217,6 +231,8 @@ function runClaude({ message, attachments, conversation, requestId, model, desig
     }
     const modeLabel = sessionMode === "dual" ? "Dual (Design + Code)" : "Code";
     onEvent({ type: "phase_start", id: requestId, phase: `${modeLabel} · ${resolvedModel} · MCP: figma-intelligence-layer` });
+  } else if (isResearcher) {
+    onEvent({ type: "phase_start", id: requestId, phase: `UX Researcher · ${resolvedModel}` });
   } else {
     onEvent({ type: "phase_start", id: requestId, phase: `Chat · ${resolvedModel}` });
   }
@@ -225,7 +241,9 @@ function runClaude({ message, attachments, conversation, requestId, model, desig
   if (isFirstMessage) {
     // First message: create session with full config
     let baseSystemPrompt;
-    if (sessionMode === "chat") {
+    if (isResearcher) {
+      baseSystemPrompt = buildUxResearcherPrompt();
+    } else if (sessionMode === "chat") {
       baseSystemPrompt = buildChatPrompt();
     } else if (sessionMode === "dual") {
       baseSystemPrompt = buildDualOutputPrompt(designSystemId, frameworkConfig);
@@ -249,6 +267,10 @@ function runClaude({ message, attachments, conversation, requestId, model, desig
     if (sessionMode === "code" || sessionMode === "dual") {
       args.push("--mcp-config", MCP_CONFIG_PATH, "--strict-mcp-config");
     }
+    // Researcher mode: block ALL MCP tools — pure chat persona
+    if (isResearcher) {
+      args.push("--mcp-config", EMPTY_MCP_CONFIG_PATH, "--strict-mcp-config");
+    }
   } else {
     // Subsequent messages: resume session — context already loaded.
     // MUST re-pass --mcp-config and --strict-mcp-config on resume too,
@@ -263,6 +285,10 @@ function runClaude({ message, attachments, conversation, requestId, model, desig
     if (sessionMode === "code" || sessionMode === "dual") {
       args.push("--mcp-config", MCP_CONFIG_PATH, "--strict-mcp-config");
     }
+    // Researcher mode: block ALL MCP tools on resume too
+    if (isResearcher) {
+      args.push("--mcp-config", EMPTY_MCP_CONFIG_PATH, "--strict-mcp-config");
+    }
     console.log(`[chat-runner] Resuming ${sessionMode} session: ${currentSessionId}`);
   }
 

package/figma-bridge-plugin/code.js

@@ -866,7 +866,7 @@ figma.ui.onmessage = async (msg) => {
       case "getNode": {
         const node = await figma.getNodeByIdAsync(params.nodeId);
         if (!node) throw new Error("Node not found: " + params.nodeId);
-        result = serializeNode(node);
+        result = await serializeNode(node);
         break;
       }
 
@@ -1459,7 +1459,7 @@ figma.ui.onmessage = async (msg) => {
 
 // ─── Helpers ─────────────────────────────────────────────────────────────────
 
-function serializeNode(node) {
+async function serializeNode(node) {
   const base = {
     id: node.id,
     name: node.name,
@@ -1511,9 +1511,15 @@ function serializeNode(node) {
       type: c.type,
     }));
   }
-  if ("mainComponent" in node) {
-    base.mainComponentId = node.mainComponent ? node.mainComponent.id : undefined;
-    base.mainComponentName = node.mainComponent ? node.mainComponent.name : undefined;
+  if (node.type === "INSTANCE") {
+    try {
+      const main = await node.getMainComponentAsync();
+      base.mainComponentId = main ? main.id : undefined;
+      base.mainComponentName = main ? main.name : undefined;
+    } catch (e) {
+      base.mainComponentId = undefined;
+      base.mainComponentName = undefined;
+    }
   }
 
   return base;

package/figma-bridge-plugin/references/SKILL.md

@@ -11,7 +11,7 @@ description: >
   specification in Figma. Also trigger when users mention "component docs", "spec
   pages", "design handoff docs", "anatomy markers", "API table", "property overview",
   "color annotation", "structure spec", "screen reader spec", or "a11y spec".
-  Works with Figma Console MCP and native Figma MCP.
+  Works with Figma Intelligence MCP via the bridge-relay.
 ---
 
 # Component Documentation Generator
@@ -20,7 +20,7 @@ Generate production-quality design system component documentation directly in Fi
 
 ## Overview
 
-This skill connects to your Figma file through Figma MCP (Console MCP or native Figma MCP), extracts component data programmatically, applies AI reasoning for classification and semantics, and renders structured documentation frames directly in your Figma file.
+This skill connects to your Figma file through Figma Intelligence MCP (via the bridge-relay local server), extracts component data programmatically, applies AI reasoning for classification and semantics, and renders structured documentation frames directly in your Figma file.
 
 **The pipeline for every spec type follows the same pattern:**
 1. **Extract** — Read component layers, properties, variables, and styles from Figma via MCP
@@ -31,7 +31,7 @@ This skill connects to your Figma file through Figma MCP (Console MCP or native
 
 ## Prerequisites
 
-- **Figma MCP connected** — Either Figma Console MCP (with Desktop Bridge plugin) or native Figma MCP
+- **Figma Intelligence MCP connected** — Via the bridge-relay local server
 - **A Figma component link** — The URL to a component set or standalone component
 - **Template library** (optional but recommended) — A published Figma library with documentation templates
 

package/figma-bridge-plugin/shared-prompt-config.js

@@ -254,6 +254,46 @@ function buildChatPrompt() {
   return CHAT_SYSTEM_PROMPT;
 }
 
+// ── UX Researcher Mode Prompt ────────────────────────────────────────────────
+
+const UX_RESEARCHER_PROMPT = `You are a senior UX researcher with 15 years of practice embedded in a Figma design tool. You speak designers' language — affordance, hierarchy, contrast, density, gestalt, scanability, cognitive load, jobs-to-be-done — and you are direct and concise. No fluff, no preamble, no "great question."
+
+You must NEVER use any tools, execute any code, or call any MCP functions. You analyze and critique designs based on the context provided to you — you do not modify anything. When the user asks you to actually build, create, or modify something in Figma, tell them to switch to Code mode for that.
+
+When the user shares a Figma selection (indicated by a === CURRENT FIGMA SELECTION === block in the message), critique it against UX principles concretely: name the heuristic, point at the specific element by its layer or component name, and propose a fix. Push back when the design contradicts a principle. If the user asks "what's wrong" or "check this" and a selection is attached, always analyze it — this is your primary job.
+
+Structure every answer as: **diagnosis → principle → evidence → fix.** Default to the top 3 highest-impact issues unless the user asks for an exhaustive review.
+
+Prioritize these qualities (in order): clarity, hierarchy, cognitive load, error prevention, accessibility, trust, conversion.
+
+You ground every claim in the established UX canon. When you cite, name the source by title and author the way a designer would in conversation: "Krug calls this 'self-evident' design in Don't Make Me Think," "Nielsen's heuristic #5 (error prevention)," "NN/g on form usability," "Refactoring UI talks about hierarchy through size and color," "Material Design's elevation system," "Apple HIG on touch targets," "WCAG 2.1 AA contrast," "the WAI-ARIA Authoring Practices Guide."
+
+Trusted sources you should reach for first:
+- Nielsen Norman Group (nngroup.com)
+- UX Matters
+- Smashing Magazine
+- Don't Make Me Think (Krug)
+- The Design of Everyday Things (Norman)
+- Refactoring UI (Wathan & Schoger)
+- About Face (Cooper)
+- 100 Things Every Designer Needs to Know About People (Weinschenk)
+- Material Design
+- Apple Human Interface Guidelines
+- WCAG
+- ARIA Authoring Practices Guide (APG)
+
+**Citation rule:** Cite source families and named principles naturally. Never fabricate specific article URLs or titles you are not certain about. If your memory of a specific source is fuzzy, cite the author or principle family instead.
+
+When the user's intent is ambiguous, ask one clarifying question instead of guessing.
+
+When knowledge sources or web references are provided in the context, incorporate them into your analysis. Cite the source name when referencing specific material.
+
+Format: short paragraphs. Use bullets when listing more than two issues. **Bold** the principle name. Never invent page numbers or section references you are unsure of.`;
+
+function buildUxResearcherPrompt() {
+  return UX_RESEARCHER_PROMPT;
+}
+
 // ── Active Skill Detection ───────────────────────────────────────────────────
 
 function detectActiveSkills(text) {
@@ -594,6 +634,7 @@ module.exports = {
   DESIGN_SYSTEMS,
   buildSystemPrompt,
   buildChatPrompt,
+  buildUxResearcherPrompt,
   buildDualOutputPrompt,
   buildSkillAddendum,
   buildDesignSystemAddendum,

package/figma-bridge-plugin/ui.html

@@ -581,6 +581,34 @@
     }
     .model-badge:hover { background: rgba(255,255,255,0.07); color: var(--text-secondary); }
 
+    /* UX Researcher toggle */
+    .ux-researcher-toggle {
+      display: flex; align-items: center; gap: 4px;
+      font-size: 10px;
+      color: var(--text-muted);
+      padding: 2px 6px;
+      border-radius: 5px;
+      cursor: pointer;
+      user-select: none;
+      transition: background 0.13s, color 0.13s;
+    }
+    .ux-researcher-toggle:hover { background: rgba(255,255,255,0.07); color: var(--text-secondary); }
+    .ux-researcher-toggle.active {
+      background: rgba(168, 130, 255, 0.15);
+      color: #c4a1ff;
+    }
+    .ux-researcher-toggle.active:hover {
+      background: rgba(168, 130, 255, 0.22);
+    }
+    .ux-researcher-dot {
+      width: 6px; height: 6px; border-radius: 50%;
+      background: var(--text-muted);
+      transition: background 0.13s;
+    }
+    .ux-researcher-toggle.active .ux-researcher-dot {
+      background: #c4a1ff;
+    }
+
     /* Model dropdown */
     .model-dropdown {
       position: absolute;
@@ -1878,6 +1906,10 @@
           <input type="file" id="file-input" multiple style="display:none" accept="image/*,.pdf,.txt,.json,.csv,.svg,.md,.html,.css,.js,.ts,.jsx,.tsx,.py,.go,.rs,.java,.rb,.yml,.yaml,.xml,.sql,.sh">
         </div>
         <div class="toolbar-right">
+          <div class="ux-researcher-toggle" id="ux-researcher-toggle" onclick="toggleUxResearcher()" title="UX Researcher — fast Haiku-powered UX critique. Auto-attaches your current Figma selection." style="display:none">
+            <span class="ux-researcher-dot"></span>
+            <span>UXR</span>
+          </div>
           <div class="model-badge" id="model-badge" onclick="toggleModelDropdown(event)">
             <span id="model-label">Sonnet</span>
             <svg width="10" height="10" viewBox="0 0 10 10" fill="none">
@@ -3030,6 +3062,7 @@
     }
     renderThreadForProvider(selectedLoginProvider);
     updateStatus();
+    syncResearcherToggle();
 
     if (ws && ws.readyState === WebSocket.OPEN) sendProviderToRelay();
   }
@@ -3174,8 +3207,49 @@
 
     // Show VS Code connection indicator for dual mode
     updateVscodeStatus();
+
+    // Sync researcher toggle visibility on mode change
+    syncResearcherToggle();
   };
 
+  /* ── UX Researcher Mode ──────────────────────────────────────────────── */
+  var isUxResearcherMode = false;
+  var UX_RESEARCHER_KEY = "figma-intelligence:researcher-mode";
+  try {
+    if (localStorage.getItem(UX_RESEARCHER_KEY) === "1") isUxResearcherMode = true;
+  } catch(e) {}
+
+  window.toggleUxResearcher = function() {
+    isUxResearcherMode = !isUxResearcherMode;
+    try { localStorage.setItem(UX_RESEARCHER_KEY, isUxResearcherMode ? "1" : "0"); } catch(e) {}
+    syncResearcherToggle();
+  };
+
+  function syncResearcherToggle() {
+    var el = document.getElementById("ux-researcher-toggle");
+    if (!el) return;
+
+    // Only show when provider is Claude and mode is Chat
+    var show = (getActiveProvider() === "claude") && (activeMode === "chat");
+    el.style.display = show ? "" : "none";
+
+    if (show) {
+      el.className = "ux-researcher-toggle" + (isUxResearcherMode ? " active" : "");
+    }
+
+    // Update input placeholder
+    if (input) {
+      if (show && isUxResearcherMode) {
+        input.placeholder = "Ask the UX researcher\u2026";
+      } else if (activeMode === "chat") {
+        input.placeholder = "Ask me anything...";
+      }
+    }
+  }
+
+  // Initial sync on load
+  setTimeout(syncResearcherToggle, 0);
+
   function isChatOnlyProvider() {
     return selectedLoginProvider === "bridge" || selectedLoginProvider === "perplexity";
   }
@@ -4027,7 +4101,7 @@
     if (/^\s*\/knowledge\b/i.test(messageText)) {
       var kQuery = messageText.replace(/^\s*\/knowledge\s*/i, "").trim();
       // Send to relay for hub processing (not as a chat message to AI)
-      ws.send(JSON.stringify({ type: "chat", id: currentRequestId, message: messageText, mode: activeMode, model: getSelectedModel(activeProvider), conversation: [] }));
+      ws.send(JSON.stringify({ type: "chat", id: currentRequestId, message: messageText, mode: activeMode, model: getSelectedModel(activeProvider), conversation: [], researcherMode: isUxResearcherMode }));
       // Reset input color
       input.style.color = "";
       return;
@@ -4040,6 +4114,7 @@
       model: getSelectedModel(activeProvider),
       conversation: conversation,
       mode: activeMode,
+      researcherMode: isUxResearcherMode,
     };
 
     if (attachedFiles.length > 0) {

package/figma-intelligence-layer/src/index.ts

@@ -2088,7 +2088,7 @@ async function dispatch(name: string, args: AnyArgs): Promise<unknown> {
     case "figma_get_node_deep": {
       const bridge = await getBridge();
       const a = args as { nodeId: string; maxDepth?: number };
-      return bridge.getNodeDeep(a.nodeId, a.maxDepth);
+      return await bridge.getNodeDeep(a.nodeId, a.maxDepth);
     }
     case "figma_batch_get_nodes": {
       const bridge = await getBridge();

package/figma-intelligence-layer/src/shared/figma-bridge.ts

@@ -633,9 +633,14 @@ export class FigmaBridge {
       const page = figma.currentPage;
       const found = page.findAll(n => n.type === 'INSTANCE');
       for (const inst of found) {
+        let mainComponentId = '';
+        try {
+          const main = await inst.getMainComponentAsync();
+          if (main) mainComponentId = main.id;
+        } catch (e) {}
         instances.push({
           id: inst.id,
-          mainComponentId: inst.mainComponent ? inst.mainComponent.id : '',
+          mainComponentId,
           name: inst.name,
           pageId: page.id,
         });
@@ -1073,7 +1078,7 @@ export class FigmaBridge {
 (async () => {
   const maxDepth = ${Math.min(maxDepth, 20)};
 
-  function serializeNode(node, depth) {
+  async function serializeNode(node, depth) {
     const data = {
       id: node.id,
       name: node.name,
@@ -1125,9 +1130,14 @@ export class FigmaBridge {
     // Component metadata
     if ('componentPropertyReferences' in node) data.componentPropertyReferences = node.componentPropertyReferences;
     if ('variantProperties' in node && node.variantProperties) data.variantProperties = node.variantProperties;
-    if (node.type === 'INSTANCE' && node.mainComponent) {
-      data.mainComponentId = node.mainComponent.id;
-      data.mainComponentName = node.mainComponent.name;
+    if (node.type === 'INSTANCE') {
+      try {
+        const main = await node.getMainComponentAsync();
+        if (main) {
+          data.mainComponentId = main.id;
+          data.mainComponentName = main.name;
+        }
+      } catch (e) { /* mainComponent unavailable */ }
     }
     if (node.description) data.description = node.description;
 
@@ -1150,7 +1160,7 @@ export class FigmaBridge {
     if ('children' in node && node.children && depth < maxDepth) {
       data.children = [];
       for (const child of node.children) {
-        data.children.push(serializeNode(child, depth + 1));
+        data.children.push(await serializeNode(child, depth + 1));
       }
       data.childCount = node.children.length;
     } else if ('children' in node && node.children) {
@@ -1164,7 +1174,7 @@ export class FigmaBridge {
 
   const root = await figma.getNodeByIdAsync(${JSON.stringify(nodeId)});
   if (!root) throw new Error('Node not found: ' + ${JSON.stringify(nodeId)});
-  return serializeNode(root, 0);
+  return await serializeNode(root, 0);
 })();
     `, 60000); // 60s timeout for deep trees
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sarjallab09/figma-intelligence",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "88 AI-powered design tools for Figma. Works with your Claude, OpenAI Codex, or Gemini CLI subscription. One command to set up.",
   "author": "Figma Intelligence Contributors",
   "license": "CC-BY-NC-ND-4.0",