sonance-brand-mcp 1.3.91 → 1.3.93

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

@@ -19,6 +19,20 @@ import * as babelParser from "@babel/parser";
  * DEVELOPMENT ONLY.
  */
 
+/** Parent section context for section-level targeting */
+interface ParentSectionInfo {
+  /** Semantic container type (section, article, form, card, dialog, etc.) */
+  type: string;
+  /** Key text content in the section (first heading, labels) */
+  sectionText?: string;
+  /** The parent container's className for code matching */
+  className?: string;
+  /** Coordinates of the parent section */
+  coordinates?: { x: number; y: number; width: number; height: number };
+  /** Parent's element ID if available */
+  elementId?: string;
+}
+
 interface VisionFocusedElement {
   name: string;
   type: string;
@@ -38,6 +52,8 @@ interface VisionFocusedElement {
   elementId?: string;
   /** IDs of child elements for more precise targeting */
   childIds?: string[];
+  /** Parent section context for section-level changes */
+  parentSection?: ParentSectionInfo;
 }
 
 interface VisionFileModification {
@@ -500,6 +516,50 @@ function findElementLineInFile(
   return null;
 }
 
+/**
+ * Search imported component files for the focused element
+ * Reuses findElementLineInFile() for consistent detection
+ * 
+ * This is called when the element cannot be found in the main target file,
+ * allowing us to redirect to the actual file containing the element.
+ */
+function findElementInImportedFiles(
+  focusedElement: VisionFocusedElement,
+  importedFiles: { path: string; content: string }[]
+): { path: string; lineNumber: number; matchedBy: string; content: string; confidence: string } | null {
+  debugLog("Searching imported components for element", {
+    elementType: focusedElement.type,
+    textContent: focusedElement.textContent?.substring(0, 30),
+    filesCount: importedFiles.length
+  });
+  
+  for (const file of importedFiles) {
+    // Focus on component files (where UI elements live)
+    // Skip types, stores, utils, hooks - they don't contain JSX elements
+    if (!file.path.includes('components/') && !file.path.includes('/ui/')) continue;
+    
+    const result = findElementLineInFile(file.content, focusedElement);
+    if (result && result.confidence !== 'low') {
+      debugLog("Found element in imported component", {
+        path: file.path,
+        lineNumber: result.lineNumber,
+        matchedBy: result.matchedBy,
+        confidence: result.confidence
+      });
+      return {
+        path: file.path,
+        lineNumber: result.lineNumber,
+        matchedBy: result.matchedBy,
+        content: file.content,
+        confidence: result.confidence
+      };
+    }
+  }
+  
+  debugLog("Element not found in any imported component files");
+  return null;
+}
+
 /**
  * PHASE 0: Deterministic Element ID Search (Cursor-style)
  * Grep entire codebase for the element ID. If found in multiple files,
@@ -1604,6 +1664,8 @@ User Request: "${userPrompt}"
         // Search for focused element in the file using multiple strategies
         // Priority: DOM id > textContent > className patterns
         let elementLocation: { lineNumber: number; snippet: string; confidence: 'high' | 'medium' | 'low'; matchedBy: string } | null = null;
+        let actualTargetFile = recommendedFileContent; // May change if we redirect
+        
         if (focusedElements && focusedElements.length > 0) {
           for (const el of focusedElements) {
             elementLocation = findElementLineInFile(content, el);
@@ -1617,6 +1679,35 @@ User Request: "${userPrompt}"
               break;
             }
           }
+          
+          // DYNAMIC IMPORT SEARCH: If not found in main file, search imported components
+          if (!elementLocation) {
+            debugLog("Element not in main file, searching imported components...", {
+              mainFile: recommendedFileContent.path,
+              importedFilesCount: pageContext.componentSources.length
+            });
+            
+            const importedMatch = findElementInImportedFiles(
+              focusedElements[0],
+              pageContext.componentSources
+            );
+            
+            if (importedMatch) {
+              debugLog("REDIRECT: Element found in imported component", {
+                originalFile: recommendedFileContent.path,
+                redirectTo: importedMatch.path,
+                matchedBy: importedMatch.matchedBy,
+                lineNumber: importedMatch.lineNumber
+              });
+              
+              // Switch target file to where element actually is
+              actualTargetFile = {
+                path: importedMatch.path,
+                content: importedMatch.content
+              };
+              elementLocation = findElementLineInFile(importedMatch.content, focusedElements[0]);
+            }
+          }
         }
         
         // Build focused elements section with precise targeting info
@@ -1628,6 +1719,36 @@ User Request: "${userPrompt}"
               textContent += ` with text "${el.textContent.substring(0, 30)}"`;
             }
             textContent += `\n`;
+            
+            // Include parent section context for section-level targeting
+            if (el.parentSection) {
+              textContent += `  └─ Parent Section: <${el.parentSection.type}>`;
+              if (el.parentSection.sectionText) {
+                textContent += ` containing "${el.parentSection.sectionText.substring(0, 60)}${el.parentSection.sectionText.length > 60 ? '...' : ''}"`;
+              }
+              if (el.parentSection.elementId) {
+                textContent += ` (id="${el.parentSection.elementId}")`;
+              }
+              if (el.parentSection.className) {
+                // Show first 80 chars of className for context
+                const truncatedClass = el.parentSection.className.length > 80 
+                  ? el.parentSection.className.substring(0, 80) + '...'
+                  : el.parentSection.className;
+                textContent += `\n     className="${truncatedClass}"`;
+              }
+              textContent += `\n`;
+            }
+          }
+          
+          // Detect section-level prompts and provide guidance
+          const sectionKeywords = ['section', 'area', 'container', 'card', 'panel', 'header', 'form', 'region', 'compact', 'modernize', 'redesign', 'layout'];
+          const isSectionLevelChange = sectionKeywords.some(kw => userPrompt?.toLowerCase().includes(kw));
+          if (isSectionLevelChange && focusedElements.some(el => el.parentSection)) {
+            textContent += `
+📍 SECTION-LEVEL CHANGE DETECTED: The user's prompt mentions section/area keywords.
+   If modifying the parent section (not just the clicked element), target the container
+   mentioned above. Look for elements matching the section className or id.
+`;
           }
           
           // Add precise targeting with line number and snippet
@@ -1649,10 +1770,11 @@ ${elementLocation.snippet}
 
 `;
           } else {
-            textContent += `\n`;
-            debugLog("WARNING: Could not locate focused element in file", {
-              file: recommendedFileContent.path,
-              hint: "The clicked element may be rendered by a child component (e.g., DialogContent, Button component). Check the component's source file instead.",
+            // Element NOT found in main file OR any imported components
+            // BLOCK the LLM from guessing - require empty modifications
+            debugLog("BLOCK: Could not locate focused element anywhere", {
+              mainFile: recommendedFileContent.path,
+              searchedImports: pageContext.componentSources.length,
               focusedElements: focusedElements.map(el => ({
                 name: el.name,
                 type: el.type,
@@ -1662,27 +1784,38 @@ ${elementLocation.snippet}
               }))
             });
             
-            // Add a hint to the LLM that we couldn't precisely locate the element
+            // STRONG BLOCK instruction - tell LLM to NOT guess
             textContent += `
-⚠️  WARNING: Could not precisely locate the clicked element in this file.
+⛔ STOP: CANNOT LOCATE THE CLICKED ELEMENT
+
+The user clicked on a specific element, but it could NOT be found in:
+- ${recommendedFileContent.path} (main target file)
+- Any of the ${pageContext.componentSources.length} imported component files
+
 The element may be:
-  - Rendered by a child component (e.g., DialogContent, Button)
-  - Dynamically generated
-  - In a different file imported by this component
+- Deeply nested in a component not in the import tree
+- Dynamically generated at runtime
+- Part of a third-party library component
 
-Please proceed with caution and verify you're modifying the correct element.
+DO NOT GUESS. Return this exact response:
+{
+  "modifications": [],
+  "explanation": "Could not locate the clicked element in this file or any of its ${pageContext.componentSources.length} imported components. The element may be rendered by a deeply nested or third-party component."
+}
 
 `;
           }
         }
         
         // Add line numbers to make it easy for LLM to reference exact code
-        const linesWithNumbers = content.split('\n').map((line, i) => 
+        // Use actualTargetFile which may have been redirected to an imported component
+        const targetContent = actualTargetFile.content;
+        const linesWithNumbers = targetContent.split('\n').map((line, i) => 
           `${String(i + 1).padStart(4, ' ')}| ${line}`
         ).join('\n');
         
         textContent += `═══════════════════════════════════════════════════════════════════════════════
-FILE TO EDIT: ${recommendedFileContent.path}
+FILE TO EDIT: ${actualTargetFile.path}
 ═══════════════════════════════════════════════════════════════════════════════
 
 IMPORTANT: Copy code EXACTLY as shown below (including line numbers for reference).
@@ -1693,11 +1826,12 @@ ${linesWithNumbers}
 \`\`\`
 
 `;
-        usedContext += content.length;
+        usedContext += targetContent.length;
         debugLog("Added TARGET COMPONENT with line numbers", { 
-          path: recommendedFileContent.path, 
-          lines: content.split('\n').length,
-          size: content.length 
+          path: actualTargetFile.path, 
+          lines: targetContent.split('\n').length,
+          size: targetContent.length,
+          wasRedirected: actualTargetFile.path !== recommendedFileContent.path
         });
       } else if (pageContext.pageContent) {
         // Fallback: use page file if no recommended file

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

@@ -18,6 +18,20 @@ import * as babelParser from "@babel/parser";
  * DEVELOPMENT ONLY.
  */
 
+/** Parent section context for section-level targeting */
+interface ParentSectionInfo {
+  /** Semantic container type (section, article, form, card, dialog, etc.) */
+  type: string;
+  /** Key text content in the section (first heading, labels) */
+  sectionText?: string;
+  /** The parent container's className for code matching */
+  className?: string;
+  /** Coordinates of the parent section */
+  coordinates?: { x: number; y: number; width: number; height: number };
+  /** Parent's element ID if available */
+  elementId?: string;
+}
+
 interface VisionFocusedElement {
   name: string;
   type: string;
@@ -37,6 +51,8 @@ interface VisionFocusedElement {
   elementId?: string;
   /** IDs of child elements for more precise targeting */
   childIds?: string[];
+  /** Parent section context for section-level changes */
+  parentSection?: ParentSectionInfo;
 }
 
 interface VisionFileModification {
@@ -496,6 +512,50 @@ function findElementLineInFile(
   return null;
 }
 
+/**
+ * Search imported component files for the focused element
+ * Reuses findElementLineInFile() for consistent detection
+ * 
+ * This is called when the element cannot be found in the main target file,
+ * allowing us to redirect to the actual file containing the element.
+ */
+function findElementInImportedFiles(
+  focusedElement: VisionFocusedElement,
+  importedFiles: { path: string; content: string }[]
+): { path: string; lineNumber: number; matchedBy: string; content: string; confidence: string } | null {
+  debugLog("Searching imported components for element", {
+    elementType: focusedElement.type,
+    textContent: focusedElement.textContent?.substring(0, 30),
+    filesCount: importedFiles.length
+  });
+  
+  for (const file of importedFiles) {
+    // Focus on component files (where UI elements live)
+    // Skip types, stores, utils, hooks - they don't contain JSX elements
+    if (!file.path.includes('components/') && !file.path.includes('/ui/')) continue;
+    
+    const result = findElementLineInFile(file.content, focusedElement);
+    if (result && result.confidence !== 'low') {
+      debugLog("Found element in imported component", {
+        path: file.path,
+        lineNumber: result.lineNumber,
+        matchedBy: result.matchedBy,
+        confidence: result.confidence
+      });
+      return {
+        path: file.path,
+        lineNumber: result.lineNumber,
+        matchedBy: result.matchedBy,
+        content: file.content,
+        confidence: result.confidence
+      };
+    }
+  }
+  
+  debugLog("Element not found in any imported component files");
+  return null;
+}
+
 /**
  * PHASE 0: Deterministic Element ID Search (Cursor-style)
  * Grep entire codebase for the element ID. If found in multiple files,
@@ -1573,6 +1633,8 @@ User Request: "${userPrompt}"
         // Search for focused element in the file using multiple strategies
         // Priority: DOM id > textContent > className patterns
         let elementLocation: { lineNumber: number; snippet: string; confidence: 'high' | 'medium' | 'low'; matchedBy: string } | null = null;
+        let actualTargetFile = recommendedFileContent; // May change if we redirect
+        
         if (focusedElements && focusedElements.length > 0) {
           for (const el of focusedElements) {
             elementLocation = findElementLineInFile(content, el);
@@ -1586,6 +1648,35 @@ User Request: "${userPrompt}"
               break;
             }
           }
+          
+          // DYNAMIC IMPORT SEARCH: If not found in main file, search imported components
+          if (!elementLocation) {
+            debugLog("Element not in main file, searching imported components...", {
+              mainFile: recommendedFileContent.path,
+              importedFilesCount: pageContext.componentSources.length
+            });
+            
+            const importedMatch = findElementInImportedFiles(
+              focusedElements[0],
+              pageContext.componentSources
+            );
+            
+            if (importedMatch) {
+              debugLog("REDIRECT: Element found in imported component", {
+                originalFile: recommendedFileContent.path,
+                redirectTo: importedMatch.path,
+                matchedBy: importedMatch.matchedBy,
+                lineNumber: importedMatch.lineNumber
+              });
+              
+              // Switch target file to where element actually is
+              actualTargetFile = {
+                path: importedMatch.path,
+                content: importedMatch.content
+              };
+              elementLocation = findElementLineInFile(importedMatch.content, focusedElements[0]);
+            }
+          }
         }
         
         // Build focused elements section with precise targeting info
@@ -1597,6 +1688,36 @@ User Request: "${userPrompt}"
               textContent += ` with text "${el.textContent.substring(0, 30)}"`;
             }
             textContent += `\n`;
+            
+            // Include parent section context for section-level targeting
+            if (el.parentSection) {
+              textContent += `  └─ Parent Section: <${el.parentSection.type}>`;
+              if (el.parentSection.sectionText) {
+                textContent += ` containing "${el.parentSection.sectionText.substring(0, 60)}${el.parentSection.sectionText.length > 60 ? '...' : ''}"`;
+              }
+              if (el.parentSection.elementId) {
+                textContent += ` (id="${el.parentSection.elementId}")`;
+              }
+              if (el.parentSection.className) {
+                // Show first 80 chars of className for context
+                const truncatedClass = el.parentSection.className.length > 80 
+                  ? el.parentSection.className.substring(0, 80) + '...'
+                  : el.parentSection.className;
+                textContent += `\n     className="${truncatedClass}"`;
+              }
+              textContent += `\n`;
+            }
+          }
+          
+          // Detect section-level prompts and provide guidance
+          const sectionKeywords = ['section', 'area', 'container', 'card', 'panel', 'header', 'form', 'region', 'compact', 'modernize', 'redesign', 'layout'];
+          const isSectionLevelChange = sectionKeywords.some(kw => userPrompt?.toLowerCase().includes(kw));
+          if (isSectionLevelChange && focusedElements.some(el => el.parentSection)) {
+            textContent += `
+📍 SECTION-LEVEL CHANGE DETECTED: The user's prompt mentions section/area keywords.
+   If modifying the parent section (not just the clicked element), target the container
+   mentioned above. Look for elements matching the section className or id.
+`;
           }
           
           // Add precise targeting with line number and snippet
@@ -1618,10 +1739,11 @@ ${elementLocation.snippet}
 
 `;
           } else {
-            textContent += `\n`;
-            debugLog("WARNING: Could not locate focused element in file", {
-              file: recommendedFileContent.path,
-              hint: "The clicked element may be rendered by a child component (e.g., DialogContent, Button component). Check the component's source file instead.",
+            // Element NOT found in main file OR any imported components
+            // BLOCK the LLM from guessing - require empty modifications
+            debugLog("BLOCK: Could not locate focused element anywhere", {
+              mainFile: recommendedFileContent.path,
+              searchedImports: pageContext.componentSources.length,
               focusedElements: focusedElements.map(el => ({
                 name: el.name,
                 type: el.type,
@@ -1631,27 +1753,38 @@ ${elementLocation.snippet}
               }))
             });
             
-            // Add a hint to the LLM that we couldn't precisely locate the element
+            // STRONG BLOCK instruction - tell LLM to NOT guess
             textContent += `
-⚠️  WARNING: Could not precisely locate the clicked element in this file.
+⛔ STOP: CANNOT LOCATE THE CLICKED ELEMENT
+
+The user clicked on a specific element, but it could NOT be found in:
+- ${recommendedFileContent.path} (main target file)
+- Any of the ${pageContext.componentSources.length} imported component files
+
 The element may be:
-  - Rendered by a child component (e.g., DialogContent, Button)
-  - Dynamically generated
-  - In a different file imported by this component
+- Deeply nested in a component not in the import tree
+- Dynamically generated at runtime
+- Part of a third-party library component
 
-Please proceed with caution and verify you're modifying the correct element.
+DO NOT GUESS. Return this exact response:
+{
+  "modifications": [],
+  "explanation": "Could not locate the clicked element in this file or any of its ${pageContext.componentSources.length} imported components. The element may be rendered by a deeply nested or third-party component."
+}
 
 `;
           }
         }
         
         // Add line numbers to make it easy for LLM to reference exact code
-        const linesWithNumbers = content.split('\n').map((line, i) => 
+        // Use actualTargetFile which may have been redirected to an imported component
+        const targetContent = actualTargetFile.content;
+        const linesWithNumbers = targetContent.split('\n').map((line, i) => 
           `${String(i + 1).padStart(4, ' ')}| ${line}`
         ).join('\n');
         
         textContent += `═══════════════════════════════════════════════════════════════════════════════
-FILE TO EDIT: ${recommendedFileContent.path}
+FILE TO EDIT: ${actualTargetFile.path}
 ═══════════════════════════════════════════════════════════════════════════════
 
 IMPORTANT: Copy code EXACTLY as shown below (including line numbers for reference).
@@ -1662,11 +1795,12 @@ ${linesWithNumbers}
 \`\`\`
 
 `;
-        usedContext += content.length;
+        usedContext += targetContent.length;
         debugLog("Added TARGET COMPONENT with line numbers", { 
-          path: recommendedFileContent.path, 
-          lines: content.split('\n').length,
-          size: content.length 
+          path: actualTargetFile.path, 
+          lines: targetContent.split('\n').length,
+          size: targetContent.length,
+          wasRedirected: actualTargetFile.path !== recommendedFileContent.path 
         });
       } else if (pageContext.pageContent) {
         // Fallback: use page file if no recommended file

package/dist/assets/dev-tools/SonanceDevTools.tsx

@@ -48,6 +48,7 @@ import {
   ApplyFirstStatus,
   TextOverride,
   OriginalTextState,
+  ParentSectionInfo,
 } from "./types";
 import {
   tabs,
@@ -71,6 +72,7 @@ import { InspectorOverlay } from "./components/InspectorOverlay";
 import { ChatInterface } from "./components/ChatInterface";
 import { DiffPreview } from "./components/DiffPreview";
 import { VisionModeBorder } from "./components/VisionModeBorder";
+import { SectionHighlight } from "./components/SectionHighlight";
 import { AnalysisPanel } from "./panels/AnalysisPanel";
 import { TextPanel } from "./panels/TextPanel";
 import { LogoToolsPanel } from "./panels/LogoToolsPanel";
@@ -82,6 +84,100 @@ import { ComponentsPanel } from "./panels/ComponentsPanel";
 // A floating development overlay for brand theming
 // ============================================
 
+// ---- Helper Functions ----
+
+/**
+ * Extract the first meaningful heading or text content from a section
+ */
+function extractSectionHeading(container: Element): string | undefined {
+  // Look for headings first
+  const heading = container.querySelector('h1, h2, h3, h4, h5, h6');
+  if (heading && heading.textContent) {
+    const text = heading.textContent.trim();
+    // Return first 100 chars max
+    return text.length > 100 ? text.substring(0, 100) + '...' : text;
+  }
+  
+  // Look for labels or title elements
+  const label = container.querySelector('label, [class*="title"], [class*="heading"]');
+  if (label && label.textContent) {
+    const text = label.textContent.trim();
+    return text.length > 100 ? text.substring(0, 100) + '...' : text;
+  }
+  
+  // Look for aria-label or title attribute
+  const ariaLabel = container.getAttribute('aria-label');
+  if (ariaLabel) return ariaLabel;
+  
+  const title = container.getAttribute('title');
+  if (title) return title;
+  
+  return undefined;
+}
+
+/**
+ * Find the nearest meaningful parent section/container for an element
+ * This helps the AI understand the broader context when making section-level changes
+ */
+function findParentSection(element: Element): ParentSectionInfo | undefined {
+  // Selectors for common section-like containers
+  const sectionSelectors = [
+    'section', 'article', 'form', 'dialog', 'aside', 'header', 'footer', 'main',
+    '[role="dialog"]', '[role="region"]', '[role="form"]', '[role="main"]',
+    '[role="complementary"]', '[role="banner"]', '[role="contentinfo"]'
+  ];
+  
+  // Class patterns that indicate section-like containers
+  const sectionClassPatterns = /\b(card|panel|section|container|modal|drawer|header|footer|sidebar|content|wrapper|box|block|group|region|area)\b/i;
+  
+  let current = element.parentElement;
+  let depth = 0;
+  const maxDepth = 10; // Don't traverse too far up
+  
+  while (current && current !== document.body && depth < maxDepth) {
+    // Skip DevTools elements
+    if (current.hasAttribute('data-sonance-devtools')) {
+      current = current.parentElement;
+      depth++;
+      continue;
+    }
+    
+    // Check if current matches a section-like container
+    const matchesSelector = sectionSelectors.some(sel => {
+      try {
+        return current!.matches(sel);
+      } catch {
+        return false;
+      }
+    });
+    
+    const matchesClassPattern = current.className && sectionClassPatterns.test(current.className);
+    
+    if (matchesSelector || matchesClassPattern) {
+      const rect = current.getBoundingClientRect();
+      // Store document-relative coordinates (add scroll offset)
+      // This ensures the highlight stays with the section when scrolling
+      return {
+        type: current.tagName.toLowerCase(),
+        sectionText: extractSectionHeading(current),
+        className: current.className || undefined,
+        coordinates: {
+          x: rect.left + window.scrollX,
+          y: rect.top + window.scrollY,
+          width: rect.width,
+          height: rect.height,
+        },
+        elementId: current.id || undefined,
+      };
+    }
+    
+    current = current.parentElement;
+    depth++;
+  }
+  
+  return undefined;
+}
+
 // ---- Main Component ----
 
 export function SonanceDevTools() {
@@ -1079,6 +1175,24 @@ export function SonanceDevTools() {
   const handleVisionElementClick = useCallback((element: DetectedElement) => {
     if (!visionModeActive) return;
 
+    // Find the actual DOM element using coordinates (center of the element)
+    const centerX = element.rect.left + element.rect.width / 2;
+    const centerY = element.rect.top + element.rect.height / 2;
+    const domElement = document.elementFromPoint(centerX, centerY);
+    
+    // Find parent section context for section-level targeting
+    let parentSection: ParentSectionInfo | undefined;
+    if (domElement) {
+      parentSection = findParentSection(domElement);
+      if (parentSection) {
+        console.log("[Vision Mode] Captured parent section:", {
+          type: parentSection.type,
+          sectionText: parentSection.sectionText?.substring(0, 50),
+          elementId: parentSection.elementId,
+        });
+      }
+    }
+
     const focusedElement: VisionFocusedElement = {
       name: element.name,
       type: element.type,
@@ -1095,6 +1209,8 @@ export function SonanceDevTools() {
       // Capture element ID and child IDs for precise code targeting
       elementId: element.elementId,
       childIds: element.childIds,
+      // Parent section context for section-level changes
+      parentSection,
     };
 
     setVisionFocusedElements((prev) => {
@@ -2707,6 +2823,11 @@ export function SonanceDevTools() {
         active={visionModeActive}
         focusedCount={visionFocusedElements.length}
       />
+      {/* Section Highlight - shows detected parent section when element is clicked */}
+      <SectionHighlight
+        active={visionModeActive}
+        focusedElements={visionFocusedElements}
+      />
       {/* Visual Inspector Overlay - switches to preview mode when AI changes are pending */}
       {(inspectorEnabled || isPreviewActive || visionModeActive || changedElements.length > 0 || (viewMode === "inspector" && selectedComponentType !== "all")) && filteredOverlayElements.length > 0 && (
         <InspectorOverlay

package/dist/assets/dev-tools/components/ChatInterface.tsx

@@ -1,11 +1,59 @@
 "use client";
 
 import React, { useState, useEffect, useCallback, useRef } from "react";
-import { Loader2, Send, Sparkles, Eye } from "lucide-react";
+import { Loader2, Send, Sparkles, Eye, AlertCircle, X } from "lucide-react";
 import { cn } from "../../../lib/utils";
 import { ChatMessage, AIEditResult, PendingEdit, VisionFocusedElement, VisionPendingEdit, ApplyFirstSession } from "../types";
 import html2canvas from "html2canvas-pro";
 
+// Helper to detect location failure in explanation
+function isLocationFailure(explanation: string | undefined): boolean {
+  if (!explanation) return false;
+  const lowerExplanation = explanation.toLowerCase();
+  return (
+    lowerExplanation.includes('could not locate') ||
+    lowerExplanation.includes('element_not_found') ||
+    lowerExplanation.includes('cannot find the clicked element') ||
+    lowerExplanation.includes('unable to locate') ||
+    lowerExplanation.includes('could not find the element')
+  );
+}
+
+/**
+ * Draw a section highlight border on a screenshot image
+ * This helps the LLM visually identify the target section for modifications
+ */
+function drawSectionHighlight(
+  screenshotDataUrl: string,
+  sectionCoords: { x: number; y: number; width: number; height: number }
+): Promise<string> {
+  return new Promise((resolve) => {
+    const img = new Image();
+    img.onload = () => {
+      const canvas = document.createElement('canvas');
+      canvas.width = img.width;
+      canvas.height = img.height;
+      const ctx = canvas.getContext('2d')!;
+      
+      // Draw original screenshot
+      ctx.drawImage(img, 0, 0);
+      
+      // Draw section highlight border (teal/cyan to match Sonance brand)
+      ctx.strokeStyle = '#00D3C8';
+      ctx.lineWidth = 3;
+      ctx.setLineDash([8, 4]); // Dashed line for visibility
+      ctx.strokeRect(sectionCoords.x, sectionCoords.y, sectionCoords.width, sectionCoords.height);
+      
+      // Semi-transparent fill to subtly highlight the area
+      ctx.fillStyle = 'rgba(0, 211, 200, 0.08)';
+      ctx.fillRect(sectionCoords.x, sectionCoords.y, sectionCoords.width, sectionCoords.height);
+      
+      resolve(canvas.toDataURL('image/png', 0.8));
+    };
+    img.src = screenshotDataUrl;
+  });
+}
+
 // Variant styles captured from the DOM
 export interface VariantStyles {
   backgroundColor: string;
@@ -56,8 +104,17 @@ export function ChatInterface({
   const [messages, setMessages] = useState<ChatMessage[]>([]);
   const [input, setInput] = useState("");
   const [isProcessing, setIsProcessing] = useState(false);
+  const [toastMessage, setToastMessage] = useState<{ message: string; type: 'error' | 'warning' } | null>(null);
   const messagesEndRef = useRef<HTMLDivElement>(null);
   const inputRef = useRef<HTMLInputElement>(null);
+  
+  // Auto-dismiss toast after 5 seconds
+  useEffect(() => {
+    if (toastMessage) {
+      const timer = setTimeout(() => setToastMessage(null), 5000);
+      return () => clearTimeout(timer);
+    }
+  }, [toastMessage]);
 
   // Scroll to bottom when messages change
   useEffect(() => {
@@ -133,8 +190,22 @@ export function ChatInterface({
     try {
       // Capture screenshot
       console.log("[Vision Mode] Capturing screenshot...");
-      const screenshot = await captureScreenshot();
-      console.log("[Vision Mode] Screenshot captured:", screenshot ? `${screenshot.length} bytes` : "null");
+      const rawScreenshot = await captureScreenshot();
+      console.log("[Vision Mode] Screenshot captured:", rawScreenshot ? `${rawScreenshot.length} bytes` : "null");
+
+      // Annotate screenshot with section highlight if parent section exists
+      // This helps the LLM visually identify the target area for modifications
+      let screenshot = rawScreenshot;
+      if (rawScreenshot && visionFocusedElements.length > 0) {
+        const parentSection = visionFocusedElements[0].parentSection;
+        if (parentSection?.coordinates) {
+          screenshot = await drawSectionHighlight(rawScreenshot, parentSection.coordinates);
+          console.log("[Vision Mode] Added section highlight to screenshot:", {
+            sectionType: parentSection.type,
+            sectionText: parentSection.sectionText?.substring(0, 30),
+          });
+        }
+      }
 
       // Choose API endpoint based on mode
       const endpoint = useApplyFirst ? "/api/sonance-vision-apply" : "/api/sonance-vision-edit";
@@ -162,20 +233,49 @@ export function ChatInterface({
         error: data.error,
       });
 
+      // Check if this is a "location failure" case - element could not be found in code
+      const hasLocationFailure = isLocationFailure(data.explanation);
+      const hasNoModifications = !data.modifications || data.modifications.length === 0;
+      const isElementNotFound = hasLocationFailure && hasNoModifications;
+
+      // Build appropriate message based on result
+      let messageContent: string;
+      if (isElementNotFound) {
+        // Element not found - provide helpful guidance
+        messageContent = (data.explanation || "Could not locate the clicked element in the source code.") +
+          "\n\nTry clicking on a different element or describe what you want to change in more detail.";
+      } else if (data.success) {
+        messageContent = useApplyFirst
+          ? data.explanation || "Changes applied! Review and accept or revert."
+          : data.explanation || "Vision mode changes ready for preview.";
+      } else {
+        messageContent = data.error || "Failed to generate changes.";
+      }
+
       const assistantMessage: ChatMessage = {
         id: `msg-${Date.now()}-response`,
         role: "assistant",
-        content: data.success
-          ? useApplyFirst
-            ? data.explanation || "Changes applied! Review and accept or revert."
-            : data.explanation || "Vision mode changes ready for preview."
-          : data.error || "Failed to generate changes.",
+        content: messageContent,
         timestamp: new Date(),
       };
 
       setMessages((prev) => [...prev, assistantMessage]);
 
-      if (data.success && data.modifications) {
+      // Handle element not found case - show toast and do NOT trigger page refresh
+      if (isElementNotFound) {
+        console.log("[Vision Mode] Element not found - blocking page refresh:", {
+          explanation: data.explanation,
+          modifications: data.modifications?.length || 0,
+        });
+        setToastMessage({
+          message: "Could not locate the clicked element in the source code",
+          type: 'warning'
+        });
+        // Do NOT call onApplyFirstComplete - this prevents page refresh
+        return;
+      }
+
+      if (data.success && data.modifications && data.modifications.length > 0) {
         if (useApplyFirst && onApplyFirstComplete) {
           // Apply-First mode: files are already written, user can see changes via HMR
           console.log("[Apply-First] Calling onApplyFirstComplete with:", {
@@ -344,6 +444,27 @@ export function ChatInterface({
 
   return (
     <div className="space-y-3">
+      {/* Toast Notification */}
+      {toastMessage && (
+        <div 
+          className={cn(
+            "flex items-center gap-2 p-3 rounded-md text-sm animate-in slide-in-from-top-2",
+            toastMessage.type === 'error' 
+              ? "bg-red-50 border border-red-200 text-red-700"
+              : "bg-amber-50 border border-amber-200 text-amber-700"
+          )}
+        >
+          <AlertCircle className="h-4 w-4 flex-shrink-0" />
+          <span className="flex-1">{toastMessage.message}</span>
+          <button 
+            onClick={() => setToastMessage(null)}
+            className="p-0.5 hover:bg-black/5 rounded"
+          >
+            <X className="h-3 w-3" />
+          </button>
+        </div>
+      )}
+
       {/* Vision Mode Banner */}
       {visionMode && (
         <div className="p-2 bg-purple-50 border border-purple-200 rounded-md">

package/dist/assets/dev-tools/components/SectionHighlight.tsx

@@ -0,0 +1,124 @@
+"use client";
+
+import React, { useEffect, useState } from "react";
+import { createPortal } from "react-dom";
+import { Box } from "lucide-react";
+import type { VisionFocusedElement } from "../types";
+
+interface SectionHighlightProps {
+  /** Whether vision mode is active */
+  active: boolean;
+  /** The focused elements that may have parent section info */
+  focusedElements: VisionFocusedElement[];
+}
+
+/**
+ * SectionHighlight renders a visible dashed border around the detected
+ * parent section when a user clicks an element in vision mode.
+ * This provides visual feedback so users can verify the correct section
+ * will be targeted by the AI.
+ */
+export function SectionHighlight({ active, focusedElements }: SectionHighlightProps) {
+  const [mounted, setMounted] = useState(false);
+
+  useEffect(() => {
+    setMounted(true);
+    return () => setMounted(false);
+  }, []);
+
+  if (!active || !mounted) return null;
+
+  // Find the first focused element with parent section coordinates
+  const elementWithSection = focusedElements.find(
+    (el) => el.parentSection?.coordinates
+  );
+
+  if (!elementWithSection?.parentSection?.coordinates) return null;
+
+  const { coordinates, type, sectionText, elementId } = elementWithSection.parentSection;
+
+  // Coordinates are already document-relative (scroll offset added at capture time)
+  // so we can use them directly with absolute positioning
+
+  // Build the label text
+  let labelText = `<${type}>`;
+  if (sectionText) {
+    const truncatedText = sectionText.length > 40 
+      ? sectionText.substring(0, 40) + "..." 
+      : sectionText;
+    labelText += ` "${truncatedText}"`;
+  }
+  if (elementId) {
+    labelText += ` #${elementId}`;
+  }
+
+  return createPortal(
+    <>
+      {/* Section border overlay - uses absolute positioning to stay with content on scroll */}
+      <div
+        data-section-highlight="true"
+        style={{
+          position: "absolute",
+          top: coordinates.y,
+          left: coordinates.x,
+          width: coordinates.width,
+          height: coordinates.height,
+          pointerEvents: "none",
+          zIndex: 9995, // Below VisionModeBorder (9996)
+          border: "3px dashed #00D3C8",
+          borderRadius: "4px",
+          backgroundColor: "rgba(0, 211, 200, 0.06)",
+          boxShadow: "0 0 0 1px rgba(0, 211, 200, 0.3), inset 0 0 20px rgba(0, 211, 200, 0.05)",
+          transition: "all 0.2s ease-out",
+        }}
+      >
+        {/* Section label */}
+        <div
+          style={{
+            position: "absolute",
+            top: "-28px",
+            left: "0",
+            display: "flex",
+            alignItems: "center",
+            gap: "6px",
+            backgroundColor: "#00D3C8",
+            color: "#1a1a1a",
+            padding: "4px 10px",
+            borderRadius: "4px",
+            fontSize: "11px",
+            fontWeight: 600,
+            fontFamily: "'Montserrat', system-ui, -apple-system, sans-serif",
+            boxShadow: "0 2px 8px rgba(0, 211, 200, 0.4)",
+            whiteSpace: "nowrap",
+            maxWidth: "350px",
+            overflow: "hidden",
+            textOverflow: "ellipsis",
+          }}
+        >
+          <Box size={12} />
+          <span>Section: {labelText}</span>
+        </div>
+
+        {/* Corner markers for emphasis */}
+        {[
+          { top: -2, left: -2, borderTop: "3px solid #00D3C8", borderLeft: "3px solid #00D3C8" },
+          { top: -2, right: -2, borderTop: "3px solid #00D3C8", borderRight: "3px solid #00D3C8" },
+          { bottom: -2, left: -2, borderBottom: "3px solid #00D3C8", borderLeft: "3px solid #00D3C8" },
+          { bottom: -2, right: -2, borderBottom: "3px solid #00D3C8", borderRight: "3px solid #00D3C8" },
+        ].map((style, i) => (
+          <div
+            key={i}
+            style={{
+              position: "absolute",
+              width: "12px",
+              height: "12px",
+              ...style,
+            }}
+          />
+        ))}
+      </div>
+    </>,
+    document.body
+  );
+}
+

package/dist/assets/dev-tools/types.ts

@@ -215,6 +215,20 @@ export type ComponentsViewMode = "visual" | "inspector";
 
 // ---- Vision Mode Types ----
 
+/** Parent section/container context for section-level targeting */
+export interface ParentSectionInfo {
+  /** Semantic container type (section, article, form, card, dialog, etc.) */
+  type: string;
+  /** Key text content in the section (first heading, labels) */
+  sectionText?: string;
+  /** The parent container's className for code matching */
+  className?: string;
+  /** Coordinates of the parent section */
+  coordinates?: { x: number; y: number; width: number; height: number };
+  /** Parent's element ID if available */
+  elementId?: string;
+}
+
 export interface VisionFocusedElement {
   name: string;
   type: DetectedElementType;
@@ -234,6 +248,8 @@ export interface VisionFocusedElement {
   elementId?: string;
   /** IDs of child elements for more precise targeting */
   childIds?: string[];
+  /** Parent section context for section-level targeting */
+  parentSection?: ParentSectionInfo;
 }
 
 export interface VisionEditRequest {

package/package.json

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