sonance-brand-mcp 1.3.53 → 1.3.56

package/dist/assets/api/sonance-vision-apply/route.ts

@@ -686,8 +686,9 @@ export async function POST(request: Request) {
       const messageContent: Anthropic.MessageCreateParams["messages"][0]["content"] = [];
 
       // Add screenshot if provided
+      let base64Data = "";
       if (screenshot) {
-        const base64Data = screenshot.split(",")[1] || screenshot;
+        base64Data = screenshot.split(",")[1] || screenshot;
         messageContent.push({
           type: "image",
           source: {
@@ -698,6 +699,111 @@ export async function POST(request: Request) {
         });
       }
 
+      // ========== PHASE A: VISUAL PROBLEM ANALYSIS ==========
+      // Before generating patches, analyze WHAT is visually wrong
+      // This forces the LLM to articulate the problem before trying to fix it
+      interface VisualAnalysis {
+        element: string;
+        problem: string;
+        currentState: string;
+        solution: string;
+        confidence: "high" | "medium" | "low";
+      }
+      
+      let visualAnalysis: VisualAnalysis | null = null;
+      
+      if (screenshot && userPrompt) {
+        debugLog("Phase A: Starting visual problem analysis");
+        
+        const analysisClient = new Anthropic({ apiKey });
+        
+        try {
+          const analysisResponse = await analysisClient.messages.create({
+            model: "claude-sonnet-4-20250514",
+            max_tokens: 1024,
+            messages: [
+              {
+                role: "user",
+                content: [
+                  {
+                    type: "image",
+                    source: {
+                      type: "base64",
+                      media_type: "image/png",
+                      data: base64Data,
+                    },
+                  },
+                  {
+                    type: "text",
+                    text: `You are analyzing a UI screenshot to understand a visual problem.
+
+User request: "${userPrompt}"
+
+${focusedElements && focusedElements.length > 0 ? `User clicked on these elements:
+${focusedElements.map((el) => `- ${el.name} (${el.type}) at position (${el.coordinates.x}, ${el.coordinates.y})`).join("\n")}
+` : ""}
+
+BEFORE any code changes can be made, you must analyze the visual problem.
+
+Answer these questions:
+1. ELEMENT: Which specific UI element has the problem? (describe its location, text content, appearance)
+2. PROBLEM: What exactly is visually wrong? (invisible text, wrong color, poor contrast, wrong size, etc.)
+3. CURRENT STATE: What styling/colors appear to be applied to this element?
+4. SOLUTION: What specific CSS/Tailwind change would fix this problem?
+5. CONFIDENCE: How confident are you that you've identified the correct element and problem? (high/medium/low)
+
+Return ONLY valid JSON with no other text:
+{
+  "element": "specific description of the UI element",
+  "problem": "what is visually wrong",
+  "currentState": "what styling appears to be applied",
+  "solution": "specific CSS/Tailwind fix needed",
+  "confidence": "high"
+}`,
+                  },
+                ],
+              },
+            ],
+          });
+          
+          const analysisText = analysisResponse.content.find((block) => block.type === "text");
+          if (analysisText && analysisText.type === "text") {
+            // Parse the JSON response
+            let jsonText = analysisText.text.trim();
+            // Extract JSON if wrapped in code blocks
+            const jsonMatch = jsonText.match(/```(?:json)?\s*([\s\S]*?)\s*```/) || jsonText.match(/(\{[\s\S]*\})/);
+            if (jsonMatch) {
+              jsonText = jsonMatch[1];
+            }
+            
+            try {
+              visualAnalysis = JSON.parse(jsonText) as VisualAnalysis;
+              debugLog("Phase A: Visual problem analysis complete", visualAnalysis);
+              
+              // If low confidence, return early with clarification request
+              if (visualAnalysis.confidence === "low") {
+                debugLog("Phase A: Low confidence - requesting clarification");
+                return NextResponse.json({
+                  success: false,
+                  needsClarification: true,
+                  analysis: visualAnalysis,
+                  message: `I can see "${visualAnalysis.element}" but I'm not certain about the problem: "${visualAnalysis.problem}". Can you be more specific about what needs to change?`,
+                });
+              }
+            } catch (parseError) {
+              debugLog("Phase A: Failed to parse analysis response", { 
+                error: String(parseError), 
+                response: jsonText.substring(0, 500) 
+              });
+              // Continue without analysis if parsing fails
+            }
+          }
+        } catch (analysisError) {
+          debugLog("Phase A: Analysis call failed", { error: String(analysisError) });
+          // Continue without analysis - fall back to existing behavior
+        }
+      }
+
       // ========== SMART CONTEXT BUDGETING ==========
       // Claude can handle 200k tokens (~800k chars), so we can safely include large files
       // Priority: Recommended file (NEVER truncate) > Page file (limited) > Other components (dynamic)
@@ -731,6 +837,24 @@ User Request: "${userPrompt}"
         textContent += `FOCUSED ELEMENTS (user clicked on these):
 ${focusedElements.map((el) => `- ${el.name} (${el.type}) at (${el.coordinates.x}, ${el.coordinates.y})`).join("\n")}
 
+`;
+      }
+
+      // ========== VISUAL PROBLEM ANALYSIS (from Phase A) ==========
+      if (visualAnalysis) {
+        textContent += `═══════════════════════════════════════════════════════════════════════════════
+🔍 VISUAL PROBLEM ANALYSIS (I analyzed the screenshot first)
+═══════════════════════════════════════════════════════════════════════════════
+
+**Element:** ${visualAnalysis.element}
+**Problem:** ${visualAnalysis.problem}
+**Current State:** ${visualAnalysis.currentState}
+**Required Fix:** ${visualAnalysis.solution}
+**Confidence:** ${visualAnalysis.confidence}
+
+⚠️ IMPORTANT: Your patches MUST implement the fix described above for the element described above.
+Find the code that renders "${visualAnalysis.element}" and apply "${visualAnalysis.solution}".
+
 `;
       }
 

package/dist/assets/api/sonance-vision-apply/theme-discovery.ts

@@ -4,11 +4,53 @@
  * Dynamically discovers and parses theme/design system files from target codebases.
  * Extracts CSS variables, Tailwind colors, and available semantic tokens to provide
  * context to the LLM for intelligent styling decisions.
+ * 
+ * NEW: Includes WCAG contrast ratio calculation to warn about bad color combinations.
  */
 
 import * as fs from "fs";
 import * as path from "path";
 
+// ============================================================================
+// TYPE DEFINITIONS
+// ============================================================================
+
+/**
+ * RGB color representation
+ */
+interface RGB {
+  r: number;
+  g: number;
+  b: number;
+}
+
+/**
+ * Contrast warning for a failing color combination
+ */
+interface ContrastWarning {
+  background: string;
+  text: string;
+  ratio: string;
+  suggestion: string;
+}
+
+/**
+ * Safe color pattern that passes WCAG
+ */
+interface SafePattern {
+  background: string;
+  text: string;
+  ratio: string;
+}
+
+/**
+ * Result of contrast analysis
+ */
+interface ContrastAnalysis {
+  warnings: ContrastWarning[];
+  safePatterns: SafePattern[];
+}
+
 /**
  * Discovered theme information from a codebase
  */
@@ -27,8 +69,208 @@ export interface DiscoveredTheme {
   
   // Files that were discovered and parsed
   discoveredFiles: string[];
+  
+  // Contrast analysis results
+  contrastAnalysis?: ContrastAnalysis;
+}
+
+// ============================================================================
+// COLOR PARSING FUNCTIONS
+// ============================================================================
+
+/**
+ * Convert HSL values to RGB
+ * Handles formats: "195 100% 41%" or "hsl(195, 100%, 41%)" or "195deg 100% 41%"
+ */
+function hslToRgb(h: number, s: number, l: number): RGB {
+  // Normalize h to 0-360, s and l to 0-1
+  h = ((h % 360) + 360) % 360;
+  s = Math.max(0, Math.min(1, s / 100));
+  l = Math.max(0, Math.min(1, l / 100));
+  
+  const k = (n: number) => (n + h / 30) % 12;
+  const a = s * Math.min(l, 1 - l);
+  const f = (n: number) => l - a * Math.max(-1, Math.min(k(n) - 3, Math.min(9 - k(n), 1)));
+  
+  return {
+    r: Math.round(f(0) * 255),
+    g: Math.round(f(8) * 255),
+    b: Math.round(f(4) * 255),
+  };
+}
+
+/**
+ * Parse hex color to RGB
+ * Handles: #fff, #ffffff, fff, ffffff
+ */
+function hexToRgb(hex: string): RGB | null {
+  // Remove # if present
+  hex = hex.replace(/^#/, "");
+  
+  // Expand shorthand (e.g., "fff" -> "ffffff")
+  if (hex.length === 3) {
+    hex = hex[0] + hex[0] + hex[1] + hex[1] + hex[2] + hex[2];
+  }
+  
+  if (hex.length !== 6) {
+    return null;
+  }
+  
+  const r = parseInt(hex.substring(0, 2), 16);
+  const g = parseInt(hex.substring(2, 4), 16);
+  const b = parseInt(hex.substring(4, 6), 16);
+  
+  if (isNaN(r) || isNaN(g) || isNaN(b)) {
+    return null;
+  }
+  
+  return { r, g, b };
 }
 
+/**
+ * Parse CSS color value to RGB
+ * Handles multiple formats:
+ * - Hex: #fff, #ffffff
+ * - RGB: rgb(255, 255, 255), rgb(255 255 255)
+ * - HSL: hsl(195, 100%, 41%), hsl(195 100% 41%)
+ * - Space-separated HSL: 195 100% 41% (common in Tailwind/shadcn)
+ * - oklch: oklch(0.7 0.15 195) - approximated
+ */
+function parseColorToRgb(value: string): RGB | null {
+  if (!value || typeof value !== "string") {
+    return null;
+  }
+  
+  const trimmed = value.trim().toLowerCase();
+  
+  // Skip CSS variable references - we can't resolve these without runtime
+  if (trimmed.includes("var(")) {
+    return null;
+  }
+  
+  // Handle hex colors
+  if (trimmed.startsWith("#") || /^[0-9a-f]{3,6}$/i.test(trimmed)) {
+    return hexToRgb(trimmed);
+  }
+  
+  // Handle rgb() and rgba()
+  const rgbMatch = trimmed.match(/rgba?\s*\(\s*(\d+)[\s,]+(\d+)[\s,]+(\d+)/);
+  if (rgbMatch) {
+    return {
+      r: parseInt(rgbMatch[1], 10),
+      g: parseInt(rgbMatch[2], 10),
+      b: parseInt(rgbMatch[3], 10),
+    };
+  }
+  
+  // Handle hsl() and hsla()
+  const hslFuncMatch = trimmed.match(/hsla?\s*\(\s*([\d.]+)(?:deg)?[\s,]+([\d.]+)%[\s,]+([\d.]+)%/);
+  if (hslFuncMatch) {
+    const h = parseFloat(hslFuncMatch[1]);
+    const s = parseFloat(hslFuncMatch[2]);
+    const l = parseFloat(hslFuncMatch[3]);
+    return hslToRgb(h, s, l);
+  }
+  
+  // Handle space-separated HSL (common in Tailwind/shadcn): "195 100% 41%"
+  const hslSpaceMatch = trimmed.match(/^([\d.]+)(?:deg)?\s+([\d.]+)%\s+([\d.]+)%$/);
+  if (hslSpaceMatch) {
+    const h = parseFloat(hslSpaceMatch[1]);
+    const s = parseFloat(hslSpaceMatch[2]);
+    const l = parseFloat(hslSpaceMatch[3]);
+    return hslToRgb(h, s, l);
+  }
+  
+  // Handle oklch() - approximate conversion (not perfect but gives reasonable results)
+  const oklchMatch = trimmed.match(/oklch\s*\(\s*([\d.]+)(?:%?)\s+([\d.]+)\s+([\d.]+)/);
+  if (oklchMatch) {
+    // Simplified oklch to RGB approximation
+    // L is lightness (0-1 or 0-100%), C is chroma, H is hue
+    let l = parseFloat(oklchMatch[1]);
+    if (l > 1) l = l / 100; // Handle percentage format
+    const c = parseFloat(oklchMatch[2]);
+    const h = parseFloat(oklchMatch[3]);
+    
+    // Very rough approximation: treat as HSL with adjusted values
+    // This won't be perfect but gives a reasonable estimate for contrast
+    const approxS = Math.min(100, c * 300); // Chroma to saturation approximation
+    const approxL = l * 100;
+    return hslToRgb(h, approxS, approxL);
+  }
+  
+  // Handle named colors (common ones)
+  const namedColors: Record<string, RGB> = {
+    white: { r: 255, g: 255, b: 255 },
+    black: { r: 0, g: 0, b: 0 },
+    transparent: { r: 0, g: 0, b: 0 }, // Treat as black for contrast purposes
+    red: { r: 255, g: 0, b: 0 },
+    green: { r: 0, g: 128, b: 0 },
+    blue: { r: 0, g: 0, b: 255 },
+    yellow: { r: 255, g: 255, b: 0 },
+    cyan: { r: 0, g: 255, b: 255 },
+    magenta: { r: 255, g: 0, b: 255 },
+    gray: { r: 128, g: 128, b: 128 },
+    grey: { r: 128, g: 128, b: 128 },
+  };
+  
+  if (namedColors[trimmed]) {
+    return namedColors[trimmed];
+  }
+  
+  return null;
+}
+
+// ============================================================================
+// WCAG CONTRAST CALCULATION
+// ============================================================================
+
+/**
+ * Calculate relative luminance using WCAG formula
+ * https://www.w3.org/TR/WCAG21/#dfn-relative-luminance
+ */
+function getLuminance(r: number, g: number, b: number): number {
+  const [rs, gs, bs] = [r, g, b].map((c) => {
+    c /= 255;
+    return c <= 0.03928 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4);
+  });
+  return 0.2126 * rs + 0.7152 * gs + 0.0722 * bs;
+}
+
+/**
+ * Calculate WCAG contrast ratio between two colors
+ * Returns ratio like 4.5, 7.0, 21.0 (max), etc.
+ * WCAG AA requires 4.5:1 for normal text, 3:1 for large text
+ * WCAG AAA requires 7:1 for normal text, 4.5:1 for large text
+ */
+function getContrastRatio(rgb1: RGB, rgb2: RGB): number {
+  const l1 = getLuminance(rgb1.r, rgb1.g, rgb1.b);
+  const l2 = getLuminance(rgb2.r, rgb2.g, rgb2.b);
+  const lighter = Math.max(l1, l2);
+  const darker = Math.min(l1, l2);
+  return (lighter + 0.05) / (darker + 0.05);
+}
+
+/**
+ * Determine which alternative (white or black) provides better contrast
+ */
+function getBestAlternative(bgRgb: RGB): { color: string; ratio: number } {
+  const whiteRgb: RGB = { r: 255, g: 255, b: 255 };
+  const blackRgb: RGB = { r: 0, g: 0, b: 0 };
+  
+  const whiteRatio = getContrastRatio(bgRgb, whiteRgb);
+  const blackRatio = getContrastRatio(bgRgb, blackRgb);
+  
+  if (whiteRatio >= blackRatio) {
+    return { color: "text-white", ratio: whiteRatio };
+  } else {
+    return { color: "text-black", ratio: blackRatio };
+  }
+}
+
+// ============================================================================
+// THEME FILE DISCOVERY
+// ============================================================================
+
 /**
  * Patterns for finding theme-related files
  */
@@ -221,49 +463,120 @@ export function extractAvailableTokens(cssVariables: Record<string, string>): st
   return [...new Set([...tokens, ...commonTokens])];
 }
 
+// ============================================================================
+// CONTRAST ANALYSIS
+// ============================================================================
+
 /**
  * Analyze CSS variables to identify contrast relationships
- * Returns warnings about potentially problematic color combinations
+ * Calculates actual WCAG contrast ratios and returns warnings for failing combinations
  */
 export function analyzeContrastRelationships(
   cssVariables: Record<string, string>
-): { warnings: string[]; goodPairs: { bg: string; text: string }[] } {
-  const warnings: string[] = [];
-  const goodPairs: { bg: string; text: string }[] = [];
+): ContrastAnalysis {
+  const warnings: ContrastWarning[] = [];
+  const safePatterns: SafePattern[] = [];
   
-  // Common pattern: --{name} is background, --{name}-foreground is text
-  // Check if foreground values look like they might have contrast issues
+  // Track which backgrounds we've analyzed to add white/black alternatives
+  const analyzedBackgrounds: { name: string; rgb: RGB }[] = [];
   
+  // Find all bg/foreground pairs automatically
   for (const [varName, value] of Object.entries(cssVariables)) {
     // Skip if this is a foreground variable
     if (varName.includes("foreground")) continue;
     
+    // Skip non-color variables
+    if (
+      varName.includes("radius") ||
+      varName.includes("shadow") ||
+      varName.includes("ring") ||
+      varName.includes("border") && !varName.match(/border$/)
+    ) {
+      continue;
+    }
+    
     const baseName = varName.replace(/^--/, "");
     const foregroundVar = `--${baseName}-foreground`;
     
+    // Parse background color
+    const bgRgb = parseColorToRgb(value);
+    if (!bgRgb) continue;
+    
+    // Track this background for alternative suggestions
+    analyzedBackgrounds.push({ name: baseName, rgb: bgRgb });
+    
+    // Check if there's a corresponding foreground variable
     if (cssVariables[foregroundVar]) {
-      const bgValue = value;
-      const fgValue = cssVariables[foregroundVar];
+      const fgRgb = parseColorToRgb(cssVariables[foregroundVar]);
       
-      // Simple heuristic: if both values reference same color or are similar
-      // This is a basic check - real contrast would need color parsing
-      if (bgValue === fgValue) {
-        warnings.push(
-          `WARNING: ${varName} and ${foregroundVar} have identical values - text will be invisible`
-        );
+      if (fgRgb) {
+        const ratio = getContrastRatio(bgRgb, fgRgb);
+        const passes = ratio >= 4.5; // WCAG AA for normal text
+        
+        if (!passes) {
+          // Find the best alternative
+          const alternative = getBestAlternative(bgRgb);
+          
+          warnings.push({
+            background: `bg-${baseName}`,
+            text: `text-${baseName}-foreground`,
+            ratio: ratio.toFixed(1),
+            suggestion: `Use ${alternative.color} instead (${alternative.ratio.toFixed(1)}:1 contrast)`,
+          });
+        } else {
+          safePatterns.push({
+            background: `bg-${baseName}`,
+            text: `text-${baseName}-foreground`,
+            ratio: ratio.toFixed(1),
+          });
+        }
       }
+    }
+  }
+  
+  // Add white/black alternatives for all analyzed backgrounds
+  const whiteRgb: RGB = { r: 255, g: 255, b: 255 };
+  const blackRgb: RGB = { r: 0, g: 0, b: 0 };
+  
+  for (const { name, rgb } of analyzedBackgrounds) {
+    // Only add alternatives for semantic color names (primary, accent, etc.)
+    if (
+      name.includes("primary") ||
+      name.includes("secondary") ||
+      name.includes("accent") ||
+      name.includes("destructive") ||
+      name.includes("success") ||
+      name.includes("warning") ||
+      name.includes("muted")
+    ) {
+      const whiteRatio = getContrastRatio(rgb, whiteRgb);
+      const blackRatio = getContrastRatio(rgb, blackRgb);
       
-      // Add as a known pair (user should verify contrast)
-      goodPairs.push({
-        bg: `bg-${baseName}`,
-        text: `text-${baseName}-foreground`,
-      });
+      if (whiteRatio >= 4.5) {
+        safePatterns.push({
+          background: `bg-${name}`,
+          text: "text-white",
+          ratio: whiteRatio.toFixed(1),
+        });
+      }
+      
+      if (blackRatio >= 4.5) {
+        safePatterns.push({
+          background: `bg-${name}`,
+          text: "text-black",
+          ratio: blackRatio.toFixed(1),
+        });
+      }
     }
   }
   
-  return { warnings, goodPairs };
+  return { warnings, safePatterns };
 }
 
+// ============================================================================
+// MAIN ENTRY POINTS
+// ============================================================================
+
 /**
  * Main entry point: Discover theme from a project
  */
@@ -308,11 +621,15 @@ export async function discoverTheme(projectRoot: string): Promise<DiscoveredThem
   // Extract available tokens
   result.availableTokens = extractAvailableTokens(result.cssVariables);
   
+  // Run contrast analysis
+  result.contrastAnalysis = analyzeContrastRelationships(result.cssVariables);
+  
   return result;
 }
 
 /**
  * Format discovered theme as context for the LLM prompt
+ * Includes contrast warnings to prevent bad color combinations
  */
 export function formatThemeForPrompt(theme: DiscoveredTheme): string {
   const lines: string[] = [];
@@ -369,6 +686,57 @@ export function formatThemeForPrompt(theme: DiscoveredTheme): string {
     lines.push("");
   }
   
+  // ========== CONTRAST ANALYSIS (NEW) ==========
+  // Run contrast analysis if not already done
+  const contrastAnalysis = theme.contrastAnalysis || analyzeContrastRelationships(theme.cssVariables);
+  
+  // Show warnings first (most important for LLM)
+  if (contrastAnalysis.warnings.length > 0) {
+    lines.push("");
+    lines.push("⚠️ CONTRAST WARNINGS (these combinations FAIL WCAG in this codebase - DO NOT USE):");
+    for (const w of contrastAnalysis.warnings) {
+      lines.push(`  ❌ ${w.background} + ${w.text}: ${w.ratio}:1 → ${w.suggestion}`);
+    }
+  }
+  
+  // Show safe patterns
+  if (contrastAnalysis.safePatterns.length > 0) {
+    lines.push("");
+    lines.push("✓ SAFE COLOR COMBINATIONS (use these instead):");
+    
+    // Deduplicate and sort by background, prioritize semantic foregrounds
+    const seen = new Set<string>();
+    const sorted = contrastAnalysis.safePatterns
+      .filter((p) => {
+        const key = `${p.background}+${p.text}`;
+        if (seen.has(key)) return false;
+        seen.add(key);
+        return true;
+      })
+      .sort((a, b) => {
+        // Sort by background name, then prioritize -foreground over white/black
+        if (a.background !== b.background) {
+          return a.background.localeCompare(b.background);
+        }
+        // Prioritize -foreground variants
+        const aIsForeground = a.text.includes("-foreground");
+        const bIsForeground = b.text.includes("-foreground");
+        if (aIsForeground && !bIsForeground) return -1;
+        if (!aIsForeground && bIsForeground) return 1;
+        return 0;
+      });
+    
+    for (const s of sorted.slice(0, 15)) { // Limit to avoid prompt bloat
+      lines.push(`  ✓ ${s.background} + ${s.text}: ${s.ratio}:1`);
+    }
+    
+    if (sorted.length > 15) {
+      lines.push(`  ... and ${sorted.length - 15} more safe combinations`);
+    }
+  }
+  
+  lines.push("");
+  
   // Available Tokens
   if (theme.availableTokens.length > 0) {
     lines.push(`Available Semantic Tokens: ${theme.availableTokens.slice(0, 20).join(", ")}`);
@@ -385,4 +753,3 @@ export function formatThemeForPrompt(theme: DiscoveredTheme): string {
   
   return lines.join("\n");
 }
-

package/dist/assets/api/sonance-vision-edit/route.ts

@@ -695,8 +695,9 @@ export async function POST(request: Request) {
       const messageContent: Anthropic.MessageCreateParams["messages"][0]["content"] = [];
 
       // Add screenshot if provided
+      let base64Data = "";
       if (screenshot) {
-        const base64Data = screenshot.split(",")[1] || screenshot;
+        base64Data = screenshot.split(",")[1] || screenshot;
         messageContent.push({
           type: "image",
           source: {
@@ -707,6 +708,111 @@ export async function POST(request: Request) {
         });
       }
 
+      // ========== PHASE A: VISUAL PROBLEM ANALYSIS ==========
+      // Before generating patches, analyze WHAT is visually wrong
+      // This forces the LLM to articulate the problem before trying to fix it
+      interface VisualAnalysis {
+        element: string;
+        problem: string;
+        currentState: string;
+        solution: string;
+        confidence: "high" | "medium" | "low";
+      }
+      
+      let visualAnalysis: VisualAnalysis | null = null;
+      
+      if (screenshot && userPrompt) {
+        debugLog("Phase A: Starting visual problem analysis");
+        
+        const analysisClient = new Anthropic({ apiKey });
+        
+        try {
+          const analysisResponse = await analysisClient.messages.create({
+            model: "claude-sonnet-4-20250514",
+            max_tokens: 1024,
+            messages: [
+              {
+                role: "user",
+                content: [
+                  {
+                    type: "image",
+                    source: {
+                      type: "base64",
+                      media_type: "image/png",
+                      data: base64Data,
+                    },
+                  },
+                  {
+                    type: "text",
+                    text: `You are analyzing a UI screenshot to understand a visual problem.
+
+User request: "${userPrompt}"
+
+${focusedElements && focusedElements.length > 0 ? `User clicked on these elements:
+${focusedElements.map((el) => `- ${el.name} (${el.type}) at position (${el.coordinates.x}, ${el.coordinates.y})`).join("\n")}
+` : ""}
+
+BEFORE any code changes can be made, you must analyze the visual problem.
+
+Answer these questions:
+1. ELEMENT: Which specific UI element has the problem? (describe its location, text content, appearance)
+2. PROBLEM: What exactly is visually wrong? (invisible text, wrong color, poor contrast, wrong size, etc.)
+3. CURRENT STATE: What styling/colors appear to be applied to this element?
+4. SOLUTION: What specific CSS/Tailwind change would fix this problem?
+5. CONFIDENCE: How confident are you that you've identified the correct element and problem? (high/medium/low)
+
+Return ONLY valid JSON with no other text:
+{
+  "element": "specific description of the UI element",
+  "problem": "what is visually wrong",
+  "currentState": "what styling appears to be applied",
+  "solution": "specific CSS/Tailwind fix needed",
+  "confidence": "high"
+}`,
+                  },
+                ],
+              },
+            ],
+          });
+          
+          const analysisText = analysisResponse.content.find((block) => block.type === "text");
+          if (analysisText && analysisText.type === "text") {
+            // Parse the JSON response
+            let jsonText = analysisText.text.trim();
+            // Extract JSON if wrapped in code blocks
+            const jsonMatch = jsonText.match(/```(?:json)?\s*([\s\S]*?)\s*```/) || jsonText.match(/(\{[\s\S]*\})/);
+            if (jsonMatch) {
+              jsonText = jsonMatch[1];
+            }
+            
+            try {
+              visualAnalysis = JSON.parse(jsonText) as VisualAnalysis;
+              debugLog("Phase A: Visual problem analysis complete", visualAnalysis);
+              
+              // If low confidence, return early with clarification request
+              if (visualAnalysis.confidence === "low") {
+                debugLog("Phase A: Low confidence - requesting clarification");
+                return NextResponse.json({
+                  success: false,
+                  needsClarification: true,
+                  analysis: visualAnalysis,
+                  message: `I can see "${visualAnalysis.element}" but I'm not certain about the problem: "${visualAnalysis.problem}". Can you be more specific about what needs to change?`,
+                });
+              }
+            } catch (parseError) {
+              debugLog("Phase A: Failed to parse analysis response", { 
+                error: String(parseError), 
+                response: jsonText.substring(0, 500) 
+              });
+              // Continue without analysis if parsing fails
+            }
+          }
+        } catch (analysisError) {
+          debugLog("Phase A: Analysis call failed", { error: String(analysisError) });
+          // Continue without analysis - fall back to existing behavior
+        }
+      }
+
       // ========== SMART CONTEXT BUDGETING ==========
       // Claude can handle 200k tokens (~800k chars), so we can safely include large files
       // Priority: Recommended file (NEVER truncate) > Page file (limited) > Other components (dynamic)
@@ -740,6 +846,24 @@ User Request: "${userPrompt}"
         textContent += `FOCUSED ELEMENTS (user clicked on these):
 ${focusedElements.map((el) => `- ${el.name} (${el.type}) at (${el.coordinates.x}, ${el.coordinates.y})`).join("\n")}
 
+`;
+      }
+
+      // ========== VISUAL PROBLEM ANALYSIS (from Phase A) ==========
+      if (visualAnalysis) {
+        textContent += `═══════════════════════════════════════════════════════════════════════════════
+🔍 VISUAL PROBLEM ANALYSIS (I analyzed the screenshot first)
+═══════════════════════════════════════════════════════════════════════════════
+
+**Element:** ${visualAnalysis.element}
+**Problem:** ${visualAnalysis.problem}
+**Current State:** ${visualAnalysis.currentState}
+**Required Fix:** ${visualAnalysis.solution}
+**Confidence:** ${visualAnalysis.confidence}
+
+⚠️ IMPORTANT: Your patches MUST implement the fix described above for the element described above.
+Find the code that renders "${visualAnalysis.element}" and apply "${visualAnalysis.solution}".
+
 `;
       }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sonance-brand-mcp",
-  "version": "1.3.53",
+  "version": "1.3.56",
   "description": "MCP Server for Sonance Brand Guidelines and Component Library - gives Claude instant access to brand colors, typography, and UI components.",
   "main": "dist/index.js",
   "type": "module",