sonance-brand-mcp 1.3.92 → 1.3.94

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 {
@@ -1703,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

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 {
@@ -1672,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

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,10 +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, Crop } from "lucide-react";
 import { cn } from "../../../lib/utils";
 import { ChatMessage, AIEditResult, PendingEdit, VisionFocusedElement, VisionPendingEdit, ApplyFirstSession } from "../types";
 import html2canvas from "html2canvas-pro";
+import { ScreenshotAnnotator, Rectangle } from "./ScreenshotAnnotator";
+
+// 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 {
@@ -56,8 +105,22 @@ 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);
+  
+  // Screenshot annotation state
+  const [isAnnotating, setIsAnnotating] = useState(false);
+  const [annotatedScreenshot, setAnnotatedScreenshot] = useState<string | null>(null);
+  const [manualFocusBounds, setManualFocusBounds] = useState<Rectangle | null>(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(() => {
@@ -107,6 +170,33 @@ export function ChatInterface({
     }
   }, []);
 
+  // Start screenshot annotation - show drawing overlay on live app
+  const startAnnotation = useCallback(() => {
+    console.log("[Vision Mode] Starting screenshot annotation overlay...");
+    setIsAnnotating(true);
+  }, []);
+
+  // Handle annotation confirmation - screenshot is already captured and annotated
+  const handleAnnotationConfirm = useCallback((annotated: string, bounds: Rectangle) => {
+    console.log("[Vision Mode] Annotation confirmed:", { bounds });
+    setAnnotatedScreenshot(annotated);
+    setManualFocusBounds(bounds);
+    setIsAnnotating(false);
+    // Focus the input so user can type their prompt
+    setTimeout(() => inputRef.current?.focus(), 100);
+  }, []);
+
+  // Handle annotation cancel
+  const handleAnnotationCancel = useCallback(() => {
+    setIsAnnotating(false);
+  }, []);
+
+  // Clear the current annotation
+  const clearAnnotation = useCallback(() => {
+    setAnnotatedScreenshot(null);
+    setManualFocusBounds(null);
+  }, []);
+
   // Handle vision mode edit request
   const handleVisionEdit = async (prompt: string) => {
     // Use Apply-First mode if callback is provided (new Cursor-style workflow)
@@ -131,10 +221,36 @@ export function ChatInterface({
     setIsProcessing(true);
 
     try {
-      // Capture screenshot
-      console.log("[Vision Mode] Capturing screenshot...");
-      const screenshot = await captureScreenshot();
-      console.log("[Vision Mode] Screenshot captured:", screenshot ? `${screenshot.length} bytes` : "null");
+      let screenshot: string | null;
+
+      // PRIORITY 1: Use manually annotated screenshot if available
+      // This is when user drew a focus area using the annotation tool
+      if (annotatedScreenshot) {
+        console.log("[Vision Mode] Using manually annotated screenshot");
+        screenshot = annotatedScreenshot;
+        // Clear the annotation after use
+        setAnnotatedScreenshot(null);
+        setManualFocusBounds(null);
+      } else {
+        // PRIORITY 2: Capture fresh screenshot and auto-annotate with section highlight
+        console.log("[Vision Mode] Capturing screenshot...");
+        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
+        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 +278,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 +489,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">
@@ -474,6 +640,26 @@ export function ChatInterface({
             "disabled:opacity-50 disabled:bg-gray-50"
           )}
         />
+        
+        {/* Annotate screenshot button - only in vision mode */}
+        {visionMode && (
+          <button
+            onClick={startAnnotation}
+            onPointerDown={(e) => e.stopPropagation()}
+            disabled={isProcessing}
+            title="Draw on screenshot to focus AI attention"
+            className={cn(
+              "px-3 py-2 rounded transition-colors",
+              annotatedScreenshot
+                ? "bg-[#00D3C8] text-[#1a1a1a]" // Teal when annotation is active
+                : "bg-gray-100 text-gray-600 hover:bg-gray-200",
+              "disabled:opacity-50 disabled:cursor-not-allowed"
+            )}
+          >
+            <Crop className="h-4 w-4" />
+          </button>
+        )}
+        
         <button
           onClick={() => handleSend(input || inputRef.current?.value || "")}
           onPointerDown={(e) => e.stopPropagation()}
@@ -493,6 +679,23 @@ export function ChatInterface({
           )}
         </button>
       </div>
+      
+      {/* Annotation indicator */}
+      {annotatedScreenshot && visionMode && (
+        <div className="flex items-center justify-between text-xs text-[#00D3C8] bg-[#00D3C8]/10 px-2 py-1 rounded">
+          <span className="flex items-center gap-1">
+            <Crop className="h-3 w-3" />
+            Focus area selected - your prompt will target this region
+          </span>
+          <button
+            onClick={clearAnnotation}
+            className="text-[#00D3C8] hover:text-[#00b3a8] p-0.5"
+            title="Clear annotation"
+          >
+            <X className="h-3 w-3" />
+          </button>
+        </div>
+      )}
 
       {/* Processing Indicator */}
       {isProcessing && (
@@ -508,6 +711,14 @@ export function ChatInterface({
           </span>
         </div>
       )}
+
+      {/* Screenshot Annotator Overlay - draws on live app */}
+      {isAnnotating && (
+        <ScreenshotAnnotator
+          onConfirm={handleAnnotationConfirm}
+          onCancel={handleAnnotationCancel}
+        />
+      )}
     </div>
   );
 }

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

@@ -88,11 +88,14 @@ export function InspectorOverlay({
       const clickX = e.clientX;
       const clickY = e.clientY;
 
-      // Don't capture clicks on the DevTools panel or its portal container
-      const devToolsPanel = document.querySelector('[data-sonance-devtools="true"]');
+      // Don't capture clicks on ANY DevTools element (panel, annotation overlay, etc.)
+      // Check if the click target or any of its ancestors have data-sonance-devtools
+      const target = e.target as HTMLElement;
+      if (target.closest('[data-sonance-devtools="true"]')) return;
+      if (target.closest('[data-annotator-overlay="true"]')) return;
+      
       const devToolsRoot = document.getElementById('sonance-devtools-root');
-      if (devToolsPanel?.contains(e.target as Node)) return;
-      if (devToolsRoot?.contains(e.target as Node)) return;
+      if (devToolsRoot?.contains(target)) return;
 
       // Find ALL elements that contain the click point
       const matchingElements = elements.filter(el =>

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

@@ -0,0 +1,352 @@
+"use client";
+
+import React, { useEffect, useState, useCallback } from "react";
+import { createPortal } from "react-dom";
+import { Check, X, RotateCcw, Crop } from "lucide-react";
+import html2canvas from "html2canvas-pro";
+
+export interface Rectangle {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+interface ScreenshotAnnotatorProps {
+  /** Called when user confirms their selection with captured screenshot */
+  onConfirm: (annotatedScreenshot: string, bounds: Rectangle) => void;
+  /** Called when user cancels */
+  onCancel: () => void;
+}
+
+/**
+ * ScreenshotAnnotator displays a transparent overlay where users can
+ * draw a rectangle on the LIVE app to define the focus area.
+ * On confirm, it captures a screenshot and annotates it with the selection.
+ */
+export function ScreenshotAnnotator({
+  onConfirm,
+  onCancel,
+}: ScreenshotAnnotatorProps) {
+  const [mounted, setMounted] = useState(false);
+  const [isDrawing, setIsDrawing] = useState(false);
+  const [startPos, setStartPos] = useState<{ x: number; y: number } | null>(null);
+  const [currentRect, setCurrentRect] = useState<Rectangle | null>(null);
+  const [isCapturing, setIsCapturing] = useState(false);
+
+  useEffect(() => {
+    setMounted(true);
+    
+    // Handle escape key to cancel
+    const handleKeyDown = (e: KeyboardEvent) => {
+      if (e.key === "Escape") {
+        onCancel();
+      }
+    };
+    document.addEventListener("keydown", handleKeyDown);
+    
+    return () => {
+      setMounted(false);
+      document.removeEventListener("keydown", handleKeyDown);
+    };
+  }, [onCancel]);
+
+  // Mouse handlers for drawing on the live page
+  const handleMouseDown = useCallback((e: React.MouseEvent) => {
+    // Ignore clicks on the toolbar buttons
+    if ((e.target as HTMLElement).closest('[data-annotator-toolbar]')) {
+      return;
+    }
+    
+    // Stop propagation to prevent InspectorOverlay from detecting this as element selection
+    e.stopPropagation();
+    
+    setStartPos({ x: e.clientX, y: e.clientY });
+    setIsDrawing(true);
+    setCurrentRect(null);
+  }, []);
+
+  const handleMouseMove = useCallback((e: React.MouseEvent) => {
+    if (!isDrawing || !startPos) return;
+    
+    // Calculate rectangle (handle drawing in any direction)
+    const x = Math.min(startPos.x, e.clientX);
+    const y = Math.min(startPos.y, e.clientY);
+    const width = Math.abs(e.clientX - startPos.x);
+    const height = Math.abs(e.clientY - startPos.y);
+    
+    setCurrentRect({ x, y, width, height });
+  }, [isDrawing, startPos]);
+
+  const handleMouseUp = useCallback(() => {
+    setIsDrawing(false);
+  }, []);
+
+  // Clear the current selection
+  const handleRedraw = useCallback(() => {
+    setCurrentRect(null);
+    setStartPos(null);
+  }, []);
+
+  // Confirm: capture screenshot and annotate it
+  const handleConfirm = useCallback(async () => {
+    if (!currentRect || isCapturing) return;
+    
+    setIsCapturing(true);
+
+    try {
+      // Capture the full page screenshot (excluding DevTools elements)
+      const canvas = await html2canvas(document.body, {
+        ignoreElements: (element) => {
+          return (
+            element.hasAttribute("data-sonance-devtools") ||
+            element.hasAttribute("data-vision-mode-border") ||
+            element.hasAttribute("data-annotator-overlay")
+          );
+        },
+        useCORS: true,
+        allowTaint: true,
+        scale: 1,
+      });
+
+      // Create annotated screenshot with the focus rectangle
+      const ctx = canvas.getContext("2d")!;
+      
+      // Draw the focus rectangle (teal dashed border)
+      ctx.strokeStyle = "#00D3C8";
+      ctx.lineWidth = 4;
+      ctx.setLineDash([12, 6]);
+      ctx.strokeRect(currentRect.x, currentRect.y, currentRect.width, currentRect.height);
+
+      // Semi-transparent fill
+      ctx.fillStyle = "rgba(0, 211, 200, 0.1)";
+      ctx.fillRect(currentRect.x, currentRect.y, currentRect.width, currentRect.height);
+
+      // Add "FOCUS AREA" label
+      ctx.setLineDash([]); // Reset dash
+      ctx.fillStyle = "#00D3C8";
+      ctx.font = "bold 14px Montserrat, system-ui, sans-serif";
+      const labelText = "FOCUS AREA";
+      const labelPadding = 8;
+      const labelHeight = 22;
+      const labelWidth = ctx.measureText(labelText).width + labelPadding * 2;
+      
+      // Position label above the rectangle
+      const labelX = currentRect.x;
+      const labelY = Math.max(currentRect.y - labelHeight - 4, 0);
+      
+      ctx.fillRect(labelX, labelY, labelWidth, labelHeight);
+      ctx.fillStyle = "#1a1a1a";
+      ctx.fillText(labelText, labelX + labelPadding, labelY + 16);
+
+      const annotatedScreenshot = canvas.toDataURL("image/png", 0.9);
+      onConfirm(annotatedScreenshot, currentRect);
+    } catch (error) {
+      console.error("Failed to capture screenshot:", error);
+      setIsCapturing(false);
+    }
+  }, [currentRect, isCapturing, onConfirm]);
+
+  if (!mounted) return null;
+
+  return createPortal(
+    <div
+      data-annotator-overlay="true"
+      data-sonance-devtools="true"
+      onMouseDown={(e) => {
+        e.stopPropagation();
+        e.preventDefault();
+        handleMouseDown(e);
+      }}
+      onMouseMove={handleMouseMove}
+      onMouseUp={handleMouseUp}
+      onMouseLeave={handleMouseUp}
+      onClick={(e) => {
+        // Prevent clicks from bubbling to InspectorOverlay
+        e.stopPropagation();
+      }}
+      style={{
+        position: "fixed",
+        top: 0,
+        left: 0,
+        right: 0,
+        bottom: 0,
+        zIndex: 10000,
+        cursor: isDrawing ? "crosshair" : "crosshair",
+        // Transparent overlay - user sees the live app
+        backgroundColor: "rgba(0, 0, 0, 0.1)",
+        // Ensure we capture all pointer events
+        pointerEvents: "all",
+      }}
+    >
+      {/* Instructions banner at top */}
+      <div
+        data-sonance-devtools="true"
+        data-annotator-toolbar="true"
+        style={{
+          position: "fixed",
+          top: 20,
+          left: "50%",
+          transform: "translateX(-50%)",
+          display: "flex",
+          alignItems: "center",
+          gap: 8,
+          backgroundColor: "#00D3C8",
+          color: "#1a1a1a",
+          padding: "10px 20px",
+          borderRadius: 8,
+          fontSize: 14,
+          fontWeight: 600,
+          fontFamily: "'Montserrat', system-ui, -apple-system, sans-serif",
+          boxShadow: "0 4px 20px rgba(0, 211, 200, 0.4)",
+          pointerEvents: "none",
+          userSelect: "none",
+        }}
+      >
+        <Crop size={18} />
+        <span>Click and drag to select the area you want to focus on</span>
+      </div>
+
+      {/* Current rectangle selection */}
+      {currentRect && (
+        <div
+          data-sonance-devtools="true"
+          style={{
+            position: "fixed",
+            left: currentRect.x,
+            top: currentRect.y,
+            width: currentRect.width,
+            height: currentRect.height,
+            border: "3px dashed #00D3C8",
+            backgroundColor: "rgba(0, 211, 200, 0.15)",
+            borderRadius: 4,
+            boxShadow: "0 0 0 2px rgba(0, 211, 200, 0.3), 0 0 20px rgba(0, 211, 200, 0.2)",
+            pointerEvents: "none",
+          }}
+        />
+      )}
+
+      {/* Toolbar at bottom */}
+      <div
+        data-sonance-devtools="true"
+        data-annotator-toolbar="true"
+        style={{
+          position: "fixed",
+          bottom: 30,
+          left: "50%",
+          transform: "translateX(-50%)",
+          display: "flex",
+          gap: 12,
+        }}
+      >
+        {/* Cancel button */}
+        <button
+          data-sonance-devtools="true"
+          onClick={(e) => {
+            e.stopPropagation();
+            onCancel();
+          }}
+          onMouseDown={(e) => e.stopPropagation()}
+          style={{
+            display: "flex",
+            alignItems: "center",
+            gap: 6,
+            padding: "10px 20px",
+            backgroundColor: "rgba(30, 30, 30, 0.95)",
+            color: "white",
+            border: "1px solid rgba(255, 255, 255, 0.2)",
+            borderRadius: 6,
+            fontSize: 14,
+            fontWeight: 500,
+            fontFamily: "'Montserrat', system-ui, sans-serif",
+            cursor: "pointer",
+            transition: "all 0.2s",
+            boxShadow: "0 4px 12px rgba(0, 0, 0, 0.3)",
+          }}
+        >
+          <X size={16} />
+          Cancel
+        </button>
+
+        {/* Redraw button */}
+        <button
+          data-sonance-devtools="true"
+          onClick={(e) => {
+            e.stopPropagation();
+            handleRedraw();
+          }}
+          onMouseDown={(e) => e.stopPropagation()}
+          disabled={!currentRect}
+          style={{
+            display: "flex",
+            alignItems: "center",
+            gap: 6,
+            padding: "10px 20px",
+            backgroundColor: currentRect ? "rgba(30, 30, 30, 0.95)" : "rgba(30, 30, 30, 0.6)",
+            color: currentRect ? "white" : "rgba(255, 255, 255, 0.4)",
+            border: "1px solid rgba(255, 255, 255, 0.2)",
+            borderRadius: 6,
+            fontSize: 14,
+            fontWeight: 500,
+            fontFamily: "'Montserrat', system-ui, sans-serif",
+            cursor: currentRect ? "pointer" : "not-allowed",
+            transition: "all 0.2s",
+            boxShadow: "0 4px 12px rgba(0, 0, 0, 0.3)",
+          }}
+        >
+          <RotateCcw size={16} />
+          Redraw
+        </button>
+
+        {/* Confirm button */}
+        <button
+          data-sonance-devtools="true"
+          onClick={(e) => {
+            e.stopPropagation();
+            handleConfirm();
+          }}
+          onMouseDown={(e) => e.stopPropagation()}
+          disabled={!currentRect || isCapturing}
+          style={{
+            display: "flex",
+            alignItems: "center",
+            gap: 6,
+            padding: "10px 24px",
+            backgroundColor: currentRect ? "#00D3C8" : "rgba(0, 211, 200, 0.3)",
+            color: currentRect ? "#1a1a1a" : "rgba(26, 26, 26, 0.5)",
+            border: "none",
+            borderRadius: 6,
+            fontSize: 14,
+            fontWeight: 600,
+            fontFamily: "'Montserrat', system-ui, sans-serif",
+            cursor: currentRect && !isCapturing ? "pointer" : "not-allowed",
+            transition: "all 0.2s",
+            boxShadow: currentRect ? "0 4px 20px rgba(0, 211, 200, 0.4)" : "none",
+          }}
+        >
+          <Check size={16} />
+          {isCapturing ? "Capturing..." : "Confirm Selection"}
+        </button>
+      </div>
+
+      {/* Keyboard hint */}
+      <div
+        data-sonance-devtools="true"
+        style={{
+          position: "fixed",
+          bottom: 10,
+          left: "50%",
+          transform: "translateX(-50%)",
+          color: "rgba(255, 255, 255, 0.6)",
+          fontSize: 12,
+          fontFamily: "'Montserrat', system-ui, sans-serif",
+          textShadow: "0 1px 2px rgba(0, 0, 0, 0.5)",
+          pointerEvents: "none",
+        }}
+      >
+        Press <kbd style={{ padding: "2px 6px", backgroundColor: "rgba(0,0,0,0.4)", borderRadius: 4 }}>Esc</kbd> to cancel
+      </div>
+    </div>,
+    document.body
+  );
+}

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.92",
+  "version": "1.3.94",
   "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",