figma-rust-mcp 3.0.4 → 3.0.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "figma-rust-mcp",
-  "version": "3.0.4",
+  "version": "3.0.5",
   "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-mcp",
   "type": "module",

package/plugin/code.js

@@ -1,7 +1,7 @@
 // figma-mcp — Figma Plugin main thread v1.2.1
 // Handles both WRITE (draw UI) and READ (extract design) operations.
 // AUTO-GENERATED by scripts/build-plugin.js — edit plugin-src/*.js instead
-// Generated: 2026-08-29T14:34:20.483Z
+// Generated: 2026-08-30T10:25:26.211Z
 
 // ── plugin-src/utils.js ──
 // ─── UTILS ────────────────────────────────────────────────────────────────────
@@ -347,53 +347,129 @@ function cacheNode(node) {
   return node;
 }
 
+function normalizeNodeId(id) {
+  if (!id || typeof id !== "string") return id;
+  var clean = id.trim().replace(/^['"]|['"]$/g, "");
+  try { clean = decodeURIComponent(clean); } catch(e) {}
+  // Convert URL hyphenated IDs (e.g. 2715-40862) to colon notation (2715:40862)
+  clean = clean.replace(/(\d+)-(\d+)/g, "$1:$2");
+  return clean;
+}
+
+var allPagesLoaded = false;
+async function ensureAllPagesLoaded() {
+  if (allPagesLoaded) return;
+  if (typeof figma.loadAllPagesAsync === "function") {
+    try {
+      await figma.loadAllPagesAsync();
+      allPagesLoaded = true;
+    } catch(e) {}
+  }
+}
+
+function getNodeNotFoundContext(id, name) {
+  var currentPageName = figma.currentPage ? figma.currentPage.name : "unknown";
+  var availablePages = figma.root && figma.root.children ? figma.root.children.map(function(p) { return p.name; }).join(", ") : "none";
+  var selInfo = figma.currentPage && figma.currentPage.selection && figma.currentPage.selection.length > 0
+    ? figma.currentPage.selection.map(function(s) { return s.id + " (" + s.name + ")"; }).join(", ")
+    : "none";
+  var target = id || name || "no id/name given";
+  return "Node not found: " + target + ". [Active Page: \"" + currentPageName + "\", Available Pages: [" + availablePages + "], Current Selection: [" + selInfo + "]]. Use figma_read get_page_nodes to list nodes or set_page to switch pages.";
+}
+
 function findNodeById(id) {
   if (!id) return null;
-  if (figma.currentPage.id === id) return figma.currentPage;
-  if (figma.root.id === id) return figma.root;
-  if (nodeCache.has(id)) {
-    var cached = nodeCache.get(id);
+  var cleanId = normalizeNodeId(id);
+  if (figma.currentPage.id === cleanId || figma.currentPage.id === id) return figma.currentPage;
+  if (figma.root.id === cleanId || figma.root.id === id) return figma.root;
+  if (nodeCache.has(cleanId)) {
+    var cached = nodeCache.get(cleanId);
     if (!cached.removed) return cached;
+    nodeCache.delete(cleanId);
+  }
+  if (nodeCache.has(id)) {
+    var cached2 = nodeCache.get(id);
+    if (!cached2.removed) return cached2;
     nodeCache.delete(id);
   }
   try {
     if (typeof figma.getNodeById === "function") {
-      var node = figma.getNodeById(id);
+      var node = figma.getNodeById(cleanId) || (cleanId !== id ? figma.getNodeById(id) : null);
       if (node && !node.removed) return cacheNode(node);
     }
   } catch(e) {}
   // Check selection
   for (var i = 0; i < figma.currentPage.selection.length; i++) {
-    if (figma.currentPage.selection[i].id === id) return cacheNode(figma.currentPage.selection[i]);
+    var sel = figma.currentPage.selection[i];
+    if (sel.id === cleanId || sel.id === id) return cacheNode(sel);
   }
   return null;
 }
 
 async function findNodeByIdAsync(id) {
   if (!id) return null;
-  if (figma.currentPage.id === id) return figma.currentPage;
-  if (figma.root.id === id) return figma.root;
-  if (nodeCache.has(id)) {
-    var cached = nodeCache.get(id);
+  var cleanId = normalizeNodeId(id);
+  if (figma.currentPage.id === cleanId || figma.currentPage.id === id) return figma.currentPage;
+  if (figma.root.id === cleanId || figma.root.id === id) return figma.root;
+  if (nodeCache.has(cleanId)) {
+    var cached = nodeCache.get(cleanId);
     if (!cached.removed) return cached;
+    nodeCache.delete(cleanId);
+  }
+  if (nodeCache.has(id)) {
+    var cached2 = nodeCache.get(id);
+    if (!cached2.removed) return cached2;
     nodeCache.delete(id);
   }
-  // Try synchronous lookup first (0ms)
+
+  // 1. Try synchronous lookup first (0ms)
   try {
     if (typeof figma.getNodeById === "function") {
-      var syncNode = figma.getNodeById(id);
+      var syncNode = figma.getNodeById(cleanId) || (cleanId !== id ? figma.getNodeById(id) : null);
       if (syncNode && !syncNode.removed) return cacheNode(syncNode);
     }
   } catch(e) {}
-  // Fallback to async
+
+  // 2. Try async lookup
   try {
-    var node = await figma.getNodeByIdAsync(id);
+    var node = await figma.getNodeByIdAsync(cleanId);
+    if (!node && cleanId !== id) node = await figma.getNodeByIdAsync(id);
     if (node && !node.removed) return cacheNode(node);
   } catch(e) {}
+
+  // 3. Check selection
+  for (var i = 0; i < figma.currentPage.selection.length; i++) {
+    var s = figma.currentPage.selection[i];
+    if (s.id === cleanId || s.id === id) return cacheNode(s);
+  }
+
+  // 4. Fallback: If not found and pages are lazily loaded, load all pages and retry
+  if (!allPagesLoaded && typeof figma.loadAllPagesAsync === "function") {
+    await ensureAllPagesLoaded();
+    try {
+      var retryNode = await figma.getNodeByIdAsync(cleanId);
+      if (!retryNode && cleanId !== id) retryNode = await figma.getNodeByIdAsync(id);
+      if (retryNode && !retryNode.removed) return cacheNode(retryNode);
+    } catch(e) {}
+  }
+
+  // 5. Fallback for instance sub-layer IDs (e.g. "I2715:40862;123:456")
+  if (cleanId.indexOf(";") !== -1) {
+    var parts = cleanId.split(";");
+    for (var p = 0; p < parts.length; p++) {
+      var partId = parts[p].replace(/^I/, "");
+      try {
+        var subNode = await figma.getNodeByIdAsync(partId);
+        if (subNode && !subNode.removed) return cacheNode(subNode);
+      } catch(e) {}
+    }
+  }
+
   return null;
 }
 
 function findNodeByName(name) {
+  if (!name) return null;
   if (figma.currentPage.name === name) return figma.currentPage;
   // Search in selection first, then shallow children, then findOne as fallback
   for (var i = 0; i < figma.currentPage.selection.length; i++) {
@@ -402,20 +478,34 @@ function findNodeByName(name) {
   for (var j = 0; j < figma.currentPage.children.length; j++) {
     if (figma.currentPage.children[j].name === name) return cacheNode(figma.currentPage.children[j]);
   }
-  var found = figma.currentPage.findOne(n => n.name === name);
-  if (found) cacheNode(found);
-  return found;
+  var found = figma.currentPage.findOne(function(n) { return n.name === name; });
+  if (found) return cacheNode(found);
+
+  // Cross-page fallback
+  if (figma.root && figma.root.children) {
+    for (var p = 0; p < figma.root.children.length; p++) {
+      var page = figma.root.children[p];
+      if (page === figma.currentPage) continue;
+      if (page.name === name) return page;
+      var pageFound = page.findOne ? page.findOne(function(n) { return n.name === name; }) : null;
+      if (pageFound) return cacheNode(pageFound);
+    }
+  }
+
+  return null;
 }
 
 async function resolveNode(params) {
-  var id   = params.id || params.nodeId || params.targetId;
-  var name = params.name || params.nodeName;
+  if (!params) return null;
+  var id   = params.id || params.nodeId || params.node_id || params.targetId || params.target_id;
+  var name = params.name || params.nodeName || params.node_name;
   var node = null;
   if (id)   node = await findNodeByIdAsync(id);
   if (!node && name) node = findNodeByName(name);
   return node;
 }
 
+
 function nodeToInfo(node) {
   if (!node) return null;
   const info = {
@@ -438,6 +528,71 @@ function yieldToUI(delayMs) {
   });
 }
 
+// Flexible operation handler resolver with camelCase/snake_case and alias support
+function resolveOperationHandler(operation) {
+  if (!operation || typeof operation !== "string") return null;
+  if (typeof handlers !== "object" || !handlers) return null;
+  if (handlers[operation]) return handlers[operation];
+
+  // 1. Convert snake_case -> camelCase (e.g. create_variable -> createVariable, list_pages -> listPages)
+  var camel = operation.replace(/_([a-z0-9])/gi, function(_, c) { return c.toUpperCase(); });
+  if (handlers[camel]) return handlers[camel];
+
+  // 2. Convert camelCase -> snake_case (e.g. getPageNodes -> get_page_nodes, getNodeDetail -> get_node_detail)
+  var snake = operation.replace(/([a-z0-9])([A-Z])/g, "$1_$2").toLowerCase();
+  if (handlers[snake]) return handlers[snake];
+
+  // 3. Common semantic synonyms & aliases
+  var normalized = operation.toLowerCase().replace(/[-_\s]+/g, "");
+  var aliasMap = {
+    "getnode": handlers.get_node_detail,
+    "getnodedetail": handlers.get_node_detail,
+    "getnodeinfo": handlers.get_node_detail,
+    "nodedetail": handlers.get_node_detail,
+    "nodeinfo": handlers.get_node_detail,
+    "inspectnode": handlers.get_design_context,
+    "inspect": handlers.get_design_context,
+    "getdesigncontext": handlers.get_design_context,
+    "designcontext": handlers.get_design_context,
+    "getdesign": handlers.get_design,
+    "getselection": handlers.get_selection,
+    "selection": handlers.get_selection,
+    "getpagenodes": handlers.get_page_nodes,
+    "pagenodes": handlers.get_page_nodes,
+    "getstyles": handlers.get_styles,
+    "styles": handlers.get_styles,
+    "getvariables": handlers.get_variables,
+    "gettokens": handlers.get_variables,
+    "tokens": handlers.get_variables,
+    "variables": handlers.get_variables,
+    "getvariabletokens": handlers.get_variables,
+    "getlocalcomponents": handlers.get_local_components,
+    "localcomponents": handlers.get_local_components,
+    "listcomponents": handlers.listComponents,
+    "components": handlers.get_local_components,
+    "getcomponentmap": handlers.get_component_map,
+    "getunmappedcomponents": handlers.get_unmapped_components,
+    "scandesign": handlers.scan_design,
+    "searchnodes": handlers.search_nodes,
+    "getviewport": handlers.get_viewport,
+    "setviewport": handlers.set_viewport,
+    "exportsvg": handlers.export_svg,
+    "exportimage": handlers.export_image,
+    "exportassets": handlers.export_assets,
+    "listpages": handlers.listPages,
+    "setpage": handlers.setPage,
+    "createpage": handlers.createPage,
+    "loadallpages": handlers.loadAllPagesAsync,
+    "loadallpagesasync": handlers.loadAllPagesAsync,
+    "update": handlers.modify,
+    "remove": handlers["delete"]
+  };
+
+  if (aliasMap[normalized]) return aliasMap[normalized];
+
+  return null;
+}
+
 
 // ── plugin-src/svg-path-helpers.js ──
 // ─── SVG PATH NORMALIZATION ───────────────────────────────────────────────────
@@ -868,6 +1023,150 @@ function resolveTextStyle(node, opts) {
   return out;
 }
 
+// ── Design Token / Variable Resolver Map ──
+var cachedVariableResolverMap = null;
+var cachedVariableResolverMapTime = 0;
+
+async function buildVariableResolverMapAsync(forceRefresh) {
+  var now = Date.now();
+  if (!forceRefresh && cachedVariableResolverMap && (now - cachedVariableResolverMapTime < 15000)) {
+    return cachedVariableResolverMap;
+  }
+  var map = { byId: {}, byName: {} };
+  try {
+    if (typeof figma.variables !== "undefined" && typeof figma.variables.getLocalVariablesAsync === "function") {
+      var vars = await figma.variables.getLocalVariablesAsync();
+      var rawMap = {};
+      for (var i = 0; i < vars.length; i++) {
+        var v = vars[i];
+        if (v && v.id) rawMap[v.id] = v;
+      }
+
+      function resolveVarValue(v, depth) {
+        if (!v || depth > 6) return null;
+        var defaultVal = null;
+        if (v.valuesByMode) {
+          var modeKeys = Object.keys(v.valuesByMode);
+          if (modeKeys.length > 0) defaultVal = v.valuesByMode[modeKeys[0]];
+        }
+        if (defaultVal && typeof defaultVal === "object" && defaultVal.type === "VARIABLE_ALIAS" && defaultVal.id) {
+          var targetVar = rawMap[defaultVal.id];
+          if (targetVar) {
+            var targetRes = resolveVarValue(targetVar, depth + 1);
+            return {
+              isAlias: true,
+              targetId: targetVar.id,
+              targetName: targetVar.name,
+              primitiveName: (targetRes && targetRes.primitiveName) ? targetRes.primitiveName : targetVar.name,
+              resolvedValue: targetRes ? targetRes.resolvedValue : null,
+            };
+          }
+        }
+        if (defaultVal && typeof defaultVal === "object" && "r" in defaultVal && "g" in defaultVal && "b" in defaultVal) {
+          return { isAlias: false, resolvedValue: rgbToHex(defaultVal), primitiveName: v.name };
+        }
+        if (typeof defaultVal === "number" || typeof defaultVal === "string" || typeof defaultVal === "boolean") {
+          return { isAlias: false, resolvedValue: defaultVal, primitiveName: v.name };
+        }
+        return { isAlias: false, resolvedValue: defaultVal, primitiveName: v.name };
+      }
+
+      for (var j = 0; j < vars.length; j++) {
+        var vr = vars[j];
+        if (!vr || !vr.id) continue;
+        var res = resolveVarValue(vr, 0);
+        var item = {
+          id: vr.id,
+          name: vr.name,
+          resolvedType: vr.resolvedType,
+          isAlias: res ? res.isAlias : false,
+          targetName: res ? res.targetName : null,
+          primitiveName: res ? res.primitiveName : vr.name,
+          resolvedValue: res ? res.resolvedValue : null,
+        };
+        map.byId[vr.id] = item;
+        map.byName[vr.name] = item;
+      }
+    }
+  } catch(e) {}
+  cachedVariableResolverMap = map;
+  cachedVariableResolverMapTime = now;
+  return map;
+}
+
+// ── Clean Variant & Component Properties Parser ──
+function cleanComponentProperties(node) {
+  var out = { variant: null, props: null };
+  if (!node) return out;
+
+  // 1. Native variantProperties on instance
+  if (node.variantProperties && typeof node.variantProperties === "object") {
+    var varKeys = Object.keys(node.variantProperties);
+    if (varKeys.length > 0) {
+      out.variant = {};
+      for (var vk = 0; vk < varKeys.length; vk++) {
+        out.variant[varKeys[vk]] = node.variantProperties[varKeys[vk]];
+      }
+    }
+  }
+
+  // 2. Component Properties parsing (strip #ID suffix and separate variants vs normal props)
+  if (node.componentProperties && typeof node.componentProperties === "object") {
+    var rawProps = node.componentProperties;
+    var propKeys = Object.keys(rawProps);
+    if (propKeys.length > 0) {
+      var cleanProps = {};
+      var inferredVariants = out.variant || {};
+      for (var pk = 0; pk < propKeys.length; pk++) {
+        var rawKey = propKeys[pk];
+        var propObj = rawProps[rawKey];
+        if (!propObj) continue;
+        var cleanKey = rawKey.split("#")[0].trim();
+        if (propObj.type === "VARIANT") {
+          inferredVariants[cleanKey] = propObj.value;
+        } else {
+          cleanProps[cleanKey] = propObj.value;
+        }
+      }
+      if (Object.keys(cleanProps).length > 0) out.props = cleanProps;
+      if (Object.keys(inferredVariants).length > 0) out.variant = inferredVariants;
+    }
+  }
+  return out;
+}
+
+// ── Infer Semantic Role ──
+function inferSemanticRole(node, info) {
+  if (!node) return null;
+  var name = (node.name || "").toLowerCase();
+  var type = node.type;
+
+  if (isLikelyIcon(node) || name.indexOf("icon") !== -1) return "icon";
+  if (name.indexOf("button") !== -1 || name.indexOf("btn") !== -1) return "button";
+  if (name.indexOf("input") !== -1 || name.indexOf("textfield") !== -1 || name.indexOf("search") !== -1) return "input";
+  if (name.indexOf("badge") !== -1 || name.indexOf("tag") !== -1 || name.indexOf("chip") !== -1 || name.indexOf("pill") !== -1) return "badge";
+  if (name.indexOf("avatar") !== -1 || name.indexOf("userpic") !== -1 || name.indexOf("profile-pic") !== -1) return "avatar";
+  if (name.indexOf("card") !== -1) return "card";
+  if (name.indexOf("modal") !== -1 || name.indexOf("dialog") !== -1 || name.indexOf("popup") !== -1) return "modal";
+  if (name.indexOf("checkbox") !== -1) return "checkbox";
+  if (name.indexOf("switch") !== -1 || name.indexOf("toggle") !== -1) return "switch";
+  if (name.indexOf("divider") !== -1 || name.indexOf("separator") !== -1) return "divider";
+  if (name.indexOf("header") !== -1 || name.indexOf("navbar") !== -1 || name.indexOf("appbar") !== -1) return "header";
+  if (name.indexOf("tab") !== -1) return "tab";
+
+  if (type === "INSTANCE") {
+    if (info && info.componentSetName) {
+      var setName = info.componentSetName.toLowerCase();
+      if (setName.indexOf("button") !== -1) return "button";
+      if (setName.indexOf("input") !== -1) return "input";
+      if (setName.indexOf("badge") !== -1) return "badge";
+      if (setName.indexOf("avatar") !== -1) return "avatar";
+      if (setName.indexOf("icon") !== -1) return "icon";
+    }
+  }
+  return null;
+}
+
 // Instance → main component resolution.
 //
 // `instance.mainComponent` throws under documentAccess: dynamic-page, so the
@@ -908,10 +1207,18 @@ async function resolveInstanceComponents(entries, apply) {
     }));
     for (var b = 0; b < batch.length; b++) {
       var main = mains[b];
-      if (!main) continue;
-      var desc = describeMainComponent(main);
-      if (apply) apply(batch[b].info, desc);
-      else Object.assign(batch[b].info, desc);
+      var entryNode = batch[b].node;
+      var entryInfo = batch[b].info;
+      if (main) {
+        var desc = describeMainComponent(main);
+        if (apply) apply(entryInfo, desc);
+        else Object.assign(entryInfo, desc);
+      }
+      var parsed = cleanComponentProperties(entryNode);
+      if (parsed.variant) entryInfo.variant = parsed.variant;
+      if (parsed.props) entryInfo.props = parsed.props;
+      var role = inferSemanticRole(entryNode, entryInfo);
+      if (role) entryInfo.role = role;
       resolved++;
     }
   }
@@ -1132,19 +1439,41 @@ function extractDesignTree(node, depth, maxDepth, detailLevel, filterInvisible,
   try { if ("blendMode" in node && node.blendMode !== "NORMAL" && node.blendMode !== "PASS_THROUGH") info.blendMode = node.blendMode; } catch(e) {}
   try { if ("clipsContent" in node && node.clipsContent) info.clipsContent = true; } catch(e) {}
 
-  // ── Bound Variables (Design Tokens) — full only ──
-  if (isFull) try {
+  // ── Bound Variables (Design Tokens) — full & compact ──
+  if (isFull || isCompact) try {
     if (node.boundVariables) {
       var bv = {};
       var bvKeys = Object.keys(node.boundVariables);
+      var varMap = (walkState && walkState.variableMap) ? walkState.variableMap.byId : null;
       for (var bvi = 0; bvi < bvKeys.length; bvi++) {
         var bvk = bvKeys[bvi];
         var binding = node.boundVariables[bvk];
         if (binding) {
-          if (Array.isArray(binding)) {
-            bv[bvk] = binding.map(function(b) { return b ? b.id : null; });
-          } else {
-            bv[bvk] = binding.id || null;
+          var bindings = Array.isArray(binding) ? binding : [binding];
+          var resolvedList = [];
+          for (var bi = 0; bi < bindings.length; bi++) {
+            var bObj = bindings[bi];
+            if (!bObj || !bObj.id) continue;
+            var vInfo = varMap && varMap[bObj.id] ? varMap[bObj.id] : null;
+            if (vInfo) {
+              var entry = { id: bObj.id, name: vInfo.name, type: vInfo.resolvedType };
+              if (vInfo.resolvedValue !== null && vInfo.resolvedValue !== undefined) entry.value = vInfo.resolvedValue;
+              if (vInfo.isAlias && vInfo.targetName) entry.aliasTarget = vInfo.targetName;
+              resolvedList.push(entry);
+            } else {
+              resolvedList.push({ id: bObj.id });
+            }
+          }
+          if (resolvedList.length > 0) {
+            bv[bvk] = Array.isArray(binding) ? resolvedList : resolvedList[0];
+            var primaryEntry = resolvedList[0];
+            if (primaryEntry && primaryEntry.name) {
+              if (bvk === "fills" || bvk === "fill") info.fillToken = primaryEntry.name;
+              else if (bvk === "strokes" || bvk === "stroke") info.strokeToken = primaryEntry.name;
+              else if (bvk === "itemSpacing") info.gapToken = primaryEntry.name;
+              else if (bvk === "paddingTop" || bvk === "paddingBottom" || bvk === "paddingLeft" || bvk === "paddingRight") info.paddingToken = primaryEntry.name;
+              else if (bvk === "topLeftRadius" || bvk === "cornerRadius") info.radiusToken = primaryEntry.name;
+            }
           }
         }
       }
@@ -1210,6 +1539,8 @@ function extractDesignTree(node, depth, maxDepth, detailLevel, filterInvisible,
         mode: node.layoutMode,
       };
       if (node.itemSpacing !== undefined && node.itemSpacing !== 0) layoutObj.itemSpacing = node.itemSpacing;
+      if (info.gapToken) layoutObj.gapToken = info.gapToken;
+      if (info.paddingToken) layoutObj.paddingToken = info.paddingToken;
       if (node.primaryAxisAlignItems && node.primaryAxisAlignItems !== "MIN") layoutObj.align = node.primaryAxisAlignItems;
       if (node.counterAxisAlignItems && node.counterAxisAlignItems !== "MIN") layoutObj.crossAlign = node.counterAxisAlignItems;
 
@@ -1259,7 +1590,6 @@ function extractDesignTree(node, depth, maxDepth, detailLevel, filterInvisible,
   // ── Component-specific info ──
   if (node.type === "COMPONENT" || node.type === "COMPONENT_SET") {
     try { info.description = node.description; } catch(e) {}
-    // Expose component property definitions for COMPONENT/COMPONENT_SET
     try {
       if (node.componentPropertyDefinitions) {
         var defs = node.componentPropertyDefinitions;
@@ -1276,27 +1606,17 @@ function extractDesignTree(node, depth, maxDepth, detailLevel, filterInvisible,
     } catch(e) {}
   }
   if (node.type === "INSTANCE") {
-    // Issue #2: expose source component reference. mainComponent is async-only
-    // under documentAccess: dynamic-page, so defer to the caller's collector.
+    var parsedProps = cleanComponentProperties(node);
+    if (parsedProps.variant) info.variant = parsedProps.variant;
+    if (parsedProps.props) info.props = parsedProps.props;
     if (instanceCollector) instanceCollector.push({ info: info, node: node });
     try { if (node.overrides && node.overrides.length) info.overrideCount = node.overrides.length; } catch(e) {}
-    // Issue #4: expose explicit component property values on this instance
-    try {
-      if (node.componentProperties) {
-        var props = node.componentProperties;
-        var propKeys = Object.keys(props);
-        if (propKeys.length > 0) {
-          info.componentPropertyValues = {};
-          for (var pi = 0; pi < propKeys.length; pi++) {
-            var pk = propKeys[pi];
-            var pv = props[pk];
-            info.componentPropertyValues[pk] = { type: pv.type, value: pv.value };
-          }
-        }
-      }
-    } catch(e) {}
   }
 
+  // ── Semantic Role ──
+  var semanticRole = inferSemanticRole(node, info);
+  if (semanticRole) info.role = semanticRole;
+
   // ── VECTOR / BOOLEAN_OPERATION ──
   if (node.type === "VECTOR" || node.type === "BOOLEAN_OPERATION") {
     try { if (node.vectorPaths) info.pathCount = node.vectorPaths.length; } catch(e) {}
@@ -2342,6 +2662,21 @@ handlers.swapComponent = async function(params) {
   };
 };
 
+// ─── ALIASES FOR WRITE HANDLERS ──────────────────────────────────────────────
+handlers.list_pages = handlers.listPages;
+handlers.set_page = handlers.setPage;
+handlers.create_page = handlers.createPage;
+handlers.list_components = handlers.listComponents;
+handlers.load_all_pages_async = handlers.loadAllPagesAsync;
+handlers.loadAllPages = handlers.loadAllPagesAsync;
+handlers.load_all_pages = handlers.loadAllPagesAsync;
+handlers.set_component_properties = handlers.setComponentProperties;
+handlers.get_component_properties = handlers.getComponentProperties;
+handlers.swap_component = handlers.swapComponent;
+handlers.update = handlers.modify;
+handlers.remove = handlers["delete"];
+
+
 
 // ── plugin-src/handlers-library.js ──
 // ─── DESIGN LIBRARY HANDLERS ──────────────────────────────────────────────────
@@ -2472,6 +2807,11 @@ handlers.get_library_tokens = async function() {
   return { libraryId: lib.id, colors: colors, textStyles: textStyles };
 };
 
+// ─── ALIASES FOR LIBRARY HANDLERS ─────────────────────────────────────────────
+handlers.ensureLibrary = handlers.ensure_library;
+handlers.getLibraryTokens = handlers.get_library_tokens;
+
+
 
 // ── plugin-src/handlers-read.js ──
 // ─── READ HANDLERS ────────────────────────────────────────────────────────────
@@ -2482,10 +2822,16 @@ handlers.get_library_tokens = async function() {
 // `absolute: true` forces absoluteBoundingBox on every node.
 var DEFAULT_NODE_BUDGET = 3000;
 
-function makeWalkState(params) {
+async function makeWalkStateAsync(params) {
   var p = params || {};
   var budget = (p.maxNodes !== undefined && Number(p.maxNodes) > 0) ? Number(p.maxNodes) : DEFAULT_NODE_BUDGET;
-  return { remaining: budget, budget: budget, truncated: false, absolute: p.absolute === true };
+  var varMap = null;
+  try {
+    if (typeof buildVariableResolverMapAsync === "function") {
+      varMap = await buildVariableResolverMapAsync();
+    }
+  } catch(e) {}
+  return { remaining: budget, budget: budget, truncated: false, absolute: p.absolute === true, variableMap: varMap };
 }
 
 function walkStateMeta(walkState) {
@@ -2518,7 +2864,7 @@ handlers.get_selection = async function(params) {
   var filterInvisible = !(params && params.includeHidden === true);
   var tokenCollector = (detailLevel !== "minimal") ? { colors: new Set(), fonts: new Set(), sizes: new Set() } : null;
   var instanceCollector = (detailLevel !== "minimal") ? [] : null;
-  var walkState = makeWalkState(params);
+  var walkState = await makeWalkStateAsync(params);
   var trees = nodes.map(function(n) { return extractDesignTree(n, 0, maxDepth, detailLevel, filterInvisible, tokenCollector, instanceCollector, walkState); });
   // mainComponent is async-only under documentAccess: dynamic-page — resolve
   // every collected INSTANCE after the (synchronous) tree walk.
@@ -2559,7 +2905,7 @@ handlers.get_design = async function(params) {
   try {
     var tokenCollector = (detailLevel !== "minimal") ? { colors: new Set(), fonts: new Set(), sizes: new Set() } : null;
     var instanceCollector = (detailLevel !== "minimal") ? [] : null;
-    var walkState = makeWalkState(p);
+    var walkState = await makeWalkStateAsync(p);
     var tree = extractDesignTree(root, 0, maxDepth, detailLevel, filterInvisible, tokenCollector, instanceCollector, walkState);
     var instanceInfo = await resolveInstanceComponents(instanceCollector);
 
@@ -3306,19 +3652,54 @@ handlers.index_scan = async function() {
   };
 };
 
+// ─── ALIASES FOR READ HANDLERS ────────────────────────────────────────────────
+handlers.getSelection = handlers.get_selection;
+handlers.selection = handlers.get_selection;
+handlers.getDesign = handlers.get_design;
+handlers.scanDesign = handlers.scan_design;
+handlers.searchNodes = handlers.search_nodes;
+handlers.getPageNodes = handlers.get_page_nodes;
+handlers.pageNodes = handlers.get_page_nodes;
+handlers.capture = handlers.screenshot;
+handlers.takeScreenshot = handlers.screenshot;
+handlers.exportSvg = handlers.export_svg;
+handlers.exportImage = handlers.export_image;
+handlers.indexScan = handlers.index_scan;
+
+
 
 // ── plugin-src/handlers-read-detail.js ──
 // ─── READ DETAIL HANDLERS ─────────────────────────────────────────────────────
 
 // get_node_detail — CSS-like properties for a single node (no tree traversal)
 handlers.get_node_detail = async function(params) {
-  // Accept id, nodeId, name, nodeName — try ID first then name fallback
-  var id = params ? (params.id || params.nodeId) : null;
-  var nodeName = params ? (params.name || params.nodeName) : null;
+  // Batch support: if nodeIds array is provided, inspect multiple nodes in one call
+  if (params && (Array.isArray(params.nodeIds) || Array.isArray(params.ids))) {
+    var ids = params.nodeIds || params.ids;
+    var results = [];
+    for (var bi = 0; bi < ids.length; bi++) {
+      try {
+        var nd = await handlers.get_node_detail({ id: ids[bi] });
+        results.push(nd);
+      } catch (e) {
+        results.push({ id: ids[bi], error: e.message });
+      }
+    }
+    return { nodes: results, count: results.length };
+  }
+
+  // Accept id, nodeId, node_id, targetId, target_id, name, nodeName, node_name — try ID first then name fallback
+  var id = params ? (params.id || params.nodeId || params.node_id || params.targetId || params.target_id) : null;
+  var nodeName = params ? (params.name || params.nodeName || params.node_name) : null;
   var node = null;
   if (id) node = await findNodeByIdAsync(id);
   if (!node && nodeName) node = findNodeByName(nodeName);
-  if (!node) throw new Error("Node not found: " + (id || nodeName || "no id/name given") + ". Use figma_read get_page_nodes to get current node IDs.");
+  if (!node) {
+    var errMsg = typeof getNodeNotFoundContext === "function"
+      ? getNodeNotFoundContext(id, nodeName)
+      : ("Node not found: " + (id || nodeName || "no id/name given") + ". Use figma_read get_page_nodes to get current node IDs.");
+    throw new Error(errMsg);
+  }
 
   var detail = {
     id: node.id, name: node.name, type: node.type,
@@ -3550,6 +3931,25 @@ handlers.get_node_detail = async function(params) {
     }
   } catch(e) {}
 
+  // Attach direct semantic token names on detail
+  try {
+    if (detail.boundVariables) {
+      var bvKeys = Object.keys(detail.boundVariables);
+      for (var bvi = 0; bvi < bvKeys.length; bvi++) {
+        var bvk = bvKeys[bvi];
+        var bEntry = detail.boundVariables[bvk];
+        var pName = (bEntry && typeof bEntry === "object") ? (Array.isArray(bEntry) ? (bEntry[0] && bEntry[0].name) : bEntry.name) : null;
+        if (pName) {
+          if (bvk === "fills" || bvk === "fill") detail.fillToken = pName;
+          else if (bvk === "strokes" || bvk === "stroke") detail.strokeToken = pName;
+          else if (bvk === "itemSpacing") detail.gapToken = pName;
+          else if (bvk === "paddingTop" || bvk === "paddingBottom" || bvk === "paddingLeft" || bvk === "paddingRight") detail.paddingToken = pName;
+          else if (bvk === "topLeftRadius" || bvk === "cornerRadius") detail.radiusToken = pName;
+        }
+      }
+    }
+  } catch(e) {}
+
   // P4: Resolve style IDs → name + values (not just opaque IDs)
   try {
     if (node.textStyleId && typeof node.textStyleId === "string") {
@@ -3576,12 +3976,15 @@ handlers.get_node_detail = async function(params) {
   try { if (node.strokeStyleId && typeof node.strokeStyleId === "string") detail.strokeStyleId = node.strokeStyleId; } catch(e) {}
   try { if (node.effectStyleId && typeof node.effectStyleId === "string") detail.effectStyleId = node.effectStyleId; } catch(e) {}
 
-  // Instance: source component reference + property values + overrides + P5 variantLabel
+  // Instance: source component reference + property values + overrides + P5 variantLabel + clean variant & props
   if (node.type === "INSTANCE") {
-    // mainComponent is async-only under documentAccess: dynamic-page.
-    // describeMainComponent yields componentId/componentName/componentSetName/variantLabel.
     var instComp = await getMainComponentSafe(node);
     if (instComp) Object.assign(detail, describeMainComponent(instComp));
+    var parsed = typeof cleanComponentProperties === "function" ? cleanComponentProperties(node) : null;
+    if (parsed) {
+      if (parsed.variant) detail.variant = parsed.variant;
+      if (parsed.props) detail.props = parsed.props;
+    }
     // P3: Full override list instead of just count
     try {
       if (node.overrides && node.overrides.length) {
@@ -3607,6 +4010,10 @@ handlers.get_node_detail = async function(params) {
     } catch(e) {}
   }
 
+  // Semantic Role
+  var semanticRole = typeof inferSemanticRole === "function" ? inferSemanticRole(node, detail) : null;
+  if (semanticRole) detail.role = semanticRole;
+
   // Children count + text content summary
   if (node && typeof node === "object" && "children" in node && Array.isArray(node.children)) {
     detail.childCount = node.children.length;
@@ -3714,8 +4121,8 @@ handlers.get_css = async function(params) {
 // Returns: flex layout semantics, token-resolved colors, typography, component instances
 // Much more code-ready than get_design (raw tree) or get_css (single string)
 handlers.get_design_context = async function(params) {
-  var id = params ? (params.id || params.nodeId) : null;
-  var nodeName = params ? (params.name || params.nodeName) : null;
+  var id = params ? (params.id || params.nodeId || params.node_id || params.targetId || params.target_id) : null;
+  var nodeName = params ? (params.name || params.nodeName || params.node_name) : null;
   var node = null;
   if (id) node = await findNodeByIdAsync(id);
   if (!node && nodeName) node = findNodeByName(nodeName);
@@ -3724,7 +4131,12 @@ handlers.get_design_context = async function(params) {
     var sel = figma.currentPage.selection;
     node = sel && sel.length > 0 ? sel[0] : null;
   }
-  if (!node) throw new Error("No node specified and nothing selected. Pass nodeId or select a node.");
+  if (!node) {
+    var errMsg = (id || nodeName) && typeof getNodeNotFoundContext === "function"
+      ? getNodeNotFoundContext(id, nodeName)
+      : "No node specified and nothing selected. Pass nodeId or select a node in Figma.";
+    throw new Error(errMsg);
+  }
 
   // Build variable name lookup: variableId → name
   // Use getLocalVariablesAsync (single call) instead of per-ID fetches — avoids O(n²) await loop
@@ -3789,6 +4201,26 @@ handlers.get_design_context = async function(params) {
     var fillVal = resolveFill(nd);
     if (fillVal) ctx.fill = fillVal;
 
+    // Direct token bindings
+    try {
+      if (nd.boundVariables) {
+        var bvKeys = Object.keys(nd.boundVariables);
+        for (var bvi = 0; bvi < bvKeys.length; bvi++) {
+          var bvk = bvKeys[bvi];
+          var binding = nd.boundVariables[bvk];
+          var bindId = binding ? (Array.isArray(binding) ? (binding[0] ? binding[0].id : null) : binding.id) : null;
+          if (bindId && varMap[bindId]) {
+            var vName = varMap[bindId].name;
+            if (bvk === "fills" || bvk === "fill") ctx.fillToken = vName;
+            else if (bvk === "strokes" || bvk === "stroke") ctx.strokeToken = vName;
+            else if (bvk === "itemSpacing") ctx.gapToken = vName;
+            else if (bvk === "paddingTop" || bvk === "paddingBottom" || bvk === "paddingLeft" || bvk === "paddingRight") ctx.paddingToken = vName;
+            else if (bvk === "topLeftRadius" || bvk === "cornerRadius") ctx.radiusToken = vName;
+          }
+        }
+      }
+    } catch(e) {}
+
     // Stroke
     try {
       if (nd.strokes && nd.strokes.length && nd.strokes[0].type === "SOLID") {
@@ -3841,16 +4273,17 @@ handlers.get_design_context = async function(params) {
     // documentAccess: dynamic-page, so collect now and resolve after the walk.
     if (nd.type === "INSTANCE") {
       ctxInstances.push({ info: ctx, node: nd });
-      try {
-        if (nd.componentProperties) {
-          var props = {};
-          var pks = Object.keys(nd.componentProperties);
-          for (var pi = 0; pi < pks.length; pi++) props[pks[pi]] = nd.componentProperties[pks[pi]].value;
-          if (pks.length) ctx.component = { properties: props };
-        }
-      } catch(e) {}
+      var parsedProps = typeof cleanComponentProperties === "function" ? cleanComponentProperties(nd) : null;
+      if (parsedProps) {
+        if (parsedProps.variant) ctx.variant = parsedProps.variant;
+        if (parsedProps.props) ctx.props = parsedProps.props;
+      }
     }
 
+    // Role
+    var sRole = typeof inferSemanticRole === "function" ? inferSemanticRole(nd, ctx) : null;
+    if (sRole) ctx.role = sRole;
+
     // Children (limited depth to avoid token overflow)
     if (depth < 4 && nd.children && nd.children.length) {
       ctx.children = [];
@@ -3907,9 +4340,23 @@ handlers.get_design_context = async function(params) {
 
 // Aliases for developer convenience & MCP tool naming compatibility
 handlers.inspect_node = handlers.get_design_context;
+handlers.inspectNode = handlers.get_design_context;
 handlers.inspect = handlers.get_design_context;
+handlers.getDesignContext = handlers.get_design_context;
+handlers.designContext = handlers.get_design_context;
+handlers.getCss = handlers.get_css;
+handlers.css = handlers.get_css;
+handlers.get_node = handlers.get_node_detail;
+handlers.getNode = handlers.get_node_detail;
+handlers.get_node_detail = handlers.get_node_detail;
+handlers.getNodeDetail = handlers.get_node_detail;
 handlers.get_node_info = handlers.get_node_detail;
+handlers.getNodeInfo = handlers.get_node_detail;
 handlers.node_detail = handlers.get_node_detail;
+handlers.nodeDetail = handlers.get_node_detail;
+handlers.node_info = handlers.get_node_detail;
+handlers.nodeInfo = handlers.get_node_detail;
+
 
 // get_component_map — list every component instance in a frame with variant properties
 // Use this to map Figma components to their code equivalents
@@ -4220,8 +4667,21 @@ handlers.get_variables = async function() {
 };
 
 handlers.get_variable_tokens = handlers.get_variables;
+handlers.getVariableTokens = handlers.get_variables;
 handlers.get_tokens = handlers.get_variables;
+handlers.getTokens = handlers.get_variables;
 handlers.tokens = handlers.get_variables;
+handlers.variables = handlers.get_variables;
+handlers.getVariables = handlers.get_variables;
+handlers.getStyles = handlers.get_styles;
+handlers.styles = handlers.get_styles;
+handlers.getLocalComponents = handlers.get_local_components;
+handlers.localComponents = handlers.get_local_components;
+handlers.getViewport = handlers.get_viewport;
+handlers.setViewport = handlers.set_viewport;
+handlers.getComponentMap = handlers.get_component_map;
+handlers.getUnmappedComponents = handlers.get_unmapped_components;
+
 
 // ─── EXPORT ASSETS (Batch Icon & Image Extractor) ────────────────────────────
 handlers.export_assets = async function(params) {
@@ -4348,6 +4808,9 @@ handlers.export_assets = async function(params) {
   };
 };
 
+handlers.exportAssets = handlers.export_assets;
+
+
 
 // ── plugin-src/handlers-tokens.js ──
 // ─── DESIGN TOKEN OPERATIONS (v1.7.0) ───────────────────────────────────────
@@ -5471,6 +5934,29 @@ handlers.removeComponentProperty = async function(params) {
   };
 };
 
+// ─── ALIASES FOR TOKEN & COMPONENT PROPERTY HANDLERS ─────────────────────────
+handlers.create_variable_collection = handlers.createVariableCollection;
+handlers.create_variable = handlers.createVariable;
+handlers.add_variable_mode = handlers.addVariableMode;
+handlers.rename_variable_mode = handlers.renameVariableMode;
+handlers.remove_variable_mode = handlers.removeVariableMode;
+handlers.set_variable_value = handlers.setVariableValue;
+handlers.set_frame_variable_mode = handlers.setFrameVariableMode;
+handlers.clear_frame_variable_mode = handlers.clearFrameVariableMode;
+handlers.apply_variable = handlers.applyVariable;
+handlers.create_paint_style = handlers.createPaintStyle;
+handlers.create_text_style = handlers.createTextStyle;
+handlers.create_component = handlers.createComponent;
+handlers.modify_variable = handlers.modifyVariable;
+handlers.setup_design_tokens = handlers.setupDesignTokens;
+handlers.apply_text_style = handlers.applyTextStyle;
+handlers.add_component_property = handlers.addComponentProperty;
+handlers.bind_component_property_to_text = handlers.bindComponentPropertyToText;
+handlers.bind_component_property = handlers.bindComponentProperty;
+handlers.unbind_component_property = handlers.unbindComponentProperty;
+handlers.remove_component_property = handlers.removeComponentProperty;
+
+
 
 // ── plugin-src/handlers-write-ops.js ──
 // ─── NEW WRITE OPERATIONS ────────────────────────────────────────────────────
@@ -5568,6 +6054,8 @@ handlers.set_selection = async function(params) {
   return { selected: nodes.map(nodeToInfo) };
 };
 
+handlers.setSelection = handlers.set_selection;
+
 // batch — execute multiple operations in one call
 // Supported operations: create, modify, delete (single or batch ids), append, clone
 handlers.batch = async function(params) {
@@ -5579,7 +6067,7 @@ handlers.batch = async function(params) {
   var results = [];
   for (var i = 0; i < operations.length; i++) {
     var op = operations[i];
-    var handler = handlers[op.operation];
+    var handler = typeof resolveOperationHandler === "function" ? resolveOperationHandler(op.operation) : handlers[op.operation];
     if (!handler) {
       results.push({ index: i, operation: op.operation, success: false, error: "Unknown operation" });
       continue;
@@ -5595,6 +6083,7 @@ handlers.batch = async function(params) {
 };
 
 
+
 // ── plugin-src/main.js ──
 // ─── PLUGIN ENTRY POINT ───────────────────────────────────────────────────────
 
@@ -5921,7 +6410,9 @@ figma.ui.onmessage = async (request) => {
   }
 
   const { id, operation, params } = request;
-  const handler = handlers[operation];
+  const handler = typeof resolveOperationHandler === "function"
+    ? resolveOperationHandler(operation)
+    : handlers[operation];
 
   if (!handler) {
     figma.ui.postMessage({