sonance-brand-mcp 1.3.58 → 1.3.60

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

@@ -171,6 +171,73 @@ Be smart - use your knowledge of React patterns to make educated guesses about c
   }
 }
 
+/**
+ * Search candidate files for JSX code matching the focused element
+ * This helps identify which file actually contains the element the user clicked on
+ */
+function findFilesContainingElement(
+  focusedElements: VisionFocusedElement[] | undefined,
+  candidateFiles: { path: string; content: string }[]
+): { path: string; score: number; matches: string[] }[] {
+  if (!focusedElements || focusedElements.length === 0) {
+    return [];
+  }
+
+  const results: { path: string; score: number; matches: string[] }[] = [];
+
+  for (const file of candidateFiles) {
+    let score = 0;
+    const matches: string[] = [];
+    const content = file.content.toLowerCase();
+
+    for (const el of focusedElements) {
+      // Extract element type from the name (e.g., "button #123" -> "button")
+      const elementType = el.name.split(/[\s#]/)[0].toLowerCase();
+      const componentType = el.type.toLowerCase();
+
+      // Search for JSX patterns
+      // Check for HTML tags like <button, <div, etc.
+      if (content.includes(`<${elementType}`)) {
+        score += 10;
+        matches.push(`<${elementType}>`);
+      }
+
+      // Check for React component like <Button, <Card, etc.
+      const capitalizedType = el.type.charAt(0).toUpperCase() + el.type.slice(1);
+      if (file.content.includes(`<${capitalizedType}`)) {
+        score += 15;
+        matches.push(`<${capitalizedType}>`);
+      }
+
+      // Check for component imports
+      if (content.includes(`import`) && content.includes(componentType)) {
+        score += 5;
+      }
+
+      // Check for event handlers commonly associated with buttons
+      if (elementType === "button" || componentType === "button") {
+        if (content.includes("onclick") || content.includes("onpress")) {
+          score += 3;
+        }
+      }
+
+      // Check for the component being defined in this file
+      if (file.content.includes(`function ${capitalizedType}`) || 
+          file.content.includes(`const ${capitalizedType}`)) {
+        score += 20;
+        matches.push(`defines ${capitalizedType}`);
+      }
+    }
+
+    if (score > 0) {
+      results.push({ path: file.path, score, matches });
+    }
+  }
+
+  // Sort by score descending
+  return results.sort((a, b) => b.score - a.score);
+}
+
 /**
  * Phase 3: Ask LLM to select the best file from actual file list
  * This replaces guessing - the LLM sees the real filenames and picks one
@@ -179,7 +246,8 @@ async function selectBestFileFromList(
   screenshot: string,
   userPrompt: string,
   candidateFiles: string[],
-  apiKey: string
+  apiKey: string,
+  focusedElementHints?: { path: string; score: number; matches: string[] }[]
 ): Promise<string | null> {
   if (candidateFiles.length === 0) return null;
   
@@ -203,7 +271,12 @@ async function selectBestFileFromList(
 
 Here are the actual component files found in this codebase:
 ${candidateFiles.map((f, i) => `${i + 1}. ${f}`).join('\n')}
+${focusedElementHints && focusedElementHints.length > 0 ? `
+FOCUSED ELEMENT ANALYSIS - Files that contain the element the user clicked on:
+${focusedElementHints.slice(0, 3).map(h => `- ${h.path} (confidence: ${h.score}, found: ${h.matches.join(", ")})`).join('\n')}
 
+IMPORTANT: Prefer files from the FOCUSED ELEMENT ANALYSIS above, as they contain the actual element the user wants to modify.
+` : ''}
 Looking at the screenshot, which file MOST LIKELY contains the UI elements the user wants to modify?
 
 IMPORTANT: Return ONLY the exact file path from the list above (e.g., "components/ProcessCatalogue/ProcessDetailPanel.tsx").
@@ -438,41 +511,81 @@ function searchFilesSmart(
   return sortedResults.map(r => ({ path: r.path, content: r.content, score: r.score }));
 }
 
-const VISION_SYSTEM_PROMPT = `You are a code editor. Make ONLY the change the user requested.
+const VISION_SYSTEM_PROMPT = `You are a code editor like Cursor. Before making changes, REASON about what needs to be done.
+
+═══════════════════════════════════════════════════════════════════════════════
+STEP 1: ANALYZE (Think like Cursor)
+═══════════════════════════════════════════════════════════════════════════════
+
+Before writing any patches, analyze the screenshot and answer:
+
+1. CURRENT STATE: What do I see in the screenshot? 
+   - Is the element visible/readable right now?
+   - What colors/styles are currently applied?
+
+2. PROBLEM IDENTIFICATION: What's actually wrong?
+   - Contrast issue? (text blending with background)
+   - Hidden element? (not showing at all)
+   - Hover state issue? (only visible on interaction)
+   - Layout issue? (wrong size/position)
+   - Or is it already correct?
+
+3. FIX STRATEGY: What should I change?
+   - DEFAULT state only (element needs to look different normally)
+   - HOVER state only (element needs different hover effect)
+   - BOTH states (element needs overall visibility improvement)
+   - ASK for clarification (request is too vague)
+
+═══════════════════════════════════════════════════════════════════════════════
+STEP 2: GENERATE PATCHES (Only after reasoning)
+═══════════════════════════════════════════════════════════════════════════════
+
+CRITICAL - FILE SELECTION:
+- You MUST modify the file marked "TARGET COMPONENT" - this is the file you have FULL visibility into
+- Do NOT try to modify other files listed in context - you only see their imports/exports, not full content
+- If the TARGET COMPONENT is not the right file, return clarification_needed
+
+COPY EXACTLY from the TARGET COMPONENT section:
+- Your "search" string must match the file CHARACTER-FOR-CHARACTER
+- Include exact indentation and at least 3 lines of context
+- If the element looks FINE in the screenshot, say so
 
 RULES:
-1. Make the SMALLEST possible change to accomplish the request
-2. Do NOT refactor, rebrand, or "improve" anything else
-3. Do NOT change import statements unless explicitly required
-4. Do NOT change component libraries (e.g., heroui to shadcn)
-5. If fixing a color/visibility issue, change ONLY that element's classes
-6. Your patch should typically be 1-5 lines, not 50+
-7. NEVER invent or guess code - your "search" string MUST match the file EXACTLY
-8. NEVER change data mappings (icon names, keys, enum values) unless user explicitly provides the new values
-9. If you don't know what values exist in a database or data source, DO NOT guess - ask for clarification
-
-CRITICAL - DATA INTEGRITY:
-- If code references database values (like icon_name, type, status), DO NOT change the mapping keys
-- You cannot see database content - only change STRUCTURE, not DATA MAPPINGS
-- Example: If you see iconMap["EyeOff"] = SomeIcon, do NOT change "EyeOff" to something else
-- If user wants different icons, they must tell you the EXACT icon names they want
-
-PATCH FORMAT:
-Return ONLY raw JSON (no markdown, no preamble):
+1. Make the SMALLEST possible change
+2. Do NOT refactor or "improve" other code
+3. NEVER invent code - COPY exact code from file
+4. NEVER change data mappings unless user provides new values
+5. If visibility issue: prefer explicit colors (text-white, text-black) over semantic tokens
+
+═══════════════════════════════════════════════════════════════════════════════
+RESPONSE FORMAT
+═══════════════════════════════════════════════════════════════════════════════
+
+Return ONLY raw JSON:
 {
-  "reasoning": "brief explanation",
+  "analysis": {
+    "currentState": "what I see in the screenshot",
+    "problem": "the actual issue (or 'none - element appears correct')",
+    "fixStrategy": "default|hover|both|clarification_needed"
+  },
+  "reasoning": "my diagnosis and approach",
   "modifications": [{
     "filePath": "path/to/file.tsx",
     "patches": [{
-      "search": "exact original code (copy from provided file)",
-      "replace": "minimal change",
-      "explanation": "what this does"
+      "search": "EXACT copy from file",
+      "replace": "changed code",
+      "explanation": "what this changes and why"
     }]
   }],
-  "explanation": "summary"
+  "explanation": "summary of what was changed"
 }
 
-If you cannot find the exact code to modify, OR if you would need to guess data values, return empty modifications array with explanation.`;
+If the element looks correct, return:
+{
+  "analysis": { "currentState": "...", "problem": "none", "fixStrategy": "clarification_needed" },
+  "modifications": [],
+  "explanation": "The element appears visible/correct in the screenshot. Please specify what needs to change."
+}`;
 
 export async function POST(request: Request) {
   // Only allow in development
@@ -604,6 +717,22 @@ export async function POST(request: Request) {
           const searchResults = searchFilesSmart(analysis, projectRoot, 10);
           smartSearchFiles = searchResults.map(r => ({ path: r.path, content: r.content }));
           
+          // PHASE 2.5: Find which files contain the focused element
+          const focusedElementHints = findFilesContainingElement(
+            focusedElements,
+            searchResults.map(r => ({ path: r.path, content: r.content }))
+          );
+          
+          if (focusedElementHints.length > 0) {
+            debugLog("Focused element search results", {
+              topMatches: focusedElementHints.slice(0, 3).map(h => ({
+                path: h.path,
+                score: h.score,
+                matches: h.matches
+              }))
+            });
+          }
+          
           // PHASE 3: Ask LLM to pick the best file from actual file list
           if (searchResults.length > 0) {
             const candidateFiles = searchResults.slice(0, 10).map(r => r.path);
@@ -611,7 +740,8 @@ export async function POST(request: Request) {
               screenshot,
               userPrompt,
               candidateFiles,
-              apiKey
+              apiKey,
+              focusedElementHints
             );
             
             if (selectedFile) {
@@ -778,30 +908,59 @@ ${truncatedContent}${wasTruncated ? "\n// ... (truncated)" : ""}
 
       // ========== THEME DISCOVERY (REFERENCE ONLY) ==========
       // Dynamically discover theme tokens from the target codebase
-      // This is marked as REFERENCE ONLY so the LLM doesn't use it to justify extra changes
       const discoveredTheme = await discoverTheme(projectRoot);
       const themeContext = formatThemeForPrompt(discoveredTheme);
       
+      // Check if this is a visibility-related request
+      const isVisibilityRequest = /visible|can't see|cant see|not visible|hidden|color|contrast/i.test(userPrompt);
+      
       if (discoveredTheme.discoveredFiles.length > 0) {
-        textContent += `
+        // Only include detailed color guidance for visibility requests
+        if (isVisibilityRequest) {
+          // Extract available text color classes from discovered theme
+          const textColorClasses = Object.keys(discoveredTheme.cssVariables)
+            .filter(key => key.includes('foreground') || key.includes('text'))
+            .map(key => `text-${key.replace('--', '').replace(/-/g, '-')}`)
+            .slice(0, 10);
+          
+          textContent += `
 ═══════════════════════════════════════════════════════════════════════════════
-REFERENCE ONLY (do not use this to justify additional changes)
+COLOR FIX GUIDANCE (for visibility issues only)
 ═══════════════════════════════════════════════════════════════════════════════
 
-If you need to pick a color for a VISIBILITY fix, these are safe choices:
-- bg-accent text-white (cyan button with white text)
-- bg-primary text-white (charcoal button with white text)
-- bg-success text-white (green button with white text)
-- bg-destructive text-white (red button with white text)
+AVAILABLE TEXT COLORS (use these for contrast fixes):
+- text-white (always visible on dark backgrounds)
+- text-black (always visible on light backgrounds)
+- text-foreground (theme default)
+- text-primary-foreground (for bg-primary)
+- text-accent-foreground (for bg-accent - CHECK IF THIS HAS GOOD CONTRAST)
+- text-destructive-foreground (for bg-destructive)
+
+SAFE BUTTON PATTERNS:
+- bg-accent text-white (cyan button, guaranteed visible)
+- bg-primary text-white (charcoal button, guaranteed visible)
+- bg-destructive text-white (red button, guaranteed visible)
+- bg-muted text-foreground (gray button, guaranteed visible)
 
-But ONLY use these if the user is asking for a color/visibility change.
-Do NOT rebrand or change other elements to match.
+IMPORTANT: If current code has text-accent-foreground or similar semantic colors
+that result in poor contrast, REPLACE with text-white or text-black.
 
 `;
+        } else {
+          // For non-visibility requests, minimal reference
+          textContent += `
+═══════════════════════════════════════════════════════════════════════════════
+REFERENCE ONLY (do not use this to justify additional changes)
+═══════════════════════════════════════════════════════════════════════════════
+Theme discovered from: ${discoveredTheme.discoveredFiles.join(', ')}
+`;
+        }
+        
         debugLog("Theme discovery complete", {
           filesFound: discoveredTheme.discoveredFiles,
           cssVariableCount: Object.keys(discoveredTheme.cssVariables).length,
           tailwindColorCount: Object.keys(discoveredTheme.tailwindColors).length,
+          isVisibilityRequest,
         });
       }
 
@@ -946,6 +1105,11 @@ This is better than generating patches with made-up code.`,
 
         // Parse AI response - now expecting patches instead of full file content
         let aiResponse: {
+          analysis?: {
+            currentState?: string;
+            problem?: string;
+            fixStrategy?: string;
+          };
           reasoning?: string;
           modifications: Array<{
             filePath: string;
@@ -993,9 +1157,31 @@ This is better than generating patches with made-up code.`,
           );
         }
 
+        // Log the LLM's analysis/reasoning (like Cursor showing its thought process)
+        if (aiResponse.analysis) {
+          debugLog("LLM Analysis (Step 1)", {
+            currentState: aiResponse.analysis.currentState,
+            problem: aiResponse.analysis.problem,
+            fixStrategy: aiResponse.analysis.fixStrategy,
+          });
+        }
+
         finalExplanation = aiResponse.explanation;
         finalReasoning = aiResponse.reasoning;
 
+        // If LLM says clarification is needed, return that to the user
+        if (aiResponse.analysis?.fixStrategy === "clarification_needed" && 
+            (!aiResponse.modifications || aiResponse.modifications.length === 0)) {
+          return NextResponse.json({
+            success: true,
+            sessionId: newSessionId,
+            needsClarification: true,
+            analysis: aiResponse.analysis,
+            explanation: aiResponse.explanation || "The element appears correct. Please specify what needs to change.",
+            modifications: [],
+          });
+        }
+
         if (!aiResponse.modifications || aiResponse.modifications.length === 0) {
           return NextResponse.json({
             success: true,
@@ -1034,6 +1220,19 @@ This is better than generating patches with made-up code.`,
           continue;
         }
         
+        // CRITICAL: Warn if LLM is trying to modify a file OTHER than the TARGET COMPONENT
+        // This usually means the LLM is trying to modify a file it doesn't have full visibility into
+        const targetComponentPath = recommendedFileContent?.path;
+        if (targetComponentPath && mod.filePath !== targetComponentPath) {
+          debugLog("WARNING: LLM trying to modify non-target file", {
+            targetComponent: targetComponentPath,
+            attemptedFile: mod.filePath,
+            warning: "LLM may be hallucinating code since it only has full content of the TARGET COMPONENT"
+          });
+          console.warn(`[Apply-First] ⚠️ LLM is modifying ${mod.filePath} but TARGET COMPONENT is ${targetComponentPath}`);
+          console.warn(`[Apply-First] ⚠️ This may cause hallucination since LLM only has full visibility into the TARGET COMPONENT`);
+        }
+        
         const fullPath = path.join(projectRoot, mod.filePath);
         let originalContent = "";
         if (fs.existsSync(fullPath)) {
@@ -1109,6 +1308,34 @@ This is better than generating patches with made-up code.`,
             modifiedContent = patchResult.modifiedContent;
             console.log(`[Apply-First] All ${mod.patches.length} patches applied successfully to ${mod.filePath}`);
           }
+          
+          // SYNTAX VALIDATION: Check for common JSX/HTML tag mismatches
+          // This catches cases where the LLM changes opening tags but not closing tags
+          if (mod.filePath.endsWith('.tsx') || mod.filePath.endsWith('.jsx')) {
+            const openDivs = (modifiedContent.match(/<div[\s>]/g) || []).length;
+            const closeDivs = (modifiedContent.match(/<\/div>/g) || []).length;
+            const openSpans = (modifiedContent.match(/<span[\s>]/g) || []).length;
+            const closeSpans = (modifiedContent.match(/<\/span>/g) || []).length;
+            
+            if (openDivs !== closeDivs || openSpans !== closeSpans) {
+              debugLog("SYNTAX WARNING: Tag mismatch detected", {
+                filePath: mod.filePath,
+                divs: { open: openDivs, close: closeDivs },
+                spans: { open: openSpans, close: closeSpans },
+              });
+              console.warn(`[Apply-First] ⚠️ SYNTAX WARNING: Tag mismatch in ${mod.filePath}`);
+              console.warn(`[Apply-First]   divs: ${openDivs} open, ${closeDivs} close`);
+              console.warn(`[Apply-First]   spans: ${openSpans} open, ${closeSpans} close`);
+              
+              // If there's a significant mismatch, reject the change
+              const divDiff = Math.abs(openDivs - closeDivs);
+              const spanDiff = Math.abs(openSpans - closeSpans);
+              if (divDiff > 0 || spanDiff > 0) {
+                patchErrors.push(`${mod.filePath}: LLM introduced syntax error - tag mismatch detected (${divDiff} div, ${spanDiff} span). Change rejected.`);
+                continue;
+              }
+            }
+          }
         } else if (mod.modifiedContent) {
           // Legacy: AI returned full file content
           console.warn(`[Apply-First] Legacy modifiedContent received for ${mod.filePath} - patch-based format preferred`);

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

@@ -167,6 +167,73 @@ Be smart - use your knowledge of React patterns to make educated guesses about c
   }
 }
 
+/**
+ * Search candidate files for JSX code matching the focused element
+ * This helps identify which file actually contains the element the user clicked on
+ */
+function findFilesContainingElement(
+  focusedElements: VisionFocusedElement[] | undefined,
+  candidateFiles: { path: string; content: string }[]
+): { path: string; score: number; matches: string[] }[] {
+  if (!focusedElements || focusedElements.length === 0) {
+    return [];
+  }
+
+  const results: { path: string; score: number; matches: string[] }[] = [];
+
+  for (const file of candidateFiles) {
+    let score = 0;
+    const matches: string[] = [];
+    const content = file.content.toLowerCase();
+
+    for (const el of focusedElements) {
+      // Extract element type from the name (e.g., "button #123" -> "button")
+      const elementType = el.name.split(/[\s#]/)[0].toLowerCase();
+      const componentType = el.type.toLowerCase();
+
+      // Search for JSX patterns
+      // Check for HTML tags like <button, <div, etc.
+      if (content.includes(`<${elementType}`)) {
+        score += 10;
+        matches.push(`<${elementType}>`);
+      }
+
+      // Check for React component like <Button, <Card, etc.
+      const capitalizedType = el.type.charAt(0).toUpperCase() + el.type.slice(1);
+      if (file.content.includes(`<${capitalizedType}`)) {
+        score += 15;
+        matches.push(`<${capitalizedType}>`);
+      }
+
+      // Check for component imports
+      if (content.includes(`import`) && content.includes(componentType)) {
+        score += 5;
+      }
+
+      // Check for event handlers commonly associated with buttons
+      if (elementType === "button" || componentType === "button") {
+        if (content.includes("onclick") || content.includes("onpress")) {
+          score += 3;
+        }
+      }
+
+      // Check for the component being defined in this file
+      if (file.content.includes(`function ${capitalizedType}`) || 
+          file.content.includes(`const ${capitalizedType}`)) {
+        score += 20;
+        matches.push(`defines ${capitalizedType}`);
+      }
+    }
+
+    if (score > 0) {
+      results.push({ path: file.path, score, matches });
+    }
+  }
+
+  // Sort by score descending
+  return results.sort((a, b) => b.score - a.score);
+}
+
 /**
  * Phase 3: Ask LLM to select the best file from actual file list
  * This replaces guessing - the LLM sees the real filenames and picks one
@@ -175,7 +242,8 @@ async function selectBestFileFromList(
   screenshot: string,
   userPrompt: string,
   candidateFiles: string[],
-  apiKey: string
+  apiKey: string,
+  focusedElementHints?: { path: string; score: number; matches: string[] }[]
 ): Promise<string | null> {
   if (candidateFiles.length === 0) return null;
   
@@ -199,7 +267,12 @@ async function selectBestFileFromList(
 
 Here are the actual component files found in this codebase:
 ${candidateFiles.map((f, i) => `${i + 1}. ${f}`).join('\n')}
+${focusedElementHints && focusedElementHints.length > 0 ? `
+FOCUSED ELEMENT ANALYSIS - Files that contain the element the user clicked on:
+${focusedElementHints.slice(0, 3).map(h => `- ${h.path} (confidence: ${h.score}, found: ${h.matches.join(", ")})`).join('\n')}
 
+IMPORTANT: Prefer files from the FOCUSED ELEMENT ANALYSIS above, as they contain the actual element the user wants to modify.
+` : ''}
 Looking at the screenshot, which file MOST LIKELY contains the UI elements the user wants to modify?
 
 IMPORTANT: Return ONLY the exact file path from the list above (e.g., "components/ProcessCatalogue/ProcessDetailPanel.tsx").
@@ -434,43 +507,83 @@ function searchFilesSmart(
   return sortedResults.map(r => ({ path: r.path, content: r.content, score: r.score }));
 }
 
-const VISION_SYSTEM_PROMPT = `You are a code editor. Make ONLY the change the user requested.
+const VISION_SYSTEM_PROMPT = `You are a code editor like Cursor. Before making changes, REASON about what needs to be done.
+
+═══════════════════════════════════════════════════════════════════════════════
+STEP 1: ANALYZE (Think like Cursor)
+═══════════════════════════════════════════════════════════════════════════════
+
+Before writing any patches, analyze the screenshot and answer:
+
+1. CURRENT STATE: What do I see in the screenshot? 
+   - Is the element visible/readable right now?
+   - What colors/styles are currently applied?
+
+2. PROBLEM IDENTIFICATION: What's actually wrong?
+   - Contrast issue? (text blending with background)
+   - Hidden element? (not showing at all)
+   - Hover state issue? (only visible on interaction)
+   - Layout issue? (wrong size/position)
+   - Or is it already correct?
+
+3. FIX STRATEGY: What should I change?
+   - DEFAULT state only (element needs to look different normally)
+   - HOVER state only (element needs different hover effect)
+   - BOTH states (element needs overall visibility improvement)
+   - ASK for clarification (request is too vague)
+
+═══════════════════════════════════════════════════════════════════════════════
+STEP 2: GENERATE PATCHES (Only after reasoning)
+═══════════════════════════════════════════════════════════════════════════════
+
+CRITICAL - FILE SELECTION:
+- You MUST modify the file marked "TARGET COMPONENT" - this is the file you have FULL visibility into
+- Do NOT try to modify other files listed in context - you only see their imports/exports, not full content
+- If the TARGET COMPONENT is not the right file, return clarification_needed
+
+COPY EXACTLY from the TARGET COMPONENT section:
+- Your "search" string must match the file CHARACTER-FOR-CHARACTER
+- Include exact indentation and at least 3 lines of context
+- If the element looks FINE in the screenshot, say so
 
 RULES:
-1. Make the SMALLEST possible change to accomplish the request
-2. Do NOT refactor, rebrand, or "improve" anything else
-3. Do NOT change import statements unless explicitly required
-4. Do NOT change component libraries (e.g., heroui to shadcn)
-5. If fixing a color/visibility issue, change ONLY that element's classes
-6. Your patch should typically be 1-5 lines, not 50+
-7. NEVER invent or guess code - your "search" string MUST match the file EXACTLY
-8. NEVER change data mappings (icon names, keys, enum values) unless user explicitly provides the new values
-9. If you don't know what values exist in a database or data source, DO NOT guess - ask for clarification
-
-CRITICAL - DATA INTEGRITY:
-- If code references database values (like icon_name, type, status), DO NOT change the mapping keys
-- You cannot see database content - only change STRUCTURE, not DATA MAPPINGS
-- Example: If you see iconMap["EyeOff"] = SomeIcon, do NOT change "EyeOff" to something else
-- If user wants different icons, they must tell you the EXACT icon names they want
-
-PATCH FORMAT:
-Return ONLY raw JSON (no markdown, no preamble):
+1. Make the SMALLEST possible change
+2. Do NOT refactor or "improve" other code
+3. NEVER invent code - COPY exact code from file
+4. NEVER change data mappings unless user provides new values
+5. If visibility issue: prefer explicit colors (text-white, text-black) over semantic tokens
+
+═══════════════════════════════════════════════════════════════════════════════
+RESPONSE FORMAT
+═══════════════════════════════════════════════════════════════════════════════
+
+Return ONLY raw JSON:
 {
-  "reasoning": "brief explanation",
+  "analysis": {
+    "currentState": "what I see in the screenshot",
+    "problem": "the actual issue (or 'none - element appears correct')",
+    "fixStrategy": "default|hover|both|clarification_needed"
+  },
+  "reasoning": "my diagnosis and approach",
   "modifications": [{
     "filePath": "path/to/file.tsx",
     "patches": [{
-      "search": "exact original code (copy from provided file)",
-      "replace": "minimal change",
-      "explanation": "what this does"
+      "search": "EXACT copy from file",
+      "replace": "changed code",
+      "explanation": "what this changes and why"
     }],
     "previewCSS": "optional CSS for live preview"
   }],
   "aggregatedPreviewCSS": "combined CSS for all changes",
-  "explanation": "summary"
+  "explanation": "summary of what was changed"
 }
 
-If you cannot find the exact code to modify, OR if you would need to guess data values, return empty modifications array with explanation.`;
+If the element looks correct, return:
+{
+  "analysis": { "currentState": "...", "problem": "none", "fixStrategy": "clarification_needed" },
+  "modifications": [],
+  "explanation": "The element appears visible/correct in the screenshot. Please specify what needs to change."
+}`;
 
 export async function POST(request: Request) {
   // Only allow in development
@@ -575,6 +688,22 @@ export async function POST(request: Request) {
           const searchResults = searchFilesSmart(analysis, projectRoot, 10);
           smartSearchFiles = searchResults.map(r => ({ path: r.path, content: r.content }));
           
+          // PHASE 2.5: Find which files contain the focused element
+          const focusedElementHints = findFilesContainingElement(
+            focusedElements,
+            searchResults.map(r => ({ path: r.path, content: r.content }))
+          );
+          
+          if (focusedElementHints.length > 0) {
+            debugLog("Focused element search results", {
+              topMatches: focusedElementHints.slice(0, 3).map(h => ({
+                path: h.path,
+                score: h.score,
+                matches: h.matches
+              }))
+            });
+          }
+          
           // PHASE 3: Ask LLM to pick the best file from actual file list
           if (searchResults.length > 0) {
             const candidateFiles = searchResults.slice(0, 10).map(r => r.path);
@@ -582,7 +711,8 @@ export async function POST(request: Request) {
               screenshot,
               userPrompt,
               candidateFiles,
-              apiKey
+              apiKey,
+              focusedElementHints
             );
             
             if (selectedFile) {
@@ -749,30 +879,59 @@ ${truncatedContent}${wasTruncated ? "\n// ... (truncated)" : ""}
 
       // ========== THEME DISCOVERY (REFERENCE ONLY) ==========
       // Dynamically discover theme tokens from the target codebase
-      // This is marked as REFERENCE ONLY so the LLM doesn't use it to justify extra changes
       const discoveredTheme = await discoverTheme(projectRoot);
       const themeContext = formatThemeForPrompt(discoveredTheme);
       
+      // Check if this is a visibility-related request
+      const isVisibilityRequest = /visible|can't see|cant see|not visible|hidden|color|contrast/i.test(userPrompt);
+      
       if (discoveredTheme.discoveredFiles.length > 0) {
-        textContent += `
+        // Only include detailed color guidance for visibility requests
+        if (isVisibilityRequest) {
+          // Extract available text color classes from discovered theme
+          const textColorClasses = Object.keys(discoveredTheme.cssVariables)
+            .filter(key => key.includes('foreground') || key.includes('text'))
+            .map(key => `text-${key.replace('--', '').replace(/-/g, '-')}`)
+            .slice(0, 10);
+          
+          textContent += `
 ═══════════════════════════════════════════════════════════════════════════════
-REFERENCE ONLY (do not use this to justify additional changes)
+COLOR FIX GUIDANCE (for visibility issues only)
 ═══════════════════════════════════════════════════════════════════════════════
 
-If you need to pick a color for a VISIBILITY fix, these are safe choices:
-- bg-accent text-white (cyan button with white text)
-- bg-primary text-white (charcoal button with white text)
-- bg-success text-white (green button with white text)
-- bg-destructive text-white (red button with white text)
+AVAILABLE TEXT COLORS (use these for contrast fixes):
+- text-white (always visible on dark backgrounds)
+- text-black (always visible on light backgrounds)
+- text-foreground (theme default)
+- text-primary-foreground (for bg-primary)
+- text-accent-foreground (for bg-accent - CHECK IF THIS HAS GOOD CONTRAST)
+- text-destructive-foreground (for bg-destructive)
+
+SAFE BUTTON PATTERNS:
+- bg-accent text-white (cyan button, guaranteed visible)
+- bg-primary text-white (charcoal button, guaranteed visible)
+- bg-destructive text-white (red button, guaranteed visible)
+- bg-muted text-foreground (gray button, guaranteed visible)
 
-But ONLY use these if the user is asking for a color/visibility change.
-Do NOT rebrand or change other elements to match.
+IMPORTANT: If current code has text-accent-foreground or similar semantic colors
+that result in poor contrast, REPLACE with text-white or text-black.
 
 `;
+        } else {
+          // For non-visibility requests, minimal reference
+          textContent += `
+═══════════════════════════════════════════════════════════════════════════════
+REFERENCE ONLY (do not use this to justify additional changes)
+═══════════════════════════════════════════════════════════════════════════════
+Theme discovered from: ${discoveredTheme.discoveredFiles.join(', ')}
+`;
+        }
+        
         debugLog("Theme discovery complete", {
           filesFound: discoveredTheme.discoveredFiles,
           cssVariableCount: Object.keys(discoveredTheme.cssVariables).length,
           tailwindColorCount: Object.keys(discoveredTheme.tailwindColors).length,
+          isVisibilityRequest,
         });
       }
 
@@ -913,6 +1072,11 @@ This is better than generating patches with made-up code.`,
 
         // Parse AI response - now expecting patches instead of full file content
         let aiResponse: {
+          analysis?: {
+            currentState?: string;
+            problem?: string;
+            fixStrategy?: string;
+          };
           reasoning?: string;
           modifications: Array<{
             filePath: string;
@@ -964,10 +1128,31 @@ This is better than generating patches with made-up code.`,
           );
         }
 
+        // Log the LLM's analysis/reasoning (like Cursor showing its thought process)
+        if (aiResponse.analysis) {
+          debugLog("LLM Analysis (Step 1)", {
+            currentState: aiResponse.analysis.currentState,
+            problem: aiResponse.analysis.problem,
+            fixStrategy: aiResponse.analysis.fixStrategy,
+          });
+        }
+
         finalExplanation = aiResponse.explanation;
         finalReasoning = aiResponse.reasoning;
         finalAggregatedCSS = aiResponse.aggregatedPreviewCSS;
 
+        // If LLM says clarification is needed, return that to the user
+        if (aiResponse.analysis?.fixStrategy === "clarification_needed" && 
+            (!aiResponse.modifications || aiResponse.modifications.length === 0)) {
+          return NextResponse.json({
+            success: true,
+            needsClarification: true,
+            analysis: aiResponse.analysis,
+            explanation: aiResponse.explanation || "The element appears correct. Please specify what needs to change.",
+            modifications: [],
+          });
+        }
+
         debugLog("VALIDATION: Known file paths from page context", {
           pageFile: pageContext.pageFile,
           knownPaths: Array.from(knownPaths),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sonance-brand-mcp",
-  "version": "1.3.58",
+  "version": "1.3.60",
   "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",