@mp3wizard/figma-console-mcp 1.32.3 → 1.34.1

package/figma-desktop-bridge/code.js

@@ -5,8 +5,11 @@
 // which then forwards messages to the MCP server over the WebSocket bridge.
 
 // Plugin version — sent in FILE_INFO for server-side version compatibility checks.
-// The server compares this against its own version to detect stale cached plugins.
-var PLUGIN_VERSION = '1.32.1'; // Kept in sync with package.json by scripts/release.sh — see issue #62.
+// The server compares this against the version of the plugin files IT ships to
+// detect stale cached plugins. Bumped by scripts/release.sh ONLY when plugin files
+// change (see issue #62); server-only releases leave it alone, so it may lag
+// package.json — that's intentional, not drift.
+var PLUGIN_VERSION = '1.34.0'; // Last release in which plugin files changed.
 
 console.log('🌉 [Desktop Bridge] Plugin loaded (v' + PLUGIN_VERSION + ')');
 
@@ -148,6 +151,23 @@ var __stickyColors = {
   }
 })();
 
+// Restore persisted cloud pairing config (stored via STORE_CLOUD_CONFIG) and
+// push it to the UI so cloud users don't lose their pairing on plugin reopen.
+// Fire-and-forget: never blocks the FILE_INFO/VARIABLES_DATA pushes above.
+(function() {
+  figma.clientStorage.getAsync('cloudConfig')
+    .then(function(stored) {
+      // Skip if nothing stored or the shape is unusable (e.g., cleared config)
+      if (!stored || !stored.code) return;
+      figma.ui.postMessage({ type: 'CLOUD_CONFIG_RESTORED', config: stored });
+      console.log('🌉 [Desktop Bridge] Restored cloud config from clientStorage');
+    })
+    .catch(function(error) {
+      // clientStorage can throw — non-critical, just log
+      console.warn('🌉 [Desktop Bridge] Could not restore cloud config:', error && error.message ? error.message : String(error));
+    });
+})();
+
 // Helper function to serialize a variable for response
 function serializeVariable(v) {
   return {
@@ -356,6 +376,32 @@ async function loadFontsForNode(node) {
   }
 }
 
+// Resolve a caller-supplied component property name against the instance's
+// actual property keys. TEXT/BOOLEAN/INSTANCE_SWAP property names carry a
+// #nodeId suffix (e.g. "title#2605:17"), so a bare "title" from the caller
+// must be mapped to the suffixed key. Resolution tiers:
+//   1. Exact match (covers VARIANT props and fully-suffixed names)
+//   2. Base name before '#' matches exactly
+//   3. Case-insensitive base-name match
+// Returns the resolved key, or null if nothing matches.
+function resolvePropertyName(currentProps, name) {
+  if (!currentProps || !name) return null;
+  if (currentProps[name] !== undefined) return name;
+  var existingProp;
+  for (existingProp in currentProps) {
+    if (currentProps.hasOwnProperty(existingProp) && existingProp.split('#')[0] === name) {
+      return existingProp;
+    }
+  }
+  var lowerName = String(name).toLowerCase();
+  for (existingProp in currentProps) {
+    if (currentProps.hasOwnProperty(existingProp) && existingProp.split('#')[0].toLowerCase() === lowerName) {
+      return existingProp;
+    }
+  }
+  return null;
+}
+
 // Listen for requests from UI (e.g., component data requests, write operations)
 figma.ui.onmessage = async (msg) => {
 
@@ -1904,12 +1950,19 @@ figma.ui.onmessage = async (msg) => {
       // Track failures so they surface in the result instead of failing silently.
       var overrideWarnings = [];
 
-      // Apply property overrides
+      // Apply property overrides. Property keys on the instance carry #nodeId
+      // suffixes ("title#2605:17"), so resolve the caller's bare name first —
+      // otherwise setProperties throws "Could not find a component property".
       if (msg.overrides) {
+        var instanceProps = {};
+        try { instanceProps = instance.componentProperties || {}; } catch (e) { instanceProps = {}; }
         for (var propName in msg.overrides) {
           if (msg.overrides.hasOwnProperty(propName)) {
+            var resolvedName = resolvePropertyName(instanceProps, propName);
             try {
-              instance.setProperties({ [propName]: msg.overrides[propName] });
+              var propsObj = {};
+              propsObj[resolvedName || propName] = msg.overrides[propName];
+              instance.setProperties(propsObj);
             } catch (propError) {
               var pMsg = propError && propError.message ? propError.message : String(propError);
               console.warn('🌉 [Desktop Bridge] Could not set property ' + propName + ':', pMsg);
@@ -1935,6 +1988,8 @@ figma.ui.onmessage = async (msg) => {
         var parent = await figma.getNodeByIdAsync(msg.parentId);
         if (parent && 'appendChild' in parent) {
           parent.appendChild(instance);
+        } else {
+          overrideWarnings.push('parentId "' + msg.parentId + '" not found or cannot accept children; instance placed on current page');
         }
       }
 
@@ -1967,6 +2022,293 @@ figma.ui.onmessage = async (msg) => {
     }
   }
 
+  // ============================================================================
+  // CREATE_COMPONENT_SET - Build a component set with variants in one call
+  // Two modes:
+  //   A) baseComponentId + properties: clone the base for every combination of
+  //      the property axes ({State:[default,hover], Size:[sm,lg]} → 4 variants),
+  //      rename each to "Prop=Value, Prop=Value", combineAsVariants.
+  //      The base component itself BECOMES the first variant (same node ID),
+  //      so existing instances of the base survive as instances of that variant.
+  //   B) componentIds (+ optional variantProperties): combine existing local
+  //      COMPONENT nodes as variants, optionally renaming them first.
+  // Variant properties are derived by Figma from the "Prop=Value" names, and
+  // componentPropertyDefinitions live on the resulting SET (not the variants).
+  // No text is written here, so no font loading is needed (clone() copies text
+  // without touching characters).
+  // ============================================================================
+  else if (msg.type === 'CREATE_COMPONENT_SET') {
+    try {
+      console.log('🌉 [Desktop Bridge] Creating component set:', msg.name || msg.baseComponentId || (msg.componentIds && msg.componentIds.length + ' components'));
+
+      var MAX_VARIANTS = 100;
+      var setWarnings = [];
+      // Rollback state — if anything throws before combineAsVariants succeeds,
+      // remove Mode A clones, restore the base's name, AND restore every
+      // Mode B component the handler renamed, so no partial artifacts remain.
+      // (Previously only Mode A was rolled back: a throw from the
+      // duplicate-combo check or combineAsVariants left the user's standalone
+      // components permanently renamed with no set created.)
+      var createdClones = [];
+      var renamedBase = null;
+      var originalBaseName = null;
+      var renamedNodes = []; // Mode B: [{ node, originalName }]
+      var combineDone = false;
+
+      function rollbackComponentSetWork() {
+        for (var rc = 0; rc < createdClones.length; rc++) {
+          try { createdClones[rc].remove(); } catch (e) {}
+        }
+        createdClones = [];
+        if (renamedBase && originalBaseName !== null) {
+          try { renamedBase.name = originalBaseName; } catch (e) {}
+          renamedBase = null;
+        }
+        for (var rn = 0; rn < renamedNodes.length; rn++) {
+          try { renamedNodes[rn].node.name = renamedNodes[rn].originalName; } catch (e) {}
+        }
+        renamedNodes = [];
+      }
+
+      // Build "Prop=Value, Prop=Value" from an axis-ordered property map
+      function comboName(combo, axisOrder) {
+        var parts = [];
+        for (var a = 0; a < axisOrder.length; a++) {
+          parts.push(axisOrder[a] + '=' + combo[axisOrder[a]]);
+        }
+        return parts.join(', ');
+      }
+
+      var variantNodes = [];
+
+      if (msg.baseComponentId) {
+        // ---- Mode A: generate variants from a base component ----
+        if (!msg.properties || Object.keys(msg.properties).length === 0) {
+          throw new Error('properties is required with baseComponentId. Example: { "State": ["default", "hover"], "Size": ["sm", "lg"] }');
+        }
+
+        var base = await figma.getNodeByIdAsync(msg.baseComponentId);
+        if (!base) throw new Error('Base component not found: ' + msg.baseComponentId + '. NodeIds are session-specific — re-search components to get fresh IDs.');
+        if (base.type !== 'COMPONENT') {
+          throw new Error('baseComponentId must be a COMPONENT node, got ' + base.type + '. To convert a frame, use figma_execute with figma.createComponentFromNode(frame) first.');
+        }
+        if (base.parent && base.parent.type === 'COMPONENT_SET') {
+          throw new Error('Base component is already a variant inside component set "' + base.parent.name + '". Use a standalone component.');
+        }
+
+        // Validate axes and build the cartesian product (last axis varies fastest,
+        // matching Figma's convention of State as the final property)
+        var axisOrder = [];
+        var axisValues = {};
+        for (var axis in msg.properties) {
+          if (msg.properties.hasOwnProperty(axis)) {
+            var vals = msg.properties[axis];
+            if (!vals || !vals.length) throw new Error('Property axis "' + axis + '" has no values');
+            var uniq = {};
+            for (var vv = 0; vv < vals.length; vv++) {
+              var sval = String(vals[vv]);
+              if (sval.indexOf('=') !== -1 || sval.indexOf(',') !== -1) {
+                throw new Error('Variant value "' + sval + '" (axis "' + axis + '") must not contain "=" or "," — Figma parses variant names on those characters');
+              }
+              if (uniq[sval]) throw new Error('Duplicate value "' + sval + '" in axis "' + axis + '"');
+              uniq[sval] = true;
+            }
+            if (axis.indexOf('=') !== -1 || axis.indexOf(',') !== -1) {
+              throw new Error('Property name "' + axis + '" must not contain "=" or ","');
+            }
+            axisOrder.push(axis);
+            axisValues[axis] = vals.map(String);
+          }
+        }
+
+        var combos = [{}];
+        for (var ai = 0; ai < axisOrder.length; ai++) {
+          var nextCombos = [];
+          var axisName = axisOrder[ai];
+          for (var ci = 0; ci < combos.length; ci++) {
+            for (var vi2 = 0; vi2 < axisValues[axisName].length; vi2++) {
+              var extended = {};
+              for (var k in combos[ci]) { if (combos[ci].hasOwnProperty(k)) extended[k] = combos[ci][k]; }
+              extended[axisName] = axisValues[axisName][vi2];
+              nextCombos.push(extended);
+            }
+          }
+          combos = nextCombos;
+        }
+
+        if (combos.length > MAX_VARIANTS) {
+          throw new Error('Requested ' + combos.length + ' variants — capped at ' + MAX_VARIANTS + '. Split into multiple sets or reduce axis values.');
+        }
+
+        // Base becomes the first combination; clones fill in the rest.
+        // Stack clones vertically so nothing overlaps even without autoArrange.
+        var baseX = base.x;
+        var baseY = base.y;
+        var stepY = Math.ceil(base.height) + 40;
+        originalBaseName = base.name;
+        renamedBase = base;
+        base.name = comboName(combos[0], axisOrder);
+        variantNodes.push(base);
+        for (var ci2 = 1; ci2 < combos.length; ci2++) {
+          var clone = base.clone();
+          clone.name = comboName(combos[ci2], axisOrder);
+          clone.x = baseX;
+          clone.y = baseY + ci2 * stepY;
+          createdClones.push(clone);
+          variantNodes.push(clone);
+        }
+      } else if (msg.componentIds && msg.componentIds.length) {
+        // ---- Mode B: combine existing components ----
+        if (msg.componentIds.length > MAX_VARIANTS) {
+          throw new Error('Requested ' + msg.componentIds.length + ' variants — capped at ' + MAX_VARIANTS + '.');
+        }
+        if (msg.variantProperties && msg.variantProperties.length !== msg.componentIds.length) {
+          throw new Error('variantProperties length (' + msg.variantProperties.length + ') must match componentIds length (' + msg.componentIds.length + ')');
+        }
+
+        for (var ni = 0; ni < msg.componentIds.length; ni++) {
+          var node = await figma.getNodeByIdAsync(msg.componentIds[ni]);
+          if (!node) throw new Error('Component not found: ' + msg.componentIds[ni] + '. NodeIds are session-specific — re-search components to get fresh IDs.');
+          if (node.type !== 'COMPONENT') {
+            throw new Error('Node ' + msg.componentIds[ni] + ' is a ' + node.type + ', not a COMPONENT. All componentIds must reference COMPONENT nodes.');
+          }
+          if (node.parent && node.parent.type === 'COMPONENT_SET') {
+            throw new Error('Component "' + node.name + '" (' + node.id + ') is already a variant in set "' + node.parent.name + '". Components can only belong to one set.');
+          }
+          if (msg.variantProperties) {
+            var props = msg.variantProperties[ni];
+            var propKeys = Object.keys(props);
+            if (!propKeys.length) throw new Error('variantProperties[' + ni + '] is empty — each entry needs at least one property (e.g. { "State": "hover" })');
+            // Same '='/',' validation as Mode A — a value like "hover,Size=lg"
+            // would silently create a bogus axis when Figma parses the name.
+            for (var pk = 0; pk < propKeys.length; pk++) {
+              var propName = propKeys[pk];
+              var propValue = String(props[propName]);
+              if (propName.indexOf('=') !== -1 || propName.indexOf(',') !== -1) {
+                throw new Error('Property name "' + propName + '" (variantProperties[' + ni + ']) must not contain "=" or "," — Figma parses variant names on those characters');
+              }
+              if (propValue.indexOf('=') !== -1 || propValue.indexOf(',') !== -1) {
+                throw new Error('Variant value "' + propValue + '" (property "' + propName + '", variantProperties[' + ni + ']) must not contain "=" or "," — Figma parses variant names on those characters');
+              }
+            }
+            // Record the rename so the rollback path can restore it.
+            renamedNodes.push({ node: node, originalName: node.name });
+            variantNodes.push(node);
+            node.name = comboName(props, propKeys);
+          } else {
+            variantNodes.push(node);
+            if (node.name.indexOf('=') === -1) {
+              setWarnings.push('Component "' + node.name + '" is not named "Prop=Value" — Figma will file it under "Property 1=' + node.name + '". Pass variantProperties to control naming.');
+            }
+          }
+        }
+
+        // Duplicate variant names create an invalid (conflicting) set — fail early
+        var nameSeen = {};
+        for (var dn = 0; dn < variantNodes.length; dn++) {
+          if (nameSeen[variantNodes[dn].name]) {
+            throw new Error('Two variants would have identical properties: "' + variantNodes[dn].name + '". Each variant needs a unique property combination.');
+          }
+          nameSeen[variantNodes[dn].name] = true;
+        }
+      } else {
+        throw new Error('Provide either baseComponentId + properties (generate variants) or componentIds (combine existing components).');
+      }
+
+      // Resolve the parent — combineAsVariants REQUIRES a parent, and the set is
+      // created inside it. Fall back to the current page.
+      var setParent = figma.currentPage;
+      if (msg.parentId) {
+        var requestedParent = await figma.getNodeByIdAsync(msg.parentId);
+        if (requestedParent && typeof requestedParent.appendChild === 'function' && requestedParent.type !== 'COMPONENT' && requestedParent.type !== 'COMPONENT_SET' && requestedParent.type !== 'INSTANCE') {
+          setParent = requestedParent;
+        } else {
+          setWarnings.push('parentId "' + msg.parentId + '" not found or cannot contain a component set; created on the current page instead');
+        }
+      }
+
+      // Housekeeping on failure happens in the outer catch (gated on
+      // !combineDone) — it restores Mode A clones/base AND Mode B renames.
+      var componentSet = figma.combineAsVariants(variantNodes, setParent);
+      combineDone = true;
+      if (msg.name) componentSet.name = msg.name;
+      if (msg.position) {
+        componentSet.x = msg.position.x || 0;
+        componentSet.y = msg.position.y || 0;
+      }
+
+      // componentPropertyDefinitions live on the SET (not the variants) —
+      // read them back so callers see the axes Figma actually derived.
+      var propertyDefinitions = {};
+      try {
+        var defs = componentSet.componentPropertyDefinitions;
+        for (var defName in defs) {
+          if (defs.hasOwnProperty(defName)) {
+            propertyDefinitions[defName] = {
+              type: defs[defName].type,
+              defaultValue: defs[defName].defaultValue,
+              variantOptions: defs[defName].variantOptions || []
+            };
+          }
+        }
+      } catch (defError) {
+        setWarnings.push('Could not read componentPropertyDefinitions: ' + (defError && defError.message ? defError.message : String(defError)));
+      }
+
+      var variantSummaries = [];
+      for (var vs = 0; vs < componentSet.children.length; vs++) {
+        var child = componentSet.children[vs];
+        if (child.type === 'COMPONENT') {
+          // Include each variant's key — instantiation uses VARIANT keys, not the set key
+          variantSummaries.push({ id: child.id, name: child.name, key: child.key });
+        }
+      }
+
+      figma.currentPage.selection = [componentSet];
+      figma.viewport.scrollAndZoomIntoView([componentSet]);
+
+      console.log('🌉 [Desktop Bridge] Component set created:', componentSet.id, 'with', variantSummaries.length, 'variants');
+
+      // Everything rides in `data` — ui.html's handleResult only forwards
+      // whitelisted top-level fields, and msg.data is on that whitelist.
+      figma.ui.postMessage({
+        type: 'CREATE_COMPONENT_SET_RESULT',
+        requestId: msg.requestId,
+        success: true,
+        data: {
+          componentSet: {
+            id: componentSet.id,
+            name: componentSet.name,
+            key: componentSet.key,
+            x: componentSet.x,
+            y: componentSet.y,
+            width: componentSet.width,
+            height: componentSet.height,
+            parentId: componentSet.parent ? componentSet.parent.id : null
+          },
+          variantCount: variantSummaries.length,
+          variants: variantSummaries,
+          propertyDefinitions: propertyDefinitions,
+          warnings: setWarnings.length ? setWarnings : undefined
+        }
+      });
+
+    } catch (error) {
+      var csErrorMsg = error && error.message ? error.message : String(error);
+      console.error('🌉 [Desktop Bridge] Create component set error:', csErrorMsg);
+      // Undo partial work unless the set was actually created (after
+      // combineAsVariants succeeds the clones/renames live inside the set —
+      // never touch them then).
+      try { if (!combineDone) rollbackComponentSetWork(); } catch (e) {}
+      figma.ui.postMessage({
+        type: 'CREATE_COMPONENT_SET_RESULT',
+        requestId: msg.requestId,
+        success: false,
+        error: csErrorMsg
+      });
+    }
+  }
+
   // ============================================================================
   // SET_NODE_DESCRIPTION - Set description on component/style
   // ============================================================================
@@ -2556,16 +2898,25 @@ figma.ui.onmessage = async (msg) => {
       var nodeIds = msg.nodeIds || (msg.nodeId ? [msg.nodeId] : []);
       var updatedCount = 0;
       var updatedNodes = [];
+      var skipWarnings = [];
 
       for (var i = 0; i < nodeIds.length; i++) {
         var node = await figma.getNodeByIdAsync(nodeIds[i]);
-        if (node && 'fills' in node) {
+        if (!node) {
+          skipWarnings.push('node "' + nodeIds[i] + '" not found');
+        } else if (!('fills' in node)) {
+          skipWarnings.push('node "' + nodeIds[i] + '" (' + node.type + ') does not support fills');
+        } else {
           node.fills = [fill];
           updatedCount++;
           updatedNodes.push({ id: node.id, name: node.name });
         }
       }
 
+      if (updatedCount === 0 && nodeIds.length > 0) {
+        throw new Error('Image fill applied to 0 node(s): ' + skipWarnings.join('; '));
+      }
+
       console.log('🌉 [Desktop Bridge] Image fill applied to', updatedCount, 'node(s), hash:', imageHash);
 
       figma.ui.postMessage({
@@ -2574,7 +2925,8 @@ figma.ui.onmessage = async (msg) => {
         success: true,
         imageHash: imageHash,
         updatedCount: updatedCount,
-        nodes: updatedNodes
+        nodes: updatedNodes,
+        warnings: skipWarnings.length ? skipWarnings : undefined
       });
 
     } catch (error) {
@@ -2968,8 +3320,10 @@ figma.ui.onmessage = async (msg) => {
       if (props.name) newNode.name = props.name;
       if (props.x !== undefined) newNode.x = props.x;
       if (props.y !== undefined) newNode.y = props.y;
-      if (props.width !== undefined && props.height !== undefined) {
-        newNode.resize(props.width, props.height);
+      if (props.width !== undefined || props.height !== undefined) {
+        var resizeWidth = props.width !== undefined ? props.width : newNode.width;
+        var resizeHeight = props.height !== undefined ? props.height : newNode.height;
+        newNode.resize(resizeWidth, resizeHeight);
       }
 
       // Apply fills if specified
@@ -3293,30 +3647,23 @@ figma.ui.onmessage = async (msg) => {
       // VARIANT properties use just "PropertyName"
       var propsToSet = {};
       var propUpdates = msg.properties || {};
+      var propWarnings = [];
+      var hasTextProp = false;
 
       for (var propName in propUpdates) {
+        if (!propUpdates.hasOwnProperty(propName)) continue;
         var newValue = propUpdates[propName];
+        var resolvedName = resolvePropertyName(currentProps, propName);
 
-        // Check if this exact property name exists
-        if (currentProps[propName] !== undefined) {
-          propsToSet[propName] = newValue;
-          console.log('🌉 [Desktop Bridge] Setting property:', propName, '=', newValue);
-        } else {
-          // Try to find a matching property with a suffix (for TEXT/BOOLEAN/INSTANCE_SWAP)
-          var foundMatch = false;
-          for (var existingProp in currentProps) {
-            // Check if this is the base property name with a node ID suffix
-            if (existingProp.startsWith(propName + '#')) {
-              propsToSet[existingProp] = newValue;
-              console.log('🌉 [Desktop Bridge] Found suffixed property:', existingProp, '=', newValue);
-              foundMatch = true;
-              break;
-            }
-          }
-
-          if (!foundMatch) {
-            console.warn('🌉 [Desktop Bridge] Property not found:', propName, '- Available:', Object.keys(currentProps).join(', '));
+        if (resolvedName !== null) {
+          propsToSet[resolvedName] = newValue;
+          if (currentProps[resolvedName] && currentProps[resolvedName].type === 'TEXT') {
+            hasTextProp = true;
           }
+          console.log('🌉 [Desktop Bridge] Setting property:', resolvedName, '=', newValue);
+        } else {
+          console.warn('🌉 [Desktop Bridge] Property not found:', propName, '- Available:', Object.keys(currentProps).join(', '));
+          propWarnings.push('property "' + propName + '" not found; available: ' + Object.keys(currentProps).join(', '));
         }
       }
 
@@ -3324,6 +3671,12 @@ figma.ui.onmessage = async (msg) => {
         throw new Error('No valid properties to set. Available properties: ' + Object.keys(currentProps).join(', '));
       }
 
+      // Pre-load fonts before applying TEXT-property values. Mutating text
+      // content in dynamic-page mode throws unless fonts are already loaded.
+      if (hasTextProp) {
+        await loadFontsForNode(node);
+      }
+
       // Apply the properties
       node.setProperties(propsToSet);
 
@@ -3348,7 +3701,8 @@ figma.ui.onmessage = async (msg) => {
             };
             return acc;
           }, {})
-        }
+        },
+        warnings: propWarnings.length ? propWarnings : undefined
       });
 
     } catch (error) {