@atezer/figma-mcp-bridge 1.7.30 → 1.9.1

package/f-mcp-plugin/code.js

@@ -4,6 +4,10 @@
 // Uses postMessage to communicate with UI, bypassing worker sandbox limitations
 // Puppeteer can access UI iframe's window context to retrieve data
 
+// v1.8.0+: Plugin version reported in WebSocket "ready" handshake.
+// Keep in sync with package.json and src/core/version.ts.
+var FMCP_PLUGIN_VERSION = '1.8.2';
+
 // Console log buffer for figma_get_console_logs (no CDP)
 var __consoleLogBuffer = [];
 var __consoleLogLimit = 200;
@@ -1091,19 +1095,22 @@ figma.ui.onmessage = async (msg) => {
           height: node.height
         };
 
-        // Get property definitions for non-variant components
+        // Get property definitions for non-variant components (capped at MAX_PROPERTIES)
         if (!isPartOfSet && node.componentPropertyDefinitions) {
           data.properties = [];
           var propDefs = node.componentPropertyDefinitions;
-          for (var propName in propDefs) {
-            if (propDefs.hasOwnProperty(propName)) {
-              var propDef = propDefs[propName];
-              data.properties.push({
-                name: propName,
-                type: propDef.type,
-                defaultValue: propDef.defaultValue
-              });
-            }
+          var propDefKeys = Object.keys(propDefs);
+          if (propDefKeys.length > MAX_PROPERTIES) {
+            propDefKeys = propDefKeys.slice(0, MAX_PROPERTIES);
+          }
+          for (var pi = 0; pi < propDefKeys.length; pi++) {
+            var propName = propDefKeys[pi];
+            var propDef = propDefs[propName];
+            data.properties.push({
+              name: propName,
+              type: propDef.type,
+              defaultValue: propDef.defaultValue
+            });
           }
         }
 
@@ -1111,13 +1118,16 @@ figma.ui.onmessage = async (msg) => {
       }
 
       // Helper to extract component set data with all variants
+      var MAX_VARIANTS = 50;
       function extractComponentSetData(node) {
         var variantAxes = {};
         var variants = [];
+        var totalChildCount = node.children ? node.children.length : 0;
 
-        // Parse variant properties from children names
-        if (node.children) {
-          node.children.forEach(function(child) {
+        // Parse variant properties from children names (capped at MAX_VARIANTS to prevent bridge timeout)
+        var processChildren = (totalChildCount <= MAX_VARIANTS) ? node.children : (node.children ? node.children.slice(0, MAX_VARIANTS) : []);
+        if (processChildren) {
+          processChildren.forEach(function(child) {
             if (child.type === 'COMPONENT') {
               // Parse variant name (e.g., "Size=md, State=default")
               var variantProps = {};
@@ -1163,6 +1173,21 @@ figma.ui.onmessage = async (msg) => {
           }
         }
 
+        var MAX_PROPERTIES = 100;
+        var propList = [];
+        if (node.componentPropertyDefinitions) {
+          var allPropKeys = Object.keys(node.componentPropertyDefinitions);
+          var propKeys = allPropKeys.length <= MAX_PROPERTIES ? allPropKeys : allPropKeys.slice(0, MAX_PROPERTIES);
+          propList = propKeys.map(function(propName) {
+            var propDef = node.componentPropertyDefinitions[propName];
+            return {
+              name: propName,
+              type: propDef.type,
+              defaultValue: propDef.defaultValue
+            };
+          });
+        }
+
         return {
           key: node.key,
           nodeId: node.id,
@@ -1172,14 +1197,9 @@ figma.ui.onmessage = async (msg) => {
           variantAxes: axes,
           variants: variants,
           defaultVariant: variants.length > 0 ? variants[0] : null,
-          properties: node.componentPropertyDefinitions ? Object.keys(node.componentPropertyDefinitions).map(function(propName) {
-            var propDef = node.componentPropertyDefinitions[propName];
-            return {
-              name: propName,
-              type: propDef.type,
-              defaultValue: propDef.defaultValue
-            };
-          }) : []
+          properties: propList,
+          _totalVariantCount: totalChildCount,
+          _truncated: totalChildCount > MAX_VARIANTS
         };
       }
 
@@ -1304,7 +1324,10 @@ figma.ui.onmessage = async (msg) => {
       if (assetTypes.indexOf('components') >= 0) {
         var components = [];
         var componentSets = [];
+        var libraryComponents = [];  // v1.8.0+: discovered from existing instances
+        var seenLibKeys = {};         // dedupe library component/set keys
         var hitLimit = false;
+
         function extractComponentData(node, fromSet) {
           return {
             id: node.id,
@@ -1323,6 +1346,45 @@ figma.ui.onmessage = async (msg) => {
             variantCount: node.children ? node.children.length : 0
           };
         }
+
+        // v1.8.0: Library components discovered from INSTANCE nodes via mainComponent.key.
+        // The Figma Plugin API does not expose a list-library-components endpoint,
+        // so we walk existing instances in the file and collect their library keys.
+        // This finds SUI/DS components that have been used at least once in the file.
+        async function extractFromInstance(inst) {
+          if (libraryComponents.length >= limit) return;
+          try {
+            var mc = inst.mainComponent || (inst.getMainComponentAsync ? await inst.getMainComponentAsync() : null);
+            if (!mc) return;
+            var isSet = mc.parent && mc.parent.type === 'COMPONENT_SET';
+            var node = isSet ? mc.parent : mc;
+            var key = node.key;
+            if (!key || seenLibKeys[key]) return;
+            // Filter: prefer remote (library) components — local file components are already
+            // captured by the local-component scan below.
+            var isRemote = !!node.remote;
+            if (!isRemote) return;
+            var nname = (node.name || '').toLowerCase();
+            var ndesc = (node.description || '').toLowerCase();
+            var match = !q || nname.indexOf(q) >= 0 || ndesc.indexOf(q) >= 0;
+            if (!match) return;
+            seenLibKeys[key] = true;
+            libraryComponents.push({
+              name: node.name,
+              key: key,
+              description: node.description || null,
+              type: isSet ? 'COMPONENT_SET' : 'COMPONENT',
+              variantCount: isSet && node.children ? node.children.length : null,
+              libraryName: (node.documentationLinks && node.documentationLinks[0]) || null,
+              source: 'instance-discovery',
+              sampleInstanceId: inst.id,
+              sampleVariantName: isSet ? mc.name : null
+            });
+          } catch (e) {
+            // Some library components may not be importable — skip silently
+          }
+        }
+
         async function processNodeList(nodes) {
           for (var i = 0; i < nodes.length && !hitLimit; i++) {
             if (components.length + componentSets.length >= limit) {
@@ -1344,12 +1406,23 @@ figma.ui.onmessage = async (msg) => {
             }
           }
         }
+
+        async function scanInstancesOnPage(page) {
+          if (!page || !page.findAllWithCriteria) return;
+          var instances = page.findAllWithCriteria({ types: ['INSTANCE'] }) || [];
+          for (var i = 0; i < instances.length && libraryComponents.length < limit; i++) {
+            await extractFromInstance(instances[i]);
+          }
+        }
+
         if (currentPageOnly) {
           var page = figma.currentPage;
           if (page) {
             if (page.loadAsync) await page.loadAsync();
             var pn = page.findAllWithCriteria ? page.findAllWithCriteria({ types: ['COMPONENT', 'COMPONENT_SET'] }) : [];
             await processNodeList(pn);
+            // v1.8.0: also scan instances on current page for library component keys
+            await scanInstancesOnPage(page);
           }
         } else {
           await figma.loadAllPagesAsync();
@@ -1359,13 +1432,21 @@ figma.ui.onmessage = async (msg) => {
             if (pg && pg.loadAsync) await pg.loadAsync();
             var pageNodes = pg && pg.findAllWithCriteria ? pg.findAllWithCriteria({ types: ['COMPONENT', 'COMPONENT_SET'] }) : [];
             await processNodeList(pageNodes);
+            // v1.8.0: scan instances across all pages
+            await scanInstancesOnPage(pg);
           }
         }
         out.components = components;
         out.componentSets = componentSets;
+        out.libraryComponents = libraryComponents;  // v1.8.0+
         out.truncatedByLimit = hitLimit;
         out.currentPageOnly = currentPageOnly;
-        out.notes.push('Components are from the current file (local + published keys via component.key). Full remote catalog may require REST API.');
+        if (libraryComponents.length > 0) {
+          out.notes.push('libraryComponents: discovered ' + libraryComponents.length + ' remote library component(s) via existing instance scan. Use these keys with figma_instantiate_component.');
+        } else if (assetTypes.indexOf('components') >= 0) {
+          out.notes.push('No library components found via instance scan. Either no DS instances exist in this file yet, or all instances are local. Hint: place one DS instance manually first, then re-run.');
+        }
+        out.notes.push('Components are from the current file (local + published keys via component.key).');
       }
 
       figma.ui.postMessage({
@@ -2105,6 +2186,399 @@ figma.ui.onmessage = async (msg) => {
     }
   }
 
+  // ============================================================================
+  // CLONE_SCREEN_TO_DEVICE (v1.8.1+) - HIGH-LEVEL: Clone screen and adapt to device
+  //
+  // Clones the source node, preserves library instances + bound variables,
+  // resizes the root to target dimensions (handling auto-layout correctly),
+  // positions the clone (auto or explicit), and returns the new node ID.
+  // ============================================================================
+  else if (msg.type === 'CLONE_SCREEN_TO_DEVICE') {
+    // v1.8.2: Track clonedNode outside try so cleanup can run on error
+    var clonedNode = null;
+    try {
+      console.log('🌉 [F-MCP] Clone screen to device:', msg.sourceNodeId, '→', msg.targetDeviceName);
+
+      var sourceNode = await figma.getNodeByIdAsync(msg.sourceNodeId);
+      if (!sourceNode) throw new Error('Source node not found: ' + msg.sourceNodeId);
+      if (!('clone' in sourceNode)) {
+        throw new Error('Source node type ' + sourceNode.type + ' does not support cloning');
+      }
+
+      // v1.8.2: Warn if source is too large (will likely timeout)
+      var sourceChildCount = 0;
+      if ('children' in sourceNode && sourceNode.children) {
+        sourceChildCount = sourceNode.children.length;
+      }
+      if (sourceChildCount > 20) {
+        console.warn('🌉 [F-MCP] Source has ' + sourceChildCount + ' children — clone may be slow.');
+      }
+
+      // Ensure the page containing the source is loaded (dynamic-page mode)
+      var sourcePage = sourceNode;
+      while (sourcePage.parent && sourcePage.parent.type !== 'PAGE' && sourcePage.parent.type !== 'DOCUMENT') {
+        sourcePage = sourcePage.parent;
+      }
+      if (sourcePage.parent && sourcePage.parent.type === 'PAGE' && sourcePage.parent.loadAsync) {
+        await sourcePage.parent.loadAsync();
+      }
+
+      // Clone — Figma auto-places at (original.x+10, original.y+10) in same parent
+      clonedNode = sourceNode.clone();
+      console.log('🌉 [F-MCP] Cloned:', clonedNode.id);
+
+      // Reparent if requested
+      if (msg.targetParentId) {
+        var targetParent = await figma.getNodeByIdAsync(msg.targetParentId);
+        if (targetParent && 'appendChild' in targetParent) {
+          targetParent.appendChild(clonedNode);
+        } else {
+          console.warn('🌉 [F-MCP] Target parent not found or cannot append:', msg.targetParentId);
+        }
+      }
+
+      // Explicit position — or auto-place to the right of the source
+      if (msg.position) {
+        clonedNode.x = msg.position.x;
+        clonedNode.y = msg.position.y;
+      } else {
+        // Auto: place to the right of source + 100px gap
+        if ('x' in sourceNode && 'width' in sourceNode) {
+          clonedNode.x = sourceNode.x + sourceNode.width + 100;
+          clonedNode.y = sourceNode.y;
+        }
+      }
+
+      // Resize to target device dimensions
+      // For auto-layout frames, we must switch sizingMode to FIXED first,
+      // otherwise resize() is a no-op because the frame "hugs" its content.
+      var wasHuggingX = false;
+      var wasHuggingY = false;
+      if ('layoutMode' in clonedNode && clonedNode.layoutMode !== 'NONE') {
+        if (clonedNode.primaryAxisSizingMode === 'AUTO') {
+          wasHuggingX = clonedNode.layoutMode === 'HORIZONTAL';
+          wasHuggingY = clonedNode.layoutMode === 'VERTICAL';
+          clonedNode.primaryAxisSizingMode = 'FIXED';
+        }
+        if (clonedNode.counterAxisSizingMode === 'AUTO') {
+          if (clonedNode.layoutMode === 'HORIZONTAL') wasHuggingY = true;
+          if (clonedNode.layoutMode === 'VERTICAL') wasHuggingX = true;
+          clonedNode.counterAxisSizingMode = 'FIXED';
+        }
+      }
+
+      if ('resize' in clonedNode) {
+        try {
+          clonedNode.resize(msg.targetWidth, msg.targetHeight);
+        } catch (resizeErr) {
+          console.warn('🌉 [F-MCP] Resize error (may be a constraint):', resizeErr.message);
+        }
+      }
+
+      // Name the clone
+      if (msg.newName) {
+        clonedNode.name = msg.newName;
+      } else if ('name' in clonedNode) {
+        clonedNode.name = sourceNode.name + ' — ' + msg.targetDeviceName;
+      }
+
+      // Count preserved elements for reporting
+      var instanceCount = 0;
+      var libraryInstanceCount = 0;
+      var boundVarCount = 0;
+      if ('findAllWithCriteria' in clonedNode) {
+        try {
+          var instances = clonedNode.findAllWithCriteria({ types: ['INSTANCE'] }) || [];
+          instanceCount = instances.length;
+          for (var i = 0; i < instances.length; i++) {
+            var inst = instances[i];
+            try {
+              var mc = inst.mainComponent || (inst.getMainComponentAsync ? await inst.getMainComponentAsync() : null);
+              var remote = mc && (mc.remote || (mc.parent && mc.parent.remote));
+              if (remote) libraryInstanceCount++;
+            } catch (e) { /* skip */ }
+          }
+        } catch (e) { /* skip */ }
+      }
+      // Walk the tree counting boundVariables (iterative, stack-safe)
+      var stack = [clonedNode];
+      var totalNodes = 0;
+      while (stack.length > 0) {
+        var n = stack.pop();
+        totalNodes++;
+        if (n && n.boundVariables && Object.keys(n.boundVariables).length > 0) {
+          boundVarCount++;
+        }
+        if (n && n.children) {
+          for (var ci = 0; ci < n.children.length; ci++) stack.push(n.children[ci]);
+        }
+      }
+
+      figma.ui.postMessage({
+        type: 'CLONE_SCREEN_TO_DEVICE_RESULT',
+        requestId: msg.requestId,
+        success: true,
+        clone: {
+          id: clonedNode.id,
+          name: clonedNode.name,
+          x: clonedNode.x,
+          y: clonedNode.y,
+          width: clonedNode.width,
+          height: clonedNode.height,
+          layoutMode: clonedNode.layoutMode || 'NONE',
+        },
+        source: {
+          id: sourceNode.id,
+          name: sourceNode.name,
+        },
+        targetDevice: {
+          name: msg.targetDeviceName,
+          width: msg.targetWidth,
+          height: msg.targetHeight,
+        },
+        preserved: {
+          totalNodes: totalNodes,
+          instanceCount: instanceCount,
+          libraryInstanceCount: libraryInstanceCount,
+          boundVariableCount: boundVarCount,
+        },
+      });
+    } catch (error) {
+      var errorMsg = error && error.message ? error.message : String(error);
+      console.error('🌉 [F-MCP] Clone to device error:', errorMsg);
+
+      // v1.8.2: Orphan cleanup — remove half-finished clone to prevent duplicates
+      var cleanedUp = false;
+      if (clonedNode) {
+        try {
+          clonedNode.remove();
+          cleanedUp = true;
+          console.log('🌉 [F-MCP] Cleaned up orphan clone after error');
+        } catch (cleanupErr) {
+          console.warn('🌉 [F-MCP] Orphan cleanup failed:', cleanupErr.message);
+        }
+      }
+
+      figma.ui.postMessage({
+        type: 'CLONE_SCREEN_TO_DEVICE_RESULT',
+        requestId: msg.requestId,
+        success: false,
+        error: errorMsg,
+        orphanCleanedUp: cleanedUp,
+      });
+    }
+  }
+
+  // ============================================================================
+  // VALIDATE_SCREEN (v1.8.1+) - DS compliance audit
+  //
+  // Walks a node tree (iterative, stack-safe) and computes 3 metrics:
+  //   - instanceCoverage    — % of nodes that are library instances
+  //   - autoLayoutCoverage  — % of frames with layoutMode != NONE
+  //   - tokenBindingCoverage — % of stylable nodes with boundVariables
+  // Returns aggregate score (weighted 40/30/30) + violations list.
+  // Read-only — does not mutate the file.
+  // ============================================================================
+  else if (msg.type === 'VALIDATE_SCREEN') {
+    try {
+      console.log('🌉 [F-MCP] Validate screen:', msg.nodeId);
+
+      var rootNode = await figma.getNodeByIdAsync(msg.nodeId);
+      if (!rootNode) throw new Error('Node not found: ' + msg.nodeId);
+
+      // v1.8.2 OPTIMIZATION: Two-pass validation to avoid serial await on getMainComponentAsync
+      // Pass 1: iterative walk, collect node tree + instance list (no async calls)
+      // Pass 2: Promise.all on getMainComponentAsync for all instances in parallel
+      // This cuts 100+ node validation from ~60s to ~5s.
+
+      // Iterative tree walk (stack-safe for deep trees up to 10,000+ nodes)
+      var metrics = {
+        totalNodes: 0,
+        frameNodes: 0,
+        autoLayoutFrames: 0,
+        instanceNodes: 0,
+        libraryInstanceNodes: 0,
+        stylableNodes: 0,
+        nodesWithBindings: 0,
+      };
+      var violations = [];
+      var maxViolations = 20; // cap to keep response small
+      var instanceNodesList = []; // v1.8.2: collect for batch resolve
+
+      var walkStack = [rootNode];
+      var visited = 0;
+      var maxVisit = 5000; // safety cap
+
+      while (walkStack.length > 0 && visited < maxVisit) {
+        var node = walkStack.pop();
+        visited++;
+        metrics.totalNodes++;
+
+        // Instance check — DEFER async resolve to Pass 2
+        if (node.type === 'INSTANCE') {
+          metrics.instanceNodes++;
+          // Try sync mainComponent first (works in most cases, free)
+          try {
+            var syncMc = node.mainComponent;
+            if (syncMc) {
+              var syncIsRemote = syncMc.remote || (syncMc.parent && syncMc.parent.remote);
+              if (syncIsRemote) metrics.libraryInstanceNodes++;
+            } else {
+              // Defer to Pass 2 if sync access unavailable
+              instanceNodesList.push(node);
+            }
+          } catch (e) {
+            instanceNodesList.push(node);
+          }
+        }
+
+        // Frame auto-layout check
+        if (node.type === 'FRAME' || node.type === 'COMPONENT' || node.type === 'COMPONENT_SET' || node.type === 'INSTANCE') {
+          metrics.frameNodes++;
+          if ('layoutMode' in node && node.layoutMode && node.layoutMode !== 'NONE') {
+            metrics.autoLayoutFrames++;
+          } else if ((node.type === 'FRAME' || node.type === 'COMPONENT') && violations.length < maxViolations) {
+            violations.push({
+              nodeId: node.id,
+              nodeName: node.name,
+              category: 'NO_AUTO_LAYOUT',
+              severity: 'HIGH',
+              message: "Frame '" + (node.name || node.id) + "' has no auto-layout (layoutMode=NONE). Not responsive.",
+            });
+          }
+        }
+
+        // Token binding check (any node with fills/strokes/effects that can have bound variables)
+        if ('fills' in node || 'strokes' in node || 'effects' in node) {
+          metrics.stylableNodes++;
+          var hasBindings = false;
+          try {
+            if (node.boundVariables && Object.keys(node.boundVariables).length > 0) {
+              hasBindings = true;
+            }
+          } catch (e) { /* skip */ }
+          if (hasBindings) {
+            metrics.nodesWithBindings++;
+          } else if (node.type !== 'INSTANCE' && violations.length < maxViolations) {
+            // Skip instances — their bindings come from the main component
+            var hasFills = false;
+            try {
+              if (Array.isArray(node.fills) && node.fills.length > 0 && node.fills[0].type !== 'IMAGE') {
+                hasFills = true;
+              }
+            } catch (e) { /* skip */ }
+            if (hasFills) {
+              violations.push({
+                nodeId: node.id,
+                nodeName: node.name,
+                category: 'HARDCODED_FILL',
+                severity: 'HIGH',
+                message: "Node '" + (node.name || node.id) + "' has hardcoded fills (no boundVariables). Bind to DS token.",
+              });
+            }
+          }
+        }
+
+        // Push children
+        if (node.children) {
+          for (var ci = 0; ci < node.children.length; ci++) {
+            walkStack.push(node.children[ci]);
+          }
+        }
+      }
+
+      // v1.8.2 Pass 2: Batch-resolve deferred instance mainComponents via Promise.all
+      // This is ~10x faster than serial await in the walk loop above
+      if (instanceNodesList.length > 0 && typeof Promise.all === 'function') {
+        try {
+          var mcPromises = instanceNodesList.map(function (inst) {
+            if (inst.getMainComponentAsync) {
+              return inst.getMainComponentAsync().catch(function () { return null; });
+            }
+            return Promise.resolve(null);
+          });
+          var mcResults = await Promise.all(mcPromises);
+          for (var mi = 0; mi < mcResults.length; mi++) {
+            var mc = mcResults[mi];
+            if (mc) {
+              var isRemote = mc.remote || (mc.parent && mc.parent.remote);
+              if (isRemote) metrics.libraryInstanceNodes++;
+            }
+          }
+        } catch (batchErr) {
+          console.warn('🌉 [F-MCP] Pass 2 batch mainComponent resolve failed:', batchErr.message);
+        }
+      }
+
+      // Compute scores (percentages)
+      var instanceCoverage = metrics.totalNodes > 0
+        ? Math.round((metrics.libraryInstanceNodes / Math.max(1, metrics.totalNodes)) * 100)
+        : 0;
+      var autoLayoutCoverage = metrics.frameNodes > 0
+        ? Math.round((metrics.autoLayoutFrames / metrics.frameNodes) * 100)
+        : 100;
+      var tokenBindingCoverage = metrics.stylableNodes > 0
+        ? Math.round((metrics.nodesWithBindings / metrics.stylableNodes) * 100)
+        : 100;
+
+      // Weighted aggregate (instance 40%, binding 30%, layout 30%)
+      // Note: instanceCoverage is vs total nodes which is lenient — library components
+      // contain many internal nodes that aren't instances themselves. We cap the
+      // library instance ratio so single instances don't drag the score too low.
+      // If at least 1 library instance exists, give partial credit up to 70 for this axis.
+      var normalizedInstanceScore = metrics.libraryInstanceNodes === 0
+        ? 0
+        : Math.min(100, Math.max(30, instanceCoverage * 3));
+      var score = Math.round(
+        (normalizedInstanceScore * 0.4) +
+        (tokenBindingCoverage * 0.3) +
+        (autoLayoutCoverage * 0.3)
+      );
+
+      var minScore = typeof msg.minScore === 'number' ? msg.minScore : 80;
+      var passed = score >= minScore;
+
+      var recommendation = passed
+        ? 'Score ' + score + '/100 passed minimum ' + minScore + '. Screen is DS-compliant.'
+        : 'Score ' + score + '/100 is below minimum ' + minScore + '. Consider deleting this screen and rebuilding using ' +
+          'DS components (figma_instantiate_component) and token bindings (figma_bind_variable).';
+
+      figma.ui.postMessage({
+        type: 'VALIDATE_SCREEN_RESULT',
+        requestId: msg.requestId,
+        success: true,
+        score: score,
+        passed: passed,
+        minScore: minScore,
+        breakdown: {
+          instanceCoverage: instanceCoverage,
+          libraryInstanceCount: metrics.libraryInstanceNodes,
+          totalInstances: metrics.instanceNodes,
+          autoLayoutCoverage: autoLayoutCoverage,
+          autoLayoutFrames: metrics.autoLayoutFrames,
+          totalFrames: metrics.frameNodes,
+          tokenBindingCoverage: tokenBindingCoverage,
+          nodesWithBindings: metrics.nodesWithBindings,
+          totalStylable: metrics.stylableNodes,
+        },
+        violations: violations,
+        violationCount: violations.length,
+        violationCapped: violations.length >= maxViolations,
+        totalNodesWalked: visited,
+        recommendation: recommendation,
+      });
+    } catch (error) {
+      var errorMsg = error && error.message ? error.message : String(error);
+      console.error('🌉 [F-MCP] Validate screen error:', errorMsg);
+      figma.ui.postMessage({
+        type: 'VALIDATE_SCREEN_RESULT',
+        requestId: msg.requestId,
+        success: false,
+        error: errorMsg,
+      });
+    }
+  }
+
   // ============================================================================
   // DELETE_NODE - Delete a node
   // ============================================================================
@@ -2353,14 +2827,21 @@ figma.ui.onmessage = async (msg) => {
         throw new Error('Node type ' + node.type + ' does not support export');
       }
 
-      // Configure export settings
-      var format = msg.format || 'PNG';
-      var scale = msg.scale || 2;
+      // v1.8.0: Default JPG@1x q70 for context safety. Plugin reads msg.format,
+      // msg.scale, msg.jpegQuality from the request payload (passed through
+      // captureScreenshot connector → bridge → here).
+      var format = (msg.format || 'JPG').toUpperCase();
+      var scale = msg.scale != null ? msg.scale : 1;
+      var jpegQuality = msg.jpegQuality != null ? msg.jpegQuality : 70;
 
       var exportSettings = {
         format: format,
         constraint: { type: 'SCALE', value: scale }
       };
+      // JPG quality (Figma Plugin API supports 'quality' for ExportSettingsImage)
+      if (format === 'JPG') {
+        exportSettings.quality = jpegQuality;
+      }
 
       // Export the node
       var bytes = await node.exportAsync(exportSettings);
@@ -2374,7 +2855,7 @@ figma.ui.onmessage = async (msg) => {
         bounds = node.absoluteBoundingBox;
       }
 
-      console.log('🌉 [F-MCP ATezer Bridge] Screenshot captured:', bytes.length, 'bytes');
+      console.log('🌉 [F-MCP ATezer Bridge] Screenshot captured:', bytes.length, 'bytes (' + format + ' @' + scale + 'x)');
 
       figma.ui.postMessage({
         type: 'CAPTURE_SCREENSHOT_RESULT',
@@ -2384,6 +2865,7 @@ figma.ui.onmessage = async (msg) => {
           base64: base64,
           format: format,
           scale: scale,
+          jpegQuality: format === 'JPG' ? jpegQuality : null,
           byteLength: bytes.length,
           node: {
             id: node.id,
@@ -2584,7 +3066,8 @@ figma.ui.onmessage = async (msg) => {
     try {
       await figma.loadAllPagesAsync();
 
-      var depth = Math.min(Math.max(msg.depth || 1, 0), 3);
+      // v1.8.0: Use != null instead of || so depth=0 is preserved (|| would rewrite 0 to default).
+      var depth = Math.min(Math.max(msg.depth != null ? msg.depth : 1, 0), 3);
       var verbosity = msg.verbosity || 'summary';
       var opts = {
         verbosity: verbosity,
@@ -2643,8 +3126,10 @@ figma.ui.onmessage = async (msg) => {
             error: 'Node not found: ' + nodeId
           });
         } else {
-          var depthNode = Math.min(Math.max(msg.depth || 2, 0), 3);
-          var verbosityNode = msg.verbosity || 'standard';
+          // v1.8.0: Context-safe defaults — depth=1, verbosity="summary" (was depth=2, verbosity="standard").
+          // Use != null instead of || so depth=0 is preserved.
+          var depthNode = Math.min(Math.max(msg.depth != null ? msg.depth : 1, 0), 3);
+          var verbosityNode = msg.verbosity || 'summary';
           var optsNode = {
             verbosity: verbosityNode,
             includeLayout: msg.includeLayout === true,