@mp3wizard/figma-console-mcp 1.17.3 → 1.19.2

package/figma-desktop-bridge/code.js

@@ -894,6 +894,566 @@ figma.ui.onmessage = async (msg) => {
     }
   }
 
+  // ============================================================================
+  // ANALYZE_COMPONENT_SET - Variant state machine + cross-variant diff
+  // For COMPONENT_SET nodes: maps variant states to CSS pseudo-classes,
+  // computes visual diffs between default and other variants, and extracts
+  // the component API surface (props, slots, conditional elements).
+  // ============================================================================
+  else if (msg.type === 'ANALYZE_COMPONENT_SET') {
+    try {
+      console.log('🌉 [Desktop Bridge] Analyzing component set: ' + msg.nodeId);
+
+      var node = await figma.getNodeByIdAsync(msg.nodeId);
+      if (!node) throw new Error('Node not found: ' + msg.nodeId);
+      if (node.type !== 'COMPONENT_SET') throw new Error('Node is not a COMPONENT_SET. Type: ' + node.type);
+
+      // Build variable name lookup
+      var varNameMap = {};
+      try {
+        var allVars = await figma.variables.getLocalVariablesAsync();
+        var allColls = await figma.variables.getLocalVariableCollectionsAsync();
+        var collMap = {};
+        for (var ci = 0; ci < allColls.length; ci++) collMap[allColls[ci].id] = allColls[ci].name;
+        for (var vi = 0; vi < allVars.length; vi++) {
+          var v = allVars[vi];
+          varNameMap[v.id] = { name: v.name, collection: collMap[v.variableCollectionId] || null, type: v.resolvedType };
+        }
+      } catch(e) {}
+
+      function resolveVarId(id) {
+        return varNameMap[id] ? varNameMap[id].name : id;
+      }
+
+      function resolveBoundColor(bv) {
+        if (!bv) return null;
+        // Handle array format (fills/strokes)
+        if (Array.isArray(bv)) {
+          return bv.length > 0 && bv[0].id ? resolveVarId(bv[0].id) : null;
+        }
+        // Handle object format
+        if (bv.id) return resolveVarId(bv.id);
+        if (bv.color && bv.color.id) return resolveVarId(bv.color.id);
+        return null;
+      }
+
+      // Extract visual signature from a variant for diffing
+      function extractSignature(variant) {
+        var sig = {};
+
+        // Find the main interactive element — prioritize by: has strokes (input fields),
+        // is a FRAME with fills and strokes, or is the largest visible non-text child
+        var mainChild = null;
+        if (variant.children) {
+          // First pass: find child with strokes (likely the input/interactive element)
+          for (var i = 0; i < variant.children.length; i++) {
+            var child = variant.children[i];
+            try {
+              if (child.visible !== false && child.type !== 'TEXT' && child.strokes && child.strokes.length > 0) {
+                mainChild = child;
+                break;
+              }
+            } catch(e) {}
+          }
+          // Fallback: first visible FRAME child
+          if (!mainChild) {
+            for (var i2 = 0; i2 < variant.children.length; i2++) {
+              var c2 = variant.children[i2];
+              try {
+                if (c2.visible !== false && c2.type === 'FRAME') {
+                  mainChild = c2;
+                  break;
+                }
+              } catch(e) {}
+            }
+          }
+        }
+
+        if (mainChild) {
+              var child = mainChild;
+              // This is the main interactive frame
+              try {
+                var bv = child.boundVariables || {};
+                sig.fillToken = resolveBoundColor(bv.fills);
+                sig.strokeToken = resolveBoundColor(bv.strokes);
+                sig.strokeWeight = child.strokeWeight;
+
+                // Raw colors as fallback
+                if (!sig.fillToken && child.fills && child.fills.length > 0 && child.fills[0].color) {
+                  var fc = child.fills[0].color;
+                  sig.fillHex = '#' + Math.round(fc.r*255).toString(16).padStart(2,'0') + Math.round(fc.g*255).toString(16).padStart(2,'0') + Math.round(fc.b*255).toString(16).padStart(2,'0');
+                }
+                if (!sig.strokeToken && child.strokes && child.strokes.length > 0 && child.strokes[0].color) {
+                  var sc = child.strokes[0].color;
+                  sig.strokeHex = '#' + Math.round(sc.r*255).toString(16).padStart(2,'0') + Math.round(sc.g*255).toString(16).padStart(2,'0') + Math.round(sc.b*255).toString(16).padStart(2,'0');
+                }
+                sig.effects = child.effects && child.effects.length > 0 ? child.effects : null;
+                sig.opacity = child.opacity < 1 ? child.opacity : null;
+              } catch(e) {}
+
+              // Check text children for color changes
+              if (child.children) {
+                for (var t = 0; t < child.children.length; t++) {
+                  var textChild = child.children[t];
+                  if (textChild.type === 'TEXT') {
+                    try {
+                      var tbv = textChild.boundVariables || {};
+                      sig.textToken = resolveBoundColor(tbv.fills);
+                      if (!sig.textToken && textChild.fills && textChild.fills.length > 0 && textChild.fills[0].color) {
+                        var tc = textChild.fills[0].color;
+                        sig.textHex = '#' + Math.round(tc.r*255).toString(16).padStart(2,'0') + Math.round(tc.g*255).toString(16).padStart(2,'0') + Math.round(tc.b*255).toString(16).padStart(2,'0');
+                      }
+                    } catch(e) {}
+                    break; // First text node is enough
+                  }
+                }
+              }
+        }
+
+        // Check element visibility changes
+        sig.visibilityChanges = {};
+        if (variant.children) {
+          for (var j = 0; j < variant.children.length; j++) {
+            var ch = variant.children[j];
+            try {
+              if (!ch.visible) sig.visibilityChanges[ch.name] = false;
+            } catch(e) {}
+          }
+        }
+
+        return sig;
+      }
+
+      // Parse variant property definitions
+      var propDefs = node.componentPropertyDefinitions || {};
+      var variantAxes = {};
+      var componentProps = {};
+      var propKeys = Object.keys(propDefs);
+      for (var pk = 0; pk < propKeys.length; pk++) {
+        var propKey = propKeys[pk];
+        var propDef = propDefs[propKey];
+        if (propDef.type === 'VARIANT') {
+          variantAxes[propKey] = propDef.variantOptions || [];
+        } else {
+          componentProps[propKey] = {
+            type: propDef.type,
+            defaultValue: propDef.defaultValue
+          };
+        }
+      }
+
+      // CSS pseudo-class mapping for state variants
+      var stateMapping = {
+        'default': null,
+        'hover': ':hover',
+        'focus': ':focus-visible',
+        'focus-visible': ':focus-visible',
+        'focused': ':focus-visible',
+        'active': ':active',
+        'pressed': ':active',
+        'disabled': ':disabled, [aria-disabled="true"]',
+        'error': '[aria-invalid="true"]',
+        'invalid': '[aria-invalid="true"]',
+        'filled': '.has-value',
+        'selected': '[aria-selected="true"]',
+        'checked': ':checked',
+        'loading': '[aria-busy="true"]',
+        'readonly': '[readonly]',
+        'open': '[aria-expanded="true"]',
+        'closed': '[aria-expanded="false"]'
+      };
+
+      // Analyze variants grouped by axes
+      var variants = node.children || [];
+      var defaultVariant = null;
+      var stateAxis = null;
+      var sizeAxis = null;
+
+      // Detect which axis is "state" and which is "size"
+      var axisKeys = Object.keys(variantAxes);
+      for (var ak = 0; ak < axisKeys.length; ak++) {
+        var axisName = axisKeys[ak].toLowerCase();
+        var axisValues = variantAxes[axisKeys[ak]];
+        if (axisName === 'state' || axisName === 'status' || axisName === 'interaction') {
+          stateAxis = axisKeys[ak];
+        } else if (axisName === 'size' || axisName === 'scale') {
+          sizeAxis = axisKeys[ak];
+        }
+      }
+
+      // Build state machine from variants
+      var stateMachine = { states: {}, defaultState: null, cssMapping: {} };
+      var defaultSig = null;
+
+      // Find the default variant (first size, default state)
+      for (var di = 0; di < variants.length; di++) {
+        var vName = variants[di].name;
+        if (vName.indexOf('state=default') !== -1 && (sizeAxis ? vName.indexOf(sizeAxis + '=') !== -1 : true)) {
+          // Pick the first default state variant
+          if (!defaultVariant || vName.indexOf('large') !== -1) {
+            defaultVariant = variants[di];
+          }
+        }
+      }
+      if (defaultVariant) {
+        defaultSig = extractSignature(defaultVariant);
+      }
+
+      // Process each variant and compute diff from default
+      var variantDiffs = [];
+      for (var vdi = 0; vdi < variants.length; vdi++) {
+        var variant = variants[vdi];
+        var sig = extractSignature(variant);
+
+        // Parse variant name to extract axis values
+        var axisParts = variant.name.split(', ');
+        var axisValues = {};
+        for (var ap = 0; ap < axisParts.length; ap++) {
+          var parts = axisParts[ap].split('=');
+          if (parts.length === 2) axisValues[parts[0].trim()] = parts[1].trim();
+        }
+
+        var stateValue = stateAxis ? (axisValues[stateAxis] || 'default') : 'default';
+        var cssSelector = stateMapping[stateValue.toLowerCase()] || null;
+
+        // Compute diff from default
+        var diff = {};
+        if (defaultSig && variant.id !== (defaultVariant ? defaultVariant.id : null)) {
+          if (sig.fillToken !== defaultSig.fillToken) diff.fillToken = sig.fillToken || sig.fillHex;
+          if (sig.strokeToken !== defaultSig.strokeToken) diff.strokeToken = sig.strokeToken || sig.strokeHex;
+          if (sig.strokeWeight !== defaultSig.strokeWeight) diff.strokeWeight = sig.strokeWeight;
+          if (sig.textToken !== defaultSig.textToken) diff.textToken = sig.textToken || sig.textHex;
+          if (sig.opacity !== defaultSig.opacity) diff.opacity = sig.opacity;
+          if (JSON.stringify(sig.effects) !== JSON.stringify(defaultSig.effects)) diff.effects = sig.effects;
+          // Visibility changes not in default
+          var dvKeys = Object.keys(defaultSig.visibilityChanges);
+          var svKeys = Object.keys(sig.visibilityChanges);
+          for (var sk = 0; sk < svKeys.length; sk++) {
+            if (!defaultSig.visibilityChanges[svKeys[sk]]) {
+              if (!diff.visibilityChanges) diff.visibilityChanges = {};
+              diff.visibilityChanges[svKeys[sk]] = sig.visibilityChanges[svKeys[sk]];
+            }
+          }
+        }
+
+        variantDiffs.push({
+          name: variant.name,
+          id: variant.id,
+          axes: axisValues,
+          state: stateValue,
+          cssSelector: cssSelector,
+          diffFromDefault: Object.keys(diff).length > 0 ? diff : null,
+          signature: sig
+        });
+
+        // Build CSS mapping
+        if (cssSelector) {
+          stateMachine.cssMapping[stateValue] = cssSelector;
+        }
+        if (!stateMachine.states[stateValue]) {
+          stateMachine.states[stateValue] = [];
+        }
+        stateMachine.states[stateValue].push(variant.id);
+      }
+
+      if (defaultVariant) {
+        stateMachine.defaultState = 'default';
+        stateMachine.defaultSignature = defaultSig;
+      }
+
+      var result = {
+        nodeId: node.id,
+        nodeName: node.name,
+        variantCount: variants.length,
+        variantAxes: variantAxes,
+        componentProps: componentProps,
+        stateMachine: stateMachine,
+        variants: variantDiffs,
+        ai_instruction: 'Use cssMapping to implement interaction states. diffFromDefault shows only what changes per state — apply these as CSS pseudo-class or attribute overrides. componentProps maps to React/Vue component props (BOOLEAN → boolean prop, TEXT → string prop, INSTANCE_SWAP → ReactNode/slot prop).'
+      };
+
+      console.log('🌉 [Desktop Bridge] Component set analysis complete. ' + variants.length + ' variants, ' + Object.keys(stateMachine.cssMapping).length + ' CSS mappings');
+
+      figma.ui.postMessage({
+        type: 'ANALYZE_COMPONENT_SET_RESULT',
+        requestId: msg.requestId,
+        success: true,
+        data: result
+      });
+
+    } catch (error) {
+      var errorMsg = error && error.message ? error.message : String(error);
+      console.error('🌉 [Desktop Bridge] Analyze component set error:', errorMsg);
+      figma.ui.postMessage({
+        type: 'ANALYZE_COMPONENT_SET_RESULT',
+        requestId: msg.requestId,
+        success: false,
+        error: errorMsg
+      });
+    }
+  }
+
+  // ============================================================================
+  // DEEP_GET_COMPONENT - Full recursive component extraction for code generation
+  // Extracts visual properties, boundVariables, reactions, instance references,
+  // and annotations at every level of the component tree.
+  // ============================================================================
+  else if (msg.type === 'DEEP_GET_COMPONENT') {
+    try {
+      var maxDepth = msg.depth || 10;
+      console.log('🌉 [Desktop Bridge] Deep component fetch: ' + msg.nodeId + ' (depth: ' + maxDepth + ')');
+
+      var rootNode = await figma.getNodeByIdAsync(msg.nodeId);
+      if (!rootNode) {
+        throw new Error('Node not found: ' + msg.nodeId);
+      }
+
+      // Build a variable name lookup map for resolving boundVariables
+      var varNameMap = {};
+      try {
+        var allVars = await figma.variables.getLocalVariablesAsync();
+        var allCollections = await figma.variables.getLocalVariableCollectionsAsync();
+        var collectionMap = {};
+        for (var ci = 0; ci < allCollections.length; ci++) {
+          collectionMap[allCollections[ci].id] = allCollections[ci].name;
+        }
+        for (var vi = 0; vi < allVars.length; vi++) {
+          var v = allVars[vi];
+          varNameMap[v.id] = {
+            name: v.name,
+            resolvedType: v.resolvedType,
+            collection: collectionMap[v.variableCollectionId] || null,
+            scopes: v.scopes || [],
+            codeSyntax: v.codeSyntax || {}
+          };
+        }
+      } catch (e) {
+        console.log('🌉 [Desktop Bridge] Could not build variable map: ' + e.message);
+      }
+
+      // Resolve boundVariables to token names
+      function resolveBoundVars(bv) {
+        if (!bv) return null;
+        var resolved = {};
+        var keys = Object.keys(bv);
+        for (var k = 0; k < keys.length; k++) {
+          var prop = keys[k];
+          var binding = bv[prop];
+          if (Array.isArray(binding)) {
+            resolved[prop] = [];
+            for (var bi = 0; bi < binding.length; bi++) {
+              var b = binding[bi];
+              if (b && b.id) {
+                var info = varNameMap[b.id];
+                resolved[prop].push(info ? { id: b.id, name: info.name, collection: info.collection, resolvedType: info.resolvedType, codeSyntax: info.codeSyntax } : { id: b.id });
+              }
+            }
+          } else if (binding && binding.id) {
+            var info = varNameMap[binding.id];
+            resolved[prop] = info ? { id: binding.id, name: info.name, collection: info.collection, resolvedType: info.resolvedType, codeSyntax: info.codeSyntax } : { id: binding.id };
+          }
+        }
+        return Object.keys(resolved).length > 0 ? resolved : null;
+      }
+
+      // Extract visual properties from a node
+      function extractNodeProps(n) {
+        var props = {};
+
+        // Layout
+        if (n.layoutMode) props.layoutMode = n.layoutMode;
+        if (n.primaryAxisSizingMode) props.primaryAxisSizingMode = n.primaryAxisSizingMode;
+        if (n.counterAxisSizingMode) props.counterAxisSizingMode = n.counterAxisSizingMode;
+        if (n.layoutSizingHorizontal) props.layoutSizingHorizontal = n.layoutSizingHorizontal;
+        if (n.layoutSizingVertical) props.layoutSizingVertical = n.layoutSizingVertical;
+        if (n.primaryAxisAlignItems) props.primaryAxisAlignItems = n.primaryAxisAlignItems;
+        if (n.counterAxisAlignItems) props.counterAxisAlignItems = n.counterAxisAlignItems;
+        if (n.paddingLeft !== undefined && n.paddingLeft !== 0) props.paddingLeft = n.paddingLeft;
+        if (n.paddingRight !== undefined && n.paddingRight !== 0) props.paddingRight = n.paddingRight;
+        if (n.paddingTop !== undefined && n.paddingTop !== 0) props.paddingTop = n.paddingTop;
+        if (n.paddingBottom !== undefined && n.paddingBottom !== 0) props.paddingBottom = n.paddingBottom;
+        if (n.itemSpacing !== undefined && n.itemSpacing !== 0) props.itemSpacing = n.itemSpacing;
+        if (n.counterAxisSpacing !== undefined && n.counterAxisSpacing !== 0) props.counterAxisSpacing = n.counterAxisSpacing;
+        if (n.layoutWrap && n.layoutWrap !== 'NO_WRAP') props.layoutWrap = n.layoutWrap;
+        if (n.minWidth !== undefined) props.minWidth = n.minWidth;
+        if (n.maxWidth !== undefined) props.maxWidth = n.maxWidth;
+        if (n.minHeight !== undefined) props.minHeight = n.minHeight;
+        if (n.maxHeight !== undefined) props.maxHeight = n.maxHeight;
+        if (n.clipsContent) props.clipsContent = true;
+
+        // Visual
+        try {
+          if (n.fills && n.fills !== figma.mixed && n.fills.length > 0) props.fills = n.fills;
+        } catch (e) { /* mixed fills */ }
+        try {
+          if (n.strokes && n.strokes.length > 0) props.strokes = n.strokes;
+        } catch (e) {}
+        if (n.strokeWeight !== undefined && n.strokeWeight !== 0 && n.strokeWeight !== figma.mixed) props.strokeWeight = n.strokeWeight;
+        if (n.cornerRadius !== undefined && n.cornerRadius !== 0 && n.cornerRadius !== figma.mixed) props.cornerRadius = n.cornerRadius;
+        try {
+          if (n.effects && n.effects.length > 0) props.effects = n.effects;
+        } catch (e) {}
+        if (n.opacity !== undefined && n.opacity < 1) props.opacity = n.opacity;
+
+        // Typography
+        if (n.type === 'TEXT') {
+          try { props.characters = n.characters; } catch (e) {}
+          try { if (n.fontSize !== figma.mixed) props.fontSize = n.fontSize; } catch (e) {}
+          try { if (n.fontName !== figma.mixed) props.fontFamily = n.fontName.family; props.fontStyle = n.fontName.style; } catch (e) {}
+          try { if (n.fontWeight !== figma.mixed) props.fontWeight = n.fontWeight; } catch (e) {}
+          try { if (n.lineHeight !== figma.mixed) props.lineHeight = n.lineHeight; } catch (e) {}
+          try { if (n.letterSpacing !== figma.mixed) props.letterSpacing = n.letterSpacing; } catch (e) {}
+          try { if (n.textAlignHorizontal) props.textAlignHorizontal = n.textAlignHorizontal; } catch (e) {}
+          try { if (n.textAlignVertical) props.textAlignVertical = n.textAlignVertical; } catch (e) {}
+          try { if (n.textAutoResize && n.textAutoResize !== 'NONE') props.textAutoResize = n.textAutoResize; } catch (e) {}
+          try { if (n.textTruncation && n.textTruncation !== 'DISABLED') props.textTruncation = n.textTruncation; } catch (e) {}
+          try { if (n.textCase && n.textCase !== 'ORIGINAL') props.textCase = n.textCase; } catch (e) {}
+          try { if (n.textDecoration && n.textDecoration !== 'NONE') props.textDecoration = n.textDecoration; } catch (e) {}
+        }
+
+        // Design tokens (resolved to names)
+        try {
+          var resolved = resolveBoundVars(n.boundVariables);
+          if (resolved) props.boundVariables = resolved;
+        } catch (e) {}
+
+        // Prototype interactions
+        try {
+          if (n.reactions && n.reactions.length > 0) {
+            props.reactions = n.reactions.map(function(r) {
+              var reaction = { trigger: r.trigger };
+              if (r.action) {
+                reaction.action = { type: r.action.type };
+                if (r.action.navigation) reaction.action.navigation = r.action.navigation;
+                if (r.action.transition) reaction.action.transition = r.action.transition;
+                if (r.action.destinationId) reaction.action.destinationId = r.action.destinationId;
+              }
+              return reaction;
+            });
+          }
+        } catch (e) {}
+
+        // Annotations
+        try {
+          if (n.annotations && n.annotations.length > 0) {
+            props.annotations = n.annotations.map(function(a) {
+              var ann = {};
+              if (a.labelMarkdown) ann.labelMarkdown = a.labelMarkdown;
+              else if (a.label) ann.label = a.label;
+              if (a.properties) ann.properties = a.properties;
+              if (a.categoryId) ann.categoryId = a.categoryId;
+              return ann;
+            });
+          }
+        } catch (e) {}
+
+        // Component instance reference
+        if (n.type === 'INSTANCE') {
+          try {
+            if (n.mainComponent) {
+              props.mainComponent = {
+                id: n.mainComponent.id,
+                name: n.mainComponent.name,
+                key: n.mainComponent.key || null,
+                isVariant: n.mainComponent.parent && n.mainComponent.parent.type === 'COMPONENT_SET'
+              };
+              if (props.mainComponent.isVariant && n.mainComponent.parent) {
+                props.mainComponent.componentSetName = n.mainComponent.parent.name;
+                props.mainComponent.componentSetId = n.mainComponent.parent.id;
+              }
+            }
+          } catch (e) {}
+          try {
+            if (n.componentProperties) props.componentProperties = n.componentProperties;
+          } catch (e) {}
+        }
+
+        // Component definitions (for COMPONENT and COMPONENT_SET)
+        if (n.type === 'COMPONENT_SET' || n.type === 'COMPONENT') {
+          try {
+            if (n.componentPropertyDefinitions) props.componentPropertyDefinitions = n.componentPropertyDefinitions;
+          } catch (e) {}
+          if (n.type === 'COMPONENT' && n.variantProperties) {
+            props.variantProperties = n.variantProperties;
+          }
+        }
+
+        // Dimensions
+        try {
+          props.width = Math.round(n.width);
+          props.height = Math.round(n.height);
+        } catch (e) {}
+
+        return props;
+      }
+
+      // Recursive tree walker
+      function walkNode(n, currentDepth) {
+        var nodeData = {
+          id: n.id,
+          name: n.name,
+          type: n.type,
+          visible: n.visible
+        };
+
+        // Skip invisible nodes (unless they're component set variants)
+        if (!n.visible && n.type !== 'COMPONENT') {
+          nodeData._hidden = true;
+          return nodeData;
+        }
+
+        // Extract all properties
+        var props = extractNodeProps(n);
+        var propKeys = Object.keys(props);
+        for (var pk = 0; pk < propKeys.length; pk++) {
+          nodeData[propKeys[pk]] = props[propKeys[pk]];
+        }
+
+        // Recurse into children
+        if (n.children && currentDepth < maxDepth) {
+          nodeData.children = [];
+          for (var i = 0; i < n.children.length; i++) {
+            try {
+              nodeData.children.push(walkNode(n.children[i], currentDepth + 1));
+            } catch (e) {
+              // Skip inaccessible slot sublayers
+            }
+          }
+        } else if (n.children) {
+          // At max depth, include lightweight child summary
+          nodeData.childCount = n.children.length;
+          nodeData._depthLimitReached = true;
+        }
+
+        return nodeData;
+      }
+
+      var result = walkNode(rootNode, 0);
+      result._variableMapSize = Object.keys(varNameMap).length;
+      result._maxDepthUsed = maxDepth;
+
+      var resultJson = JSON.stringify(result);
+      console.log('🌉 [Desktop Bridge] Deep component data: ' + Math.round(resultJson.length / 1024) + 'KB, vars resolved: ' + Object.keys(varNameMap).length);
+
+      figma.ui.postMessage({
+        type: 'DEEP_GET_COMPONENT_RESULT',
+        requestId: msg.requestId,
+        success: true,
+        data: result
+      });
+
+    } catch (error) {
+      var errorMsg = error && error.message ? error.message : String(error);
+      console.error('🌉 [Desktop Bridge] Deep component error:', errorMsg);
+      figma.ui.postMessage({
+        type: 'DEEP_GET_COMPONENT_RESULT',
+        requestId: msg.requestId,
+        success: false,
+        error: errorMsg
+      });
+    }
+  }
+
   // ============================================================================
   // GET_LOCAL_COMPONENTS - Get all local components for design system manifest
   // ============================================================================
@@ -1342,6 +1902,249 @@ figma.ui.onmessage = async (msg) => {
     }
   }
 
+  // ============================================================================
+  // GET_ANNOTATIONS - Read annotations from a node (and optionally children)
+  // ============================================================================
+  else if (msg.type === 'GET_ANNOTATIONS') {
+    try {
+      console.log('🌉 [Desktop Bridge] Getting annotations for node:', msg.nodeId);
+
+      var node = await figma.getNodeByIdAsync(msg.nodeId);
+      if (!node) {
+        throw new Error('Node not found: ' + msg.nodeId);
+      }
+
+      // Get annotation categories for name resolution
+      var categories = [];
+      try {
+        categories = await figma.annotations.getAnnotationCategoriesAsync();
+      } catch (e) {
+        console.log('🌉 [Desktop Bridge] Could not fetch annotation categories:', e.message);
+      }
+
+      // Build category lookup map
+      var categoryMap = {};
+      for (var ci = 0; ci < categories.length; ci++) {
+        categoryMap[categories[ci].id] = categories[ci].name;
+      }
+
+      // Helper to extract annotations from a single node
+      function extractAnnotations(n) {
+        var anns = n.annotations || [];
+        var result = [];
+        for (var ai = 0; ai < anns.length; ai++) {
+          var ann = anns[ai];
+          var props = [];
+          if (ann.properties) {
+            for (var pi = 0; pi < ann.properties.length; pi++) {
+              props.push({ type: ann.properties[pi].type });
+            }
+          }
+          result.push({
+            label: ann.label || null,
+            labelMarkdown: ann.labelMarkdown || null,
+            properties: props.length > 0 ? props : null,
+            categoryId: ann.categoryId || null,
+            categoryName: ann.categoryId && categoryMap[ann.categoryId] ? categoryMap[ann.categoryId] : null
+          });
+        }
+        return result;
+      }
+
+      // Collect annotations from the node itself
+      var nodeAnnotations = extractAnnotations(node);
+      var childAnnotations = [];
+
+      // Optionally walk children
+      var includeChildren = msg.includeChildren || false;
+      var maxDepth = msg.depth || 1;
+
+      if (includeChildren && 'children' in node && node.children) {
+        function walkChildren(parent, currentDepth) {
+          if (currentDepth > maxDepth) return;
+          for (var i = 0; i < parent.children.length; i++) {
+            var child = parent.children[i];
+            try {
+              var anns = extractAnnotations(child);
+              if (anns.length > 0) {
+                childAnnotations.push({
+                  nodeId: child.id,
+                  nodeName: child.name,
+                  nodeType: child.type,
+                  annotations: anns
+                });
+              }
+              if ('children' in child && child.children) {
+                walkChildren(child, currentDepth + 1);
+              }
+            } catch (e) {
+              // Skip inaccessible children (slot sublayers, etc.)
+            }
+          }
+        }
+        walkChildren(node, 1);
+      }
+
+      var result = {
+        nodeId: node.id,
+        nodeName: node.name,
+        nodeType: node.type,
+        annotations: nodeAnnotations,
+        annotationCount: nodeAnnotations.length,
+        children: includeChildren ? childAnnotations : undefined,
+        childAnnotationCount: includeChildren ? childAnnotations.reduce(function(sum, c) { return sum + c.annotations.length; }, 0) : undefined,
+        availableCategories: categories.map(function(c) { return { id: c.id, name: c.name }; })
+      };
+
+      console.log('🌉 [Desktop Bridge] Annotations retrieved. Node: ' + nodeAnnotations.length + ', Children: ' + (childAnnotations.length || 0));
+
+      figma.ui.postMessage({
+        type: 'GET_ANNOTATIONS_RESULT',
+        requestId: msg.requestId,
+        success: true,
+        data: result
+      });
+
+    } catch (error) {
+      var errorMsg = error && error.message ? error.message : String(error);
+      console.error('🌉 [Desktop Bridge] Get annotations error:', errorMsg);
+      figma.ui.postMessage({
+        type: 'GET_ANNOTATIONS_RESULT',
+        requestId: msg.requestId,
+        success: false,
+        error: errorMsg
+      });
+    }
+  }
+
+  // ============================================================================
+  // SET_ANNOTATIONS - Write annotations to a node
+  // ============================================================================
+  else if (msg.type === 'SET_ANNOTATIONS') {
+    try {
+      console.log('🌉 [Desktop Bridge] Setting annotations on node:', msg.nodeId);
+
+      var node = await figma.getNodeByIdAsync(msg.nodeId);
+      if (!node) {
+        throw new Error('Node not found: ' + msg.nodeId);
+      }
+
+      // Verify node supports annotations
+      if (!('annotations' in node)) {
+        throw new Error('Node type ' + node.type + ' does not support annotations');
+      }
+
+      // Build the annotations array
+      var newAnnotations = [];
+      var inputAnnotations = msg.annotations || [];
+
+      for (var i = 0; i < inputAnnotations.length; i++) {
+        var input = inputAnnotations[i];
+        var ann = {};
+
+        if (input.label) {
+          ann.label = input.label;
+        }
+        if (input.labelMarkdown) {
+          ann.labelMarkdown = input.labelMarkdown;
+        }
+        if (input.properties && input.properties.length > 0) {
+          ann.properties = [];
+          for (var p = 0; p < input.properties.length; p++) {
+            ann.properties.push({ type: input.properties[p].type });
+          }
+        }
+        if (input.categoryId) {
+          ann.categoryId = input.categoryId;
+        }
+
+        newAnnotations.push(ann);
+      }
+
+      // Optionally append to existing annotations instead of replacing
+      if (msg.mode === 'append') {
+        var existing = node.annotations || [];
+        var merged = [];
+        for (var e = 0; e < existing.length; e++) {
+          var ex = existing[e];
+          var copy = {};
+          // Figma auto-populates both label and labelMarkdown on read,
+          // but rejects writing both — prefer labelMarkdown when both exist
+          if (ex.labelMarkdown) {
+            copy.labelMarkdown = ex.labelMarkdown;
+          } else if (ex.label) {
+            copy.label = ex.label;
+          }
+          if (ex.properties) copy.properties = ex.properties;
+          if (ex.categoryId) copy.categoryId = ex.categoryId;
+          merged.push(copy);
+        }
+        for (var n = 0; n < newAnnotations.length; n++) {
+          merged.push(newAnnotations[n]);
+        }
+        newAnnotations = merged;
+      }
+
+      // Set annotations on the node
+      node.annotations = newAnnotations;
+
+      console.log('🌉 [Desktop Bridge] Annotations set successfully. Count: ' + newAnnotations.length);
+
+      figma.ui.postMessage({
+        type: 'SET_ANNOTATIONS_RESULT',
+        requestId: msg.requestId,
+        success: true,
+        data: {
+          nodeId: node.id,
+          nodeName: node.name,
+          annotationCount: newAnnotations.length,
+          mode: msg.mode || 'replace'
+        }
+      });
+
+    } catch (error) {
+      var errorMsg = error && error.message ? error.message : String(error);
+      console.error('🌉 [Desktop Bridge] Set annotations error:', errorMsg);
+      figma.ui.postMessage({
+        type: 'SET_ANNOTATIONS_RESULT',
+        requestId: msg.requestId,
+        success: false,
+        error: errorMsg
+      });
+    }
+  }
+
+  // ============================================================================
+  // GET_ANNOTATION_CATEGORIES - List available annotation categories
+  // ============================================================================
+  else if (msg.type === 'GET_ANNOTATION_CATEGORIES') {
+    try {
+      console.log('🌉 [Desktop Bridge] Fetching annotation categories');
+
+      var categories = await figma.annotations.getAnnotationCategoriesAsync();
+      var result = categories.map(function(c) { return { id: c.id, name: c.name }; });
+
+      console.log('🌉 [Desktop Bridge] Found ' + result.length + ' annotation categories');
+
+      figma.ui.postMessage({
+        type: 'GET_ANNOTATION_CATEGORIES_RESULT',
+        requestId: msg.requestId,
+        success: true,
+        data: { categories: result }
+      });
+
+    } catch (error) {
+      var errorMsg = error && error.message ? error.message : String(error);
+      console.error('🌉 [Desktop Bridge] Get annotation categories error:', errorMsg);
+      figma.ui.postMessage({
+        type: 'GET_ANNOTATION_CATEGORIES_RESULT',
+        requestId: msg.requestId,
+        success: false,
+        error: errorMsg
+      });
+    }
+  }
+
   // ============================================================================
   // ADD_COMPONENT_PROPERTY - Add property to component
   // ============================================================================
@@ -2085,9 +2888,107 @@ figma.ui.onmessage = async (msg) => {
         throw new Error('Node type ' + node.type + ' does not support export');
       }
 
-      // Configure export settings
+      // Configure export settings — AI-optimized defaults (PNG 1x)
       var format = msg.format || 'PNG';
-      var scale = msg.scale || 2;
+      var scale = msg.scale || 1;
+
+      // AI vision cap: Claude API resizes images to 1568px on the longest side
+      // before processing, so exporting larger just wastes bandwidth and tokens.
+      var AI_MAX_DIMENSION = 1568;
+      var nodeWidth = 0;
+      var nodeHeight = 0;
+
+      if (node.type === 'PAGE') {
+        // Pages don't have fixed dimensions — calculate from visible children
+        var minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
+        for (var i = 0; i < node.children.length; i++) {
+          var child = node.children[i];
+          if (child.visible !== false && 'absoluteBoundingBox' in child && child.absoluteBoundingBox) {
+            var bb = child.absoluteBoundingBox;
+            minX = Math.min(minX, bb.x);
+            minY = Math.min(minY, bb.y);
+            maxX = Math.max(maxX, bb.x + bb.width);
+            maxY = Math.max(maxY, bb.y + bb.height);
+          }
+        }
+        if (minX !== Infinity) {
+          nodeWidth = maxX - minX;
+          nodeHeight = maxY - minY;
+        }
+      } else if ('width' in node && 'height' in node) {
+        nodeWidth = node.width;
+        nodeHeight = node.height;
+      }
+
+      // Cap scale so the longest exported side doesn't exceed the AI processing ceiling
+      if (nodeWidth > 0 && nodeHeight > 0) {
+        var longestSide = Math.max(nodeWidth, nodeHeight);
+        var exportedLongest = longestSide * scale;
+        if (exportedLongest > AI_MAX_DIMENSION) {
+          var cappedScale = AI_MAX_DIMENSION / longestSide;
+          console.log('🌉 [Desktop Bridge] Capping scale from', scale, 'to', cappedScale.toFixed(3),
+            '(node ' + Math.round(longestSide) + 'px, cap ' + AI_MAX_DIMENSION + 'px)');
+          scale = cappedScale;
+        }
+      }
+
+      // Analyze node content to recommend optimal format
+      var imageCount = 0;
+      var gradientCount = 0;
+      var textCount = 0;
+      var vectorCount = 0;
+      var maxDepth = 3; // Don't recurse too deep — top-level composition is enough
+
+      function analyzeContent(n, depth) {
+        if (depth > maxDepth) return;
+        if (n.type === 'TEXT') { textCount++; return; }
+        if (n.type === 'VECTOR' || n.type === 'LINE' || n.type === 'STAR' ||
+            n.type === 'POLYGON' || n.type === 'ELLIPSE' || n.type === 'BOOLEAN_OPERATION') {
+          vectorCount++; return;
+        }
+        // Check fills for images and gradients
+        if ('fills' in n && Array.isArray(n.fills)) {
+          for (var f = 0; f < n.fills.length; f++) {
+            var fill = n.fills[f];
+            if (fill.visible === false) continue;
+            if (fill.type === 'IMAGE') imageCount++;
+            if (fill.type === 'GRADIENT_LINEAR' || fill.type === 'GRADIENT_RADIAL' ||
+                fill.type === 'GRADIENT_ANGULAR' || fill.type === 'GRADIENT_DIAMOND') gradientCount++;
+          }
+        }
+        // Recurse into children
+        if ('children' in n) {
+          for (var c = 0; c < n.children.length; c++) {
+            if (n.children[c].visible !== false) {
+              analyzeContent(n.children[c], depth + 1);
+            }
+          }
+        }
+      }
+      analyzeContent(node, 0);
+
+      var totalElements = imageCount + gradientCount + textCount + vectorCount;
+      var photoHeavy = totalElements > 0 && (imageCount + gradientCount) / totalElements > 0.5;
+      var adviceParts = [];
+
+      // Format advice
+      if (photoHeavy) {
+        adviceParts.push('Image/gradient-heavy content — try format: "JPG" for smaller file.');
+      }
+
+      // Scale capping advice
+      if (scale < (msg.scale || 1)) {
+        adviceParts.push('Scale capped from ' + (msg.scale || 1) + 'x to ' +
+          scale.toFixed(2) + 'x (AI vision max: 1568px).');
+      }
+
+      // Scope advice for full-page captures with heavy downscaling
+      if (node.type === 'PAGE' && scale < 0.5) {
+        adviceParts.push('Full-page capture at ' + scale.toFixed(2) +
+          'x — text may be unreadable. Pass a nodeId to target a specific frame or component.');
+      }
+
+      var formatAdvice = adviceParts.join(' ');
 
       var exportSettings = {
         format: format,
@@ -2106,7 +3007,7 @@ figma.ui.onmessage = async (msg) => {
         bounds = node.absoluteBoundingBox;
       }
 
-      console.log('🌉 [Desktop Bridge] Screenshot captured:', bytes.length, 'bytes');
+      console.log('🌉 [Desktop Bridge] Screenshot captured:', bytes.length, 'bytes (' + format + ' @ ' + scale.toFixed(2) + 'x)');
 
       figma.ui.postMessage({
         type: 'CAPTURE_SCREENSHOT_RESULT',
@@ -2122,7 +3023,8 @@ figma.ui.onmessage = async (msg) => {
             name: node.name,
             type: node.type
           },
-          bounds: bounds
+          bounds: bounds,
+          formatAdvice: formatAdvice
         }
       });