@atezer/figma-mcp-bridge 1.9.4 → 1.9.6

package/f-mcp-plugin/code.js

@@ -6,7 +6,185 @@
 
 // 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.9.4';
+var FMCP_PLUGIN_VERSION = '1.9.6';
+
+/**
+ * v1.9.6: Post-execute scan — figma_execute sonrasında oluşturulan node'ları
+ * otomatik tarayıp unbound fill/padding/radius/text-style tespit eder.
+ * Skill direktifi "return { createdNodeIds: [...] }" diyor — plugin bunu okuyup
+ * subtree'yi tarar. Violations varsa response'a _postExecuteScan field'ı eklenir,
+ * server bunu _DESIGN_SYSTEM_VIOLATIONS_BLOCKING'e dönüştürür.
+ */
+async function postExecuteScan(result) {
+  var nodeIds = [];
+  if (result && typeof result === 'object') {
+    if (Array.isArray(result.createdNodeIds)) nodeIds = result.createdNodeIds;
+    else if (Array.isArray(result.nodeIds)) nodeIds = result.nodeIds;
+    else if (Array.isArray(result.ids)) nodeIds = result.ids;
+    else if (typeof result.frameId === 'string') nodeIds = [result.frameId];
+    else if (typeof result.rootId === 'string') nodeIds = [result.rootId];
+    else if (typeof result.nodeId === 'string') nodeIds = [result.nodeId];
+  }
+  if (nodeIds.length === 0) return null;
+
+  var violations = [];
+  var maxViolations = 10;
+  var maxNodes = 500; // safety cap per subtree
+  var totalChecked = 0;
+
+  for (var i = 0; i < nodeIds.length && violations.length < maxViolations; i++) {
+    var root;
+    try { root = await figma.getNodeByIdAsync(nodeIds[i]); } catch (e) { continue; }
+    if (!root) continue;
+    var stack = [root];
+    var visited = 0;
+    while (stack.length > 0 && visited < maxNodes) {
+      var n = stack.pop(); visited++; totalChecked++;
+      if (!n) continue;
+
+      // Fill check (skip instances — their bindings come from main component)
+      if (Array.isArray(n.fills) && n.type !== 'INSTANCE') {
+        for (var fi = 0; fi < n.fills.length; fi++) {
+          var fl = n.fills[fi];
+          if (fl && fl.visible !== false && fl.type === 'SOLID') {
+            var fbv = n.boundVariables && n.boundVariables.fills;
+            if (!(fbv && (Array.isArray(fbv) ? fbv[fi] : true)) && violations.length < maxViolations) {
+              violations.push({ nodeId: n.id, nodeName: n.name, category: 'UNBOUND_FILL', hint: 'setBoundVariableForPaint cagrisi eksik' });
+            }
+          }
+        }
+      }
+
+      if ((n.type === 'FRAME' || n.type === 'COMPONENT') && n.boundVariables !== undefined) {
+        var padProps = ['paddingTop', 'paddingBottom', 'paddingLeft', 'paddingRight'];
+        for (var j = 0; j < padProps.length && violations.length < maxViolations; j++) {
+          if (typeof n[padProps[j]] === 'number' && n[padProps[j]] > 0 && !(n.boundVariables && n.boundVariables[padProps[j]])) {
+            violations.push({ nodeId: n.id, nodeName: n.name, category: 'UNBOUND_PADDING', prop: padProps[j], value: n[padProps[j]] });
+          }
+        }
+        var radProps = ['cornerRadius', 'topLeftRadius', 'topRightRadius', 'bottomLeftRadius', 'bottomRightRadius'];
+        for (var k = 0; k < radProps.length && violations.length < maxViolations; k++) {
+          if (typeof n[radProps[k]] === 'number' && n[radProps[k]] > 0 && !(n.boundVariables && n.boundVariables[radProps[k]])) {
+            violations.push({ nodeId: n.id, nodeName: n.name, category: 'UNBOUND_RADIUS', prop: radProps[k], value: n[radProps[k]] });
+          }
+        }
+        if (typeof n.itemSpacing === 'number' && n.itemSpacing > 0 && !(n.boundVariables && n.boundVariables.itemSpacing) && violations.length < maxViolations) {
+          violations.push({ nodeId: n.id, nodeName: n.name, category: 'UNBOUND_ITEMSPACING', value: n.itemSpacing });
+        }
+      }
+
+      if (n.type === 'TEXT' && !(n.textStyleId && typeof n.textStyleId === 'string' && n.textStyleId !== '') && violations.length < maxViolations) {
+        violations.push({ nodeId: n.id, nodeName: n.name, category: 'UNBOUND_TEXTSTYLE', sample: String(n.characters || '').slice(0, 30) });
+      }
+
+      if (n.children) {
+        for (var ci = 0; ci < n.children.length; ci++) stack.push(n.children[ci]);
+      }
+    }
+  }
+
+  return {
+    scanned: true,
+    rootsScanned: nodeIds.length,
+    totalChecked: totalChecked,
+    violationCount: violations.length,
+    violations: violations,
+    passed: violations.length === 0,
+    hint: violations.length > 0
+      ? '❌ v1.9.6 post-execute scan: ' + violations.length + ' unbound node tespit edildi. Kodu duzelt — her node icin setBoundVariable/setTextStyleIdAsync cagrisi eksik.'
+      : '✅ v1.9.6 post-execute scan: Tum node\'lar bound.',
+  };
+}
+
+// v1.9.5: Metadata summary builder for returnMode='summary' (screenshotsuz)
+async function buildNodeSummary(node, maxDepth) {
+  var colorUsage = {}; // role → count
+  var textRoleCount = {}; // styleId → { count, samples }
+  var unboundHexCount = 0;
+  var totalNodes = 0;
+
+  function walk(n, depth) {
+    totalNodes++;
+    // Fill bound token tracking
+    if (Array.isArray(n.fills)) {
+      for (var fi = 0; fi < n.fills.length; fi++) {
+        var fl = n.fills[fi];
+        if (fl && fl.visible !== false && fl.type === 'SOLID') {
+          var fbv = n.boundVariables && n.boundVariables.fills;
+          var bound = fbv && (Array.isArray(fbv) ? fbv[fi] : true);
+          if (bound) {
+            var role = (Array.isArray(fbv) ? fbv[fi] : fbv).id || 'unknown';
+            colorUsage[role] = (colorUsage[role] || 0) + 1;
+          } else {
+            unboundHexCount++;
+          }
+        }
+      }
+    }
+    if (n.type === 'TEXT') {
+      var styleId = n.textStyleId || 'inline';
+      if (!textRoleCount[styleId]) textRoleCount[styleId] = { count: 0, samples: [] };
+      textRoleCount[styleId].count++;
+      if (textRoleCount[styleId].samples.length < 3) {
+        textRoleCount[styleId].samples.push(String(n.characters || '').slice(0, 30));
+      }
+    }
+    if (n.children && depth < 3) { // deep walk but capped
+      for (var ci = 0; ci < n.children.length; ci++) walk(n.children[ci], depth + 1);
+    }
+  }
+
+  walk(node, 0);
+
+  function collectSections(n, depth) {
+    if (depth > maxDepth) return null;
+    var s = {
+      name: n.name,
+      type: n.type,
+      size: n.width && n.height ? Math.round(n.width) + 'x' + Math.round(n.height) : null,
+      childrenCount: n.children ? n.children.length : 0,
+    };
+    if (n.children && n.children.length > 0 && depth < maxDepth) {
+      var items = [];
+      for (var i = 0; i < n.children.length && i < 20; i++) {
+        items.push(collectSections(n.children[i], depth + 1));
+      }
+      s.children = items;
+    }
+    return s;
+  }
+
+  // Resolve variable names (best-effort)
+  var dominantColors = [];
+  var colorEntries = Object.keys(colorUsage).map(function (k) { return { role: k, usage: colorUsage[k] }; });
+  colorEntries.sort(function (a, b) { return b.usage - a.usage; });
+  for (var ci2 = 0; ci2 < Math.min(colorEntries.length, 5); ci2++) {
+    dominantColors.push({ variableId: colorEntries[ci2].role, usageCount: colorEntries[ci2].usage, bound: true });
+  }
+  if (unboundHexCount > 0) {
+    dominantColors.push({ variableId: '<hardcoded>', usageCount: unboundHexCount, bound: false });
+  }
+
+  var textRoles = [];
+  var trKeys = Object.keys(textRoleCount);
+  for (var tk = 0; tk < trKeys.length; tk++) {
+    textRoles.push({ styleId: trKeys[tk], count: textRoleCount[trKeys[tk]].count, samples: textRoleCount[trKeys[tk]].samples });
+  }
+
+  return {
+    nodeId: node.id,
+    name: node.name,
+    type: node.type,
+    dimensions: { width: Math.round(node.width || 0), height: Math.round(node.height || 0) },
+    layoutMode: node.layoutMode || 'NONE',
+    childrenCount: node.children ? node.children.length : 0,
+    totalNodes: totalNodes,
+    sections: collectSections(node, 0),
+    dominantColors: dominantColors,
+    textRoles: textRoles.slice(0, 10),
+    hint: "v1.9.5 summary: Metadata ozeti, gorsel yok. Layout karari icin yeter. Pixel dogrulama gerekirse returnMode='file' veya 'regions'.",
+  };
+}
 
 // Console log buffer for figma_get_console_logs (no CDP)
 var __consoleLogBuffer = [];
@@ -552,6 +730,17 @@ figma.ui.onmessage = async (msg) => {
         safeResult = { __serializationError: true, message: 'Result could not be serialized: ' + (serErr.message || String(serErr)), resultType: typeof result };
       }
 
+      // v1.9.6: Post-execute scan — oluşturulan node'larda unbound tespit
+      var postScan = null;
+      try {
+        postScan = await postExecuteScan(result);
+        if (postScan && postScan.violationCount > 0) {
+          console.warn('🌉 [F-MCP v1.9.6] Post-execute scan: ' + postScan.violationCount + ' unbound node detected');
+        }
+      } catch (psErr) {
+        console.warn('🌉 [F-MCP v1.9.6] Post-execute scan failed:', psErr && psErr.message ? psErr.message : String(psErr));
+      }
+
       figma.ui.postMessage({
         type: 'EXECUTE_CODE_RESULT',
         requestId: msg.requestId,
@@ -562,7 +751,8 @@ figma.ui.onmessage = async (msg) => {
         fileContext: {
           fileName: figma.root.name,
           fileKey: figma.fileKey || null
-        }
+        },
+        _postExecuteScan: postScan // v1.9.6: BLOCKING signal source for server
       });
 
     } catch (error) {
@@ -2985,64 +3175,140 @@ figma.ui.onmessage = async (msg) => {
   // ============================================================================
   else if (msg.type === 'CAPTURE_SCREENSHOT') {
     try {
-      console.log('🌉 [F-MCP ATezer Bridge] Capturing screenshot for node:', msg.nodeId);
+      console.log('🌉 [F-MCP ATezer Bridge v1.9.5] Capturing screenshot for node:', msg.nodeId, 'returnMode:', msg.returnMode);
 
       var node = msg.nodeId ? await figma.getNodeByIdAsync(msg.nodeId) : figma.currentPage;
       if (!node) {
         throw new Error('Node not found: ' + msg.nodeId);
       }
 
-      // Verify node supports export
-      if (!('exportAsync' in node)) {
-        throw new Error('Node type ' + node.type + ' does not support export');
-      }
-
-      // 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).
+      // v1.8.0: Default JPG@1x q70 for context safety.
       var format = (msg.format || 'JPG').toUpperCase();
       var scale = msg.scale != null ? msg.scale : 1;
       var jpegQuality = msg.jpegQuality != null ? msg.jpegQuality : 70;
+      // v1.9.5: returnMode (default 'file' which server translates to base64 + save)
+      var returnMode = msg.returnMode || 'base64';  // plugin default stays base64; server wraps to file
+      var regionStrategy = msg.regionStrategy || 'children';
+      var maxRegions = msg.maxRegions != null ? msg.maxRegions : 8;
 
-      var exportSettings = {
-        format: format,
-        constraint: { type: 'SCALE', value: scale }
-      };
-      // JPG quality (Figma Plugin API supports 'quality' for ExportSettingsImage)
-      if (format === 'JPG') {
-        exportSettings.quality = jpegQuality;
+      function buildExportSettings() {
+        var s = { format: format, constraint: { type: 'SCALE', value: scale } };
+        if (format === 'JPG') s.quality = jpegQuality;
+        return s;
       }
 
-      // Export the node
-      var bytes = await node.exportAsync(exportSettings);
+      // ---------- v1.9.5 MODE: summary ----------
+      // No export. Just metadata.
+      if (returnMode === 'summary') {
+        var rootSummary = await buildNodeSummary(node, /*depth*/ 2);
+        figma.ui.postMessage({
+          type: 'CAPTURE_SCREENSHOT_RESULT',
+          requestId: msg.requestId,
+          success: true,
+          mode: 'summary',
+          summary: rootSummary,
+        });
+        return;
+      }
 
-      // Convert to base64
-      var base64 = figma.base64Encode(bytes);
+      // ---------- v1.9.5 MODE: regions (children strategy) ----------
+      if (returnMode === 'regions' && regionStrategy === 'children') {
+        if (!node.children || node.children.length === 0) {
+          figma.ui.postMessage({
+            type: 'CAPTURE_SCREENSHOT_RESULT',
+            requestId: msg.requestId,
+            success: false,
+            error: "Node has no children for regions mode. Use 'file' or 'summary' instead.",
+          });
+          return;
+        }
+        var regions = [];
+        var children = node.children.slice(0, maxRegions);
+        for (var ri = 0; ri < children.length; ri++) {
+          var child = children[ri];
+          if (!('exportAsync' in child)) continue;
+          try {
+            var cbytes = await child.exportAsync(buildExportSettings());
+            var cbase64 = figma.base64Encode(cbytes);
+            regions.push({
+              name: child.name,
+              nodeId: child.id,
+              type: child.type,
+              image: {
+                base64: cbase64,
+                format: format,
+                scale: scale,
+                byteLength: cbytes.length,
+                width: child.width,
+                height: child.height,
+              },
+            });
+          } catch (childErr) {
+            regions.push({
+              name: child.name,
+              nodeId: child.id,
+              error: childErr && childErr.message ? childErr.message : String(childErr),
+            });
+          }
+        }
+        figma.ui.postMessage({
+          type: 'CAPTURE_SCREENSHOT_RESULT',
+          requestId: msg.requestId,
+          success: true,
+          mode: 'regions',
+          regionStrategy: 'children',
+          regions: regions,
+          totalRegions: regions.length,
+          rootSummary: {
+            nodeId: node.id,
+            name: node.name,
+            dimensions: { width: node.width, height: node.height },
+            childrenCount: node.children.length,
+            capped: node.children.length > maxRegions,
+          },
+        });
+        return;
+      }
+
+      // ---------- v1.9.5 MODE: regions (slices strategy) — NOT SUPPORTED YET ----------
+      if (returnMode === 'regions' && regionStrategy === 'slices') {
+        // Figma exportAsync does not support crop regions natively.
+        // Fallback: return a warning + single full image export.
+        figma.ui.postMessage({
+          type: 'CAPTURE_SCREENSHOT_RESULT',
+          requestId: msg.requestId,
+          success: false,
+          error: "regionStrategy='slices' not supported in v1.9.5. Use regionStrategy='children' or returnMode='summary'.",
+        });
+        return;
+      }
 
-      // Get node bounds for context
-      var bounds = null;
-      if ('absoluteBoundingBox' in node) {
-        bounds = node.absoluteBoundingBox;
+      // ---------- DEFAULT: full single export (base64 or file — server post-processes) ----------
+      if (!('exportAsync' in node)) {
+        throw new Error('Node type ' + node.type + ' does not support export');
       }
 
-      console.log('🌉 [F-MCP ATezer Bridge] Screenshot captured:', bytes.length, 'bytes (' + format + ' @' + scale + 'x)');
+      var bytes = await node.exportAsync(buildExportSettings());
+      var base64 = figma.base64Encode(bytes);
+      var bounds = ('absoluteBoundingBox' in node) ? node.absoluteBoundingBox : null;
+
+      console.log('🌉 [F-MCP ATezer Bridge v1.9.5] Screenshot captured:', bytes.length, 'bytes (' + format + ' @' + scale + 'x)');
 
       figma.ui.postMessage({
         type: 'CAPTURE_SCREENSHOT_RESULT',
         requestId: msg.requestId,
         success: true,
+        mode: returnMode,  // 'file' or 'base64' (server post-processes 'file' mode)
         image: {
           base64: base64,
           format: format,
           scale: scale,
           jpegQuality: format === 'JPG' ? jpegQuality : null,
           byteLength: bytes.length,
-          node: {
-            id: node.id,
-            name: node.name,
-            type: node.type
-          },
-          bounds: bounds
+          width: node.width,
+          height: node.height,
+          node: { id: node.id, name: node.name, type: node.type },
+          bounds: bounds,
         }
       });
 

package/f-mcp-plugin/ui.html

@@ -424,7 +424,7 @@
     window.__figmaFileName = null;
     // v1.8.0+: Plugin version reported in WebSocket "ready" handshake.
     // Keep in sync with package.json, src/core/version.ts, f-mcp-plugin/code.js.
-    var FMCP_PLUGIN_VERSION = '1.9.4';
+    var FMCP_PLUGIN_VERSION = '1.9.6';
 
     // v1.9.2+ Startup log — Figma plugin iframe'de yeni kod yüklendiğini doğrulamak için.
     // Console'da bu log görünüyorsa plugin güncel. Görünmüyorsa iframe eski kopyayı tutuyor

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@atezer/figma-mcp-bridge",
-	"version": "1.9.4",
+	"version": "1.9.6",
 	"description": "F-MCP ATezer: MCP server and Figma plugin bridge for Claude/Cursor. No REST token required.",
 	"type": "module",
 	"main": "dist/local-plugin-only.js",

package/skills/figma-canvas-ops/SKILL.md

@@ -184,6 +184,26 @@ active-ds.md `❌` ise: "Hangi DS? (SUI / Material / HIG / Kendi / Hiçbiri)". Y
 
 16. **Her Promise'i `await` et.**
 
+17. **v1.9.5 Concise Query Rule — tek satır boyut/metadata sorguları.**
+
+    Boyut, renk, layout sorgulamak için **20+ satır JS YAZMA**. Tek satır yeter:
+
+    ```js
+    // İYİ — tek satır, minimal context
+    return await figma.getNodeByIdAsync(id).then(n => ({ w: n.width, h: n.height, children: n.children?.length }));
+
+    // İYİ — toplu (birden fazla node)
+    return Promise.all(ids.map(async id => {
+      const n = await figma.getNodeByIdAsync(id);
+      return { id, name: n?.name, size: n ? [n.width, n.height] : null };
+    }));
+
+    // KÖTÜ — 30 satır "defensive" kod boyut sorgusu için
+    // await figma.loadAllPagesAsync(); for (var pg of ...) { if (...) ... }
+    ```
+
+    **Kural:** Tek nodeId için size → 1 satır. Multi-node metadata → 1 Promise.all. Complex traversal sadece üretim mantığında gerekli — keşifte değil.
+
 ## 2. Sayfa Kuralları
 
 ```js

package/skills/fmcp-intent-router/SKILL.md

@@ -226,6 +226,48 @@ FOR each input in required_inputs:
 
 Missing list'teki tüm soruları **TEK** `AskUserQuestion` çağrısında toplayıp sor. Max 4 soru/çağrı (AskUserQuestion limiti). 5+ soru gerekiyorsa 2 ayrı çağrı yap, ama ÖNCE kritik 4'ü sor, sonra kalanları.
 
+### v1.9.5 Elicitation Kuralı (SERT)
+
+- **Maks 1 `AskUserQuestion` çağrısı** tüm oturum boyunca. Tekrar soru sormak yasak — state'ten veya context'ten çıkar.
+- **"devam et" / "tamam" / "ok" / "yap" sonrası soru YASAK.** Kullanıcı onay verdi → üretime geç.
+- User prompt'u anlamlıysa (spesifik ekran adı, boyut, DS veriliyorsa) **hiç sorma**, direkt planla ve göster.
+- **"Sen seç"** cevabı alırsan: mantıklı default kullan (iPhone 17, mobile, single variant, active DS).
+- Sorulan her soru ≤30 kelime — uzun elicitation yasak.
+- Soruyu sormanın context maliyeti ≥ yanıtın değeri mi? Değilse sorma.
+
+### v1.9.6 Negative Intent Detection (KRITIK)
+
+Kullanıcı şu paternlerle **negatif/dışlayıcı** talimat verebilir — bunları ZORUNLU parse et:
+
+| Kullanıcı paterni | Anlam | Nasıl handle et |
+|---|---|---|
+| "X'i atla" / "X'i kullanma" / "X'ten bahsetme" | X referansını DIŞLA | `exclude_references: ["X"]` state'e yaz, o node/page/frame'e referans verme |
+| "X'e bakma" / "X yok say" / "X'i unut" | X sıfır-referans | Aynı |
+| "Y benzetme" / "Y gibi olmasın" | Y anti-pattern | `anti_pattern_refs: ["Y"]` — Y'ye ters tasarım yap |
+| "X dışında" / "X hariç" | Whitelist exclusion | `exclude_references: ["X"]` |
+| "Sıfırdan" / "baştan" / "yeni tasarım" | Mevcut iterasyonları atla | `start_fresh: true`, ideation/iterasyon referansları atla |
+
+**Örnek:**
+
+```
+Kullanıcı: "SUI Alt 3'e bakma, sıfırdan yeni bir Anasayfa tasarla"
+
+PARSE:
+  - exclude_references: ["SUI Alt 3", "241:11896"]  (SUI Alt 3 frame ID'si de dahil)
+  - start_fresh: true
+  - target_screen: "Anasayfa"
+  - DS: active-ds.md'den çek
+
+SONUÇ:
+  - SUI Alt 3 sayfası referans alınmaz
+  - Mevcut "SUI Alt 3 — Anasayfa" frame'i açılmaz, screenshot alınmaz
+  - ideation sayfası (ilham) kullanılabilir ama SUI Alt 3 bölümü atlanır
+```
+
+**Anti-pattern:** Kullanıcı "SUI Alt 3 atla" dedikten sonra onu screenshot alıp referans göstermek. v1.9.6'da bu explicit yasak — pre-flight'ta `exclude_references` kontrolü yapılır.
+
+**State persist:** `exclude_references` last-intent.md'ye yazılır; aynı oturum boyunca geçerli.
+
 **Örnek — generate-figma-screen:**
 
 ```

package/skills/fmcp-screen-orchestrator/SKILL.md

@@ -144,6 +144,35 @@ Benchmark/görselden DEĞER alma YASAK. Sadece NİYET: layout yönü, hiyerarşi
 2. **Content** — DS instance yerleşimi → screenshot → onay
 3. **Polish** — spacing, states, edge cases → son screenshot → audit
 
+### v1.9.5 Discovery Budget Rule (SERT)
+
+- **Maks 3 discovery çağrısı** (figma_get_*, figma_search_*, figma_execute read-only) sonra plan sun.
+- Plan kullanıcıya 1-2 cümle + varsa özet: "Şu ekran/section'ları oluşturacağım: [liste]. Onay veriyor musun?"
+- Kullanıcı onay verdikten sonra **mutation** aşamasına geç (figma_execute createFrame/setFills/setBoundVariable) — discovery counter reset olur.
+- Plugin 8 çağrıdan sonra `_warnings: ["DISCOVERY_BUDGET_WARNING..."]` döner — görünce üretime geçmek zorundasın.
+- 12 çağrıdan sonra `_DISCOVERY_BUDGET_EXCEEDED_BLOCKING: true` döner — **skip edilemez**, plan sun veya dur.
+
+### v1.9.5 Screenshot Method Selection (KARAR AĞACI)
+
+Ekran yakalama isteği olduğunda şu ağacı takip et:
+
+```
+İhtiyaç ne?
+├── "Planlama yapacağım, layout anlamak istiyorum" → returnMode: "summary" (metadata, screenshotsuz)
+├── "Kullanıcıya son halini göstereyim" → returnMode: "file" (1 screenshot dosyaya)
+├── "Büyük/scroll'lu ekran, bölümleri görmek istiyorum" → returnMode: "regions", regionStrategy: "children"
+├── "Üretim sonrası hızlı validation" → returnMode: "file"
+├── "Spesifik region (örn Hero)" → single-node file veya regions children maxRegions=3
+└── "Base64 context'te gerekli (nadiren)" → returnMode: "base64" (explicit, _warning ile)
+```
+
+**Budget farkındalığı:**
+- Bir oturumda >3 farklı nodeId için screenshot → 4. için zorunlu `summary` veya `regions`
+- Response'da `_warnings: ["CONTEXT_NEAR_LIMIT"]` veya `"DISCOVERY_BUDGET_..."` görürsen → sonraki screenshot zorunlu `summary`
+- Pixel-perfect değil, **region-perfect** düşün: "Hero'yu göreyim, gerekirse Actions'ı da" — hepsi birden değil
+
+**Kritik:** Screenshot YASAK değil. "Yasak" yerine **doğru yöntem** kullan. Her mode'un kullanım amacı var.
+
 ### Error Recovery
 
 | Hata | Aksiyon |