sonance-brand-mcp 1.3.1 → 1.3.3

package/dist/assets/api/sonance-analyze/route.ts

@@ -0,0 +1,1116 @@
+import { NextResponse } from "next/server";
+import * as fs from "fs";
+import * as path from "path";
+
+/**
+ * Sonance DevTools API - Project Analyzer
+ * 
+ * This endpoint scans the codebase to build an index of all design assets:
+ * - Logos and images
+ * - Theme files
+ * - Components using brand elements
+ * 
+ * DEVELOPMENT ONLY.
+ */
+
+// ---- Types ----
+
+type ElementCategory = "image" | "text" | "interactive" | "input" | "definition";
+
+type ElementType = 
+  // Images (including common wrapper components)
+  | "Image" | "img" | "ZoomImage" | "BrandImage" | "ImageGallery"
+  // Text
+  | "h1" | "h2" | "h3" | "h4" | "h5" | "h6" | "p" | "span"
+  // Interactive elements (buttons, links)
+  | "Button" | "Link" | "a"
+  // Inputs
+  | "Input" | "Textarea" | "Select" | "Checkbox" | "Switch"
+  // Component definitions
+  | "ComponentDefinition";
+
+interface ScannedElement {
+  id: string;                  // Unique ID for this occurrence
+  filePath: string;            // Relative path to the file
+  lineNumber: number;          // Line number in the file
+  index: number;               // Absolute character index in the file (for precise targeting)
+  category: ElementCategory;   // Category of element
+  elementType: ElementType;    // Specific element type
+  hasId: boolean;              // Whether element already has an id attribute
+  existingId?: string;         // The existing id if present
+  suggestedId?: string;        // Suggested ID based on context
+  context: {
+    parentComponent?: string;  // Parent component name if detectable
+    semanticContainer?: string; // header/footer/nav/aside/main/section
+  };
+  // Image-specific fields
+  srcValue?: string;           // The src prop value (for images)
+  srcType?: "literal" | "variable" | "import"; // How the src is defined
+  alt?: string;                // Alt text if present
+  // Text-specific fields
+  textContent?: string;        // Truncated text content (for headings/paragraphs)
+  // Component-specific fields
+  variant?: string;            // variant prop if present
+  // Input-specific fields
+  inputName?: string;          // name or placeholder if present
+  inputType?: string;          // type attribute if present
+}
+
+// Backwards compatibility alias
+type ImageElement = ScannedElement;
+
+interface ThemeFile {
+  filePath: string;
+  type: "css" | "tailwind" | "config";
+  hasBrandVariables: boolean;
+}
+
+// Color source detection for universal DevTools
+interface ColorSource {
+  filePath: string;
+  type: "css-variables" | "tailwind-config" | "theme-file" | "hardcoded";
+  variables: {
+    name: string;        // e.g., "--primary", "primary", "colors.primary"
+    value: string;       // e.g., "#333F48"
+    lineNumber: number;
+  }[];
+}
+
+interface ColorArchitecture {
+  primary: "css-variables" | "tailwind" | "hardcoded" | "unknown";
+  accent: "css-variables" | "tailwind" | "hardcoded" | "unknown";
+  sources: ColorSource[];
+  recommendation: string;
+}
+
+interface CategorySummary {
+  total: number;
+  withId: number;
+  missingId: number;
+}
+
+interface AnalysisResult {
+  timestamp: string;
+  scanDuration: number;
+  filesScanned: number;
+  elements: ScannedElement[];
+  // Backwards compatibility
+  images: ScannedElement[];
+  themeFiles: ThemeFile[];
+  colorArchitecture: ColorArchitecture;
+  summary: {
+    totalElements: number;
+    elementsWithId: number;
+    elementsMissingId: number;
+    byCategory: {
+      image: CategorySummary;
+      text: CategorySummary;
+      interactive: CategorySummary;
+      input: CategorySummary;
+      definition: CategorySummary;
+    };
+    // Legacy fields
+    totalImages: number;
+    imagesWithId: number;
+    imagesMissingId: number;
+    brandLogosDetected: number;
+  };
+}
+
+// ---- AST-like Parsing (Regex-based for simplicity) ----
+
+// Element type to category mapping
+const ELEMENT_CATEGORIES: Record<string, ElementCategory> = {
+  // Images (including common wrapper components)
+  "Image": "image",
+  "img": "image",
+  "ZoomImage": "image",
+  "BrandImage": "image",
+  "ImageGallery": "image",
+  // Text
+  "h1": "text", "h2": "text", "h3": "text", "h4": "text", "h5": "text", "h6": "text",
+  "p": "text", "span": "text",
+  // Interactive elements (buttons, links)
+  "Button": "interactive", "Link": "interactive", "a": "interactive",
+  // Inputs
+  "Input": "input", "Textarea": "input", "Select": "input", 
+  "Checkbox": "input", "Switch": "input",
+};
+
+// All element tags to scan for
+const ALL_ELEMENT_TAGS = Object.keys(ELEMENT_CATEGORIES);
+
+/**
+ * Extracts all design-related elements from a file using pattern matching.
+ * This is a simplified AST approach that handles common patterns.
+ */
+function extractElements(
+  filePath: string, 
+  content: string,
+  relativePath: string
+): ScannedElement[] {
+  const elements: ScannedElement[] = [];
+  const lines = content.split("\n");
+  
+  // Track component context
+  let currentComponent: string | undefined;
+  
+  // Pattern for function/const component declarations
+  const componentPattern = /(?:function|const)\s+([A-Z][a-zA-Z0-9]*)/;
+  
+  const fullContent = content;
+  
+  // Build a regex to match all element types
+  // Need to escape for regex and handle case sensitivity
+  // React components are PascalCase, HTML elements are lowercase
+  const tagNames = ALL_ELEMENT_TAGS.join("|");
+  const elementTagPattern = new RegExp(`<(${tagNames})(?:\\s|>|\\/)`, "g");
+  
+  let tagMatch;
+  
+  while ((tagMatch = elementTagPattern.exec(fullContent)) !== null) {
+    const tagStart = tagMatch.index;
+    const elementType = tagMatch[1] as ElementType;
+    const category = ELEMENT_CATEGORIES[elementType];
+    
+    if (!category) continue;
+    
+    // Find the end of this element's opening tag (closing > or />)
+    let elementEnd = tagStart;
+    let inString = false;
+    let stringChar = "";
+    let inJsxExpr = 0;
+    
+    for (let i = tagStart; i < fullContent.length; i++) {
+      const char = fullContent[i];
+      const prevChar = i > 0 ? fullContent[i - 1] : "";
+      
+      // Track string boundaries
+      if ((char === '"' || char === "'" || char === '`') && prevChar !== '\\') {
+        if (!inString) {
+          inString = true;
+          stringChar = char;
+        } else if (char === stringChar) {
+          inString = false;
+          stringChar = "";
+        }
+        continue;
+      }
+      
+      if (inString) continue;
+      
+      // Track JSX expression boundaries
+      if (char === '{') {
+        inJsxExpr++;
+        continue;
+      }
+      if (char === '}') {
+        inJsxExpr--;
+        continue;
+      }
+      
+      if (inJsxExpr > 0) continue;
+      
+      // Check for self-closing or regular closing
+      if (char === '/' && fullContent[i + 1] === '>') {
+        elementEnd = i + 2;
+        break;
+      }
+      if (char === '>') {
+        elementEnd = i + 1;
+        break;
+      }
+    }
+    
+    const elementContent = fullContent.substring(tagStart, elementEnd);
+    
+    // Calculate line number
+    const lineNumber = fullContent.substring(0, tagStart).split("\n").length;
+    
+    // Extract id attribute
+    let hasId = false;
+    let existingId: string | undefined;
+    const idMatch = elementContent.match(/\bid=["']([^"']+)["']/);
+    if (idMatch) {
+      hasId = true;
+      existingId = idMatch[1];
+    }
+    const idExprMatch = elementContent.match(/\bid=\{["']([^"']+)["']\}/);
+    if (idExprMatch) {
+      hasId = true;
+      existingId = idExprMatch[1];
+    }
+    
+    // Find semantic container by looking backwards in the content
+    let semanticContainer: string | undefined;
+    const beforeElement = fullContent.substring(Math.max(0, tagStart - 500), tagStart);
+    const semanticMatch = beforeElement.match(/<(header|footer|nav|aside|main|section)[^>]*>/gi);
+    if (semanticMatch) {
+      const lastMatch = semanticMatch[semanticMatch.length - 1];
+      const containerMatch = lastMatch.match(/<(header|footer|nav|aside|main|section)/i);
+      if (containerMatch) {
+        semanticContainer = containerMatch[1].toLowerCase();
+      }
+    }
+    
+    // Find component name
+    for (let i = lineNumber - 1; i >= 0 && i >= lineNumber - 50; i--) {
+      const line = lines[i];
+      const compMatch = line.match(componentPattern);
+      if (compMatch) {
+        currentComponent = compMatch[1];
+        break;
+      }
+    }
+    
+    // Extract category-specific fields
+    const element: ScannedElement = {
+      id: `${relativePath}:${lineNumber}:${elementType}:${tagStart}`,
+      filePath: relativePath,
+      lineNumber,
+      index: tagStart, // Absolute character index for precise targeting
+      category,
+      elementType,
+      hasId,
+      existingId,
+      context: {
+        parentComponent: currentComponent,
+        semanticContainer,
+      },
+    };
+    
+    // Image-specific extraction
+    if (category === "image") {
+      // Extract src attribute
+      const literalSrcMatch = elementContent.match(/src=["']([^"']+)["']/);
+      if (literalSrcMatch) {
+        element.srcValue = literalSrcMatch[1];
+        element.srcType = "literal";
+      } else {
+        const exprSrcMatch = elementContent.match(/src=\{([^}]+)\}/);
+        if (exprSrcMatch) {
+          element.srcValue = exprSrcMatch[1].trim();
+          element.srcType = element.srcValue.includes("import") || /^[A-Z]/.test(element.srcValue) 
+            ? "import" : "variable";
+        }
+      }
+      
+      // Extract alt text
+      const altMatch = elementContent.match(/alt=["']([^"']+)["']/);
+      if (altMatch) {
+        element.alt = altMatch[1];
+      }
+    }
+    
+    // Text-specific extraction
+    if (category === "text") {
+      // Try to extract text content between opening and closing tags
+      // This is approximate - we look for content after the opening tag
+      const afterOpenTag = fullContent.substring(elementEnd);
+      const closeTagMatch = afterOpenTag.match(new RegExp(`^([^<]*)<\\/${elementType}>`));
+      if (closeTagMatch && closeTagMatch[1].trim()) {
+        element.textContent = closeTagMatch[1].trim().substring(0, 50);
+        if (closeTagMatch[1].trim().length > 50) {
+          element.textContent += "...";
+        }
+      }
+    }
+    
+    // Component-specific extraction
+    if (category === "component") {
+      // Extract variant
+      const variantMatch = elementContent.match(/variant=["']([^"']+)["']/);
+      if (variantMatch) {
+        element.variant = variantMatch[1];
+      }
+    }
+    
+    // Input-specific extraction
+    if (category === "input") {
+      // Extract name or placeholder
+      const nameMatch = elementContent.match(/(?:name|placeholder)=["']([^"']+)["']/);
+      if (nameMatch) {
+        element.inputName = nameMatch[1];
+      }
+      // Extract type
+      const typeMatch = elementContent.match(/type=["']([^"']+)["']/);
+      if (typeMatch) {
+        element.inputType = typeMatch[1];
+      }
+    }
+    
+    // Generate suggested ID
+    element.suggestedId = generateSuggestedId(element);
+    
+    elements.push(element);
+  }
+  
+  return elements;
+}
+
+/**
+ * Legacy function for backwards compatibility
+ */
+function extractImageElements(
+  filePath: string, 
+  content: string,
+  relativePath: string
+): ScannedElement[] {
+  return extractElements(filePath, content, relativePath)
+    .filter(el => el.category === "image");
+}
+
+/**
+ * Generates a suggested ID based on element and available context
+ */
+function generateSuggestedId(element: ScannedElement): string {
+  const parts: string[] = [];
+  const { category, elementType, context, srcValue, alt, textContent, variant, inputName } = element;
+  
+  // Add semantic container if available
+  if (context.semanticContainer) {
+    parts.push(context.semanticContainer);
+  } else if (context.parentComponent) {
+    // Use component name if no semantic container
+    parts.push(context.parentComponent.replace(/([A-Z])/g, "-$1").toLowerCase().replace(/^-/, ""));
+  }
+  
+  // Category-specific ID generation
+  switch (category) {
+    case "image": {
+      const src = srcValue || "";
+      const srcLower = src.toLowerCase();
+      
+      // Try to extract brand from src
+      if (srcLower.includes("sonance")) {
+        parts.push("sonance");
+      } else if (srcLower.includes("iport")) {
+        parts.push("iport");
+      } else if (srcLower.includes("blaze")) {
+        parts.push("blaze");
+      }
+      
+      // Add "logo" if it looks like a logo
+      if (srcLower.includes("logo") || (alt && alt.toLowerCase().includes("logo"))) {
+        parts.push("logo");
+      } else if (alt) {
+        const cleanAlt = alt.toLowerCase()
+          .replace(/[^a-z0-9\s]/g, "")
+          .replace(/\s+/g, "-")
+          .substring(0, 20);
+        if (cleanAlt) parts.push(cleanAlt);
+      }
+      
+      if (parts.length === 0) parts.push("image");
+      break;
+    }
+    
+    case "text": {
+      // Add element type (h1, h2, p, etc.)
+      parts.push(elementType.toLowerCase());
+      
+      // Try to use text content for context
+      if (textContent) {
+        const cleanText = textContent.toLowerCase()
+          .replace(/[^a-z0-9\s]/g, "")
+          .replace(/\s+/g, "-")
+          .substring(0, 20);
+        if (cleanText) parts.push(cleanText);
+      }
+      
+      if (parts.length === 1) parts.push("title");
+      break;
+    }
+    
+    case "component": {
+      // Add element type (button, link, etc.)
+      parts.push(elementType.toLowerCase());
+      
+      // Add variant if present
+      if (variant) {
+        parts.push(variant.toLowerCase());
+      }
+      
+      if (parts.length === 1) parts.push("action");
+      break;
+    }
+    
+    case "input": {
+      // Add element type
+      parts.push(elementType.toLowerCase());
+      
+      // Add name/placeholder if present
+      if (inputName) {
+        const cleanName = inputName.toLowerCase()
+          .replace(/[^a-z0-9\s]/g, "")
+          .replace(/\s+/g, "-")
+          .substring(0, 15);
+        if (cleanName) parts.push(cleanName);
+      }
+      
+      if (parts.length === 1) parts.push("field");
+      break;
+    }
+  }
+  
+  // Deduplicate and join
+  return parts.filter((v, i, a) => a.indexOf(v) === i).join("-");
+}
+
+/**
+ * Detects theme-related files
+ */
+function detectThemeFiles(
+  filePath: string,
+  content: string,
+  relativePath: string
+): ThemeFile | null {
+  const filename = path.basename(filePath).toLowerCase();
+  
+  // Check for theme-related filenames
+  const isThemeFile = 
+    filename.includes("theme") ||
+    filename.includes("globals") ||
+    filename.includes("tailwind") ||
+    filename.includes("brand");
+  
+  if (!isThemeFile) return null;
+  
+  // Determine type
+  let type: ThemeFile["type"] = "css";
+  if (filename.includes("tailwind")) {
+    type = "tailwind";
+  } else if (filename.endsWith(".ts") || filename.endsWith(".js") || filename.endsWith(".json")) {
+    type = "config";
+  }
+  
+  // Check for brand variables
+  const hasBrandVariables = 
+    content.includes("--sonance") ||
+    content.includes("--iport") ||
+    content.includes("--blaze") ||
+    content.includes("sonance-") ||
+    content.includes("brandColors") ||
+    content.includes("brandLogos");
+  
+  return {
+    filePath: relativePath,
+    type,
+    hasBrandVariables,
+  };
+}
+
+/**
+ * Detects color variable definitions in a file
+ */
+function detectColorSources(
+  filePath: string,
+  content: string,
+  relativePath: string
+): ColorSource | null {
+  const filename = path.basename(filePath).toLowerCase();
+  const variables: ColorSource["variables"] = [];
+  const lines = content.split('\n');
+  
+  // Pattern 1: CSS custom properties (:root { --primary: #xxx })
+  const cssVarPattern = /--(primary|accent|color-primary|color-accent|theme-primary|theme-accent|sonance-\w+|iport-\w+|blaze-\w+)\s*:\s*(#[0-9a-fA-F]{3,8}|rgb[a]?\([^)]+\))/gi;
+  let match;
+  
+  while ((match = cssVarPattern.exec(content)) !== null) {
+    const lineNumber = content.substring(0, match.index).split('\n').length;
+    variables.push({
+      name: `--${match[1]}`,
+      value: match[2],
+      lineNumber,
+    });
+  }
+  
+  // Pattern 2: Tailwind config colors
+  if (filename.includes('tailwind.config')) {
+    const tailwindColorPattern = /(primary|accent|brand)\s*:\s*['"]?(#[0-9a-fA-F]{3,8})['"]?/gi;
+    while ((match = tailwindColorPattern.exec(content)) !== null) {
+      const lineNumber = content.substring(0, match.index).split('\n').length;
+      variables.push({
+        name: match[1],
+        value: match[2],
+        lineNumber,
+      });
+    }
+  }
+  
+  // Pattern 3: JS/TS theme objects (e.g., const colors = { primary: "#xxx" })
+  if (filename.endsWith('.ts') || filename.endsWith('.js') || filename.endsWith('.tsx')) {
+    const jsColorPattern = /(primary|accent|baseColor|accentColor)\s*[:=]\s*['"`](#[0-9a-fA-F]{3,8})['"`]/gi;
+    while ((match = jsColorPattern.exec(content)) !== null) {
+      const lineNumber = content.substring(0, match.index).split('\n').length;
+      variables.push({
+        name: match[1],
+        value: match[2],
+        lineNumber,
+      });
+    }
+  }
+  
+  if (variables.length === 0) return null;
+  
+  // Determine type
+  let type: ColorSource["type"] = "hardcoded";
+  if (filename.endsWith('.css') && variables.some(v => v.name.startsWith('--'))) {
+    type = "css-variables";
+  } else if (filename.includes('tailwind.config')) {
+    type = "tailwind-config";
+  } else if (filename.includes('theme') || filename.includes('brand') || filename.includes('colors')) {
+    type = "theme-file";
+  }
+  
+  return {
+    filePath: relativePath,
+    type,
+    variables,
+  };
+}
+
+/**
+ * Analyzes color architecture from detected sources
+ */
+function analyzeColorArchitecture(sources: ColorSource[]): ColorArchitecture {
+  let primary: ColorArchitecture["primary"] = "unknown";
+  let accent: ColorArchitecture["accent"] = "unknown";
+  let recommendation = "No standard color architecture detected. Changes will be previewed but may need manual persistence.";
+  
+  // Check for CSS variables
+  const cssVarSources = sources.filter(s => s.type === "css-variables");
+  if (cssVarSources.length > 0) {
+    const hasPrimary = cssVarSources.some(s => s.variables.some(v => v.name.includes('primary')));
+    const hasAccent = cssVarSources.some(s => s.variables.some(v => v.name.includes('accent')));
+    
+    if (hasPrimary) primary = "css-variables";
+    if (hasAccent) accent = "css-variables";
+    
+    if (hasPrimary || hasAccent) {
+      recommendation = "CSS custom properties detected. Color changes can be saved to your CSS files.";
+    }
+  }
+  
+  // Check for Tailwind config
+  const tailwindSources = sources.filter(s => s.type === "tailwind-config");
+  if (tailwindSources.length > 0) {
+    if (primary === "unknown") primary = "tailwind";
+    if (accent === "unknown") accent = "tailwind";
+    recommendation = "Tailwind config detected. Color changes can be saved to tailwind.config.";
+  }
+  
+  // Check for theme files
+  const themeSources = sources.filter(s => s.type === "theme-file");
+  if (themeSources.length > 0 && primary === "unknown") {
+    primary = "hardcoded";
+    accent = "hardcoded";
+    recommendation = "Theme configuration file detected. Color changes can be saved to your theme file.";
+  }
+  
+  return {
+    primary,
+    accent,
+    sources,
+    recommendation,
+  };
+}
+
+/**
+ * Recursively scans directory for source files
+ */
+function scanDirectory(
+  dir: string,
+  projectRoot: string,
+  extensions: string[] = [".tsx", ".jsx", ".js", ".ts", ".css"]
+): { elements: ScannedElement[]; images: ScannedElement[]; themeFiles: ThemeFile[]; colorSources: ColorSource[]; filesScanned: number } {
+  const elements: ScannedElement[] = [];
+  const themeFiles: ThemeFile[] = [];
+  const colorSources: ColorSource[] = [];
+  let filesScanned = 0;
+  
+  function scan(currentDir: string): void {
+    if (!fs.existsSync(currentDir)) return;
+    
+    const entries = fs.readdirSync(currentDir, { withFileTypes: true });
+    
+    for (const entry of entries) {
+      const fullPath = path.join(currentDir, entry.name);
+      
+      // Skip excluded directories
+      if (entry.isDirectory()) {
+        if (
+          entry.name.startsWith(".") ||
+          entry.name === "node_modules" ||
+          entry.name === "dist" ||
+          entry.name === "build" ||
+          entry.name === ".next"
+        ) {
+          continue;
+        }
+        scan(fullPath);
+      } else if (entry.isFile() && extensions.some(ext => entry.name.endsWith(ext))) {
+        try {
+          const content = fs.readFileSync(fullPath, "utf-8");
+          const relativePath = fullPath.replace(projectRoot, "").replace(/^\//, "");
+          filesScanned++;
+          
+          // Extract all elements from JSX/TSX files
+          if (entry.name.endsWith(".tsx") || entry.name.endsWith(".jsx")) {
+            const fileElements = extractElements(fullPath, content, relativePath);
+            elements.push(...fileElements);
+          }
+          
+          // Detect component definitions (files in src/components/ui or src/components/layout)
+          if (entry.name.endsWith(".tsx") && !entry.name.endsWith(".stories.tsx")) {
+            const isComponentDef = 
+              relativePath.startsWith("src/components/ui/") || 
+              relativePath.startsWith("src/components/layout/");
+            
+            if (isComponentDef) {
+              const componentName = entry.name.replace(".tsx", "");
+              const hasTag = content.includes("data-sonance-name");
+              
+              // Create a definition element for this component file
+              const defElement: ScannedElement = {
+                id: `${relativePath}:1:ComponentDefinition`,
+                filePath: relativePath,
+                lineNumber: 1,
+                index: 0,
+                category: "definition",
+                elementType: "ComponentDefinition",
+                hasId: hasTag, // "hasId" here means "has data-sonance-name"
+                existingId: hasTag ? componentName : undefined,
+                suggestedId: componentName.toLowerCase(),
+                context: {
+                  parentComponent: componentName,
+                },
+              };
+              elements.push(defElement);
+            }
+          }
+          
+          // Detect theme files
+          const themeFile = detectThemeFiles(fullPath, content, relativePath);
+          if (themeFile) {
+            themeFiles.push(themeFile);
+          }
+          
+          // Detect color sources
+          const colorSource = detectColorSources(fullPath, content, relativePath);
+          if (colorSource) {
+            colorSources.push(colorSource);
+          }
+        } catch (error) {
+          // Skip files that can't be read
+          console.error(`Error reading ${fullPath}:`, error);
+        }
+      }
+    }
+  }
+  
+  scan(dir);
+  
+  // Backwards compatibility: filter images
+  const images = elements.filter(el => el.category === "image");
+  
+  return { elements, images, themeFiles, colorSources, filesScanned };
+}
+
+// ---- Component Definition Tagging ----
+
+/**
+ * Tags a component definition file with data-sonance-name attribute.
+ * Uses multiple regex patterns to handle different component structures.
+ */
+function tagComponentDefinition(filePath: string, content: string, componentName: string): { success: boolean; content: string; error?: string } {
+  // Helper to inject tag only if not present in the match
+  const injectTag = (match: string, p1: string, p2: string) => {
+    if (match.includes("data-sonance-name=")) return match;
+    return `${p1} data-sonance-name="${componentName}"${p2}`;
+  };
+  
+  let modified = false;
+  let result = content;
+  
+  // Pattern 1: <ElementName {...props} or <ElementName className={...} {...props}
+  const propsSpreadPattern = /(<(?:[A-Z][a-zA-Z0-9]*|[a-z]+)(?:\s+[^>]*?)?)(\s+\{\.\.\.props\})/g;
+  if (propsSpreadPattern.test(result)) {
+    propsSpreadPattern.lastIndex = 0;
+    const newContent = result.replace(propsSpreadPattern, injectTag);
+    if (newContent !== result) {
+      result = newContent;
+      modified = true;
+    }
+  }
+  
+  // Pattern 2: forwardRef with explicit return
+  if (!modified) {
+    const forwardRefReturnPattern = /(return\s*\(\s*<(?:[A-Z][a-zA-Z0-9]*|[a-z]+))(?![^>]*data-sonance-name=)(\s+)/;
+    if (forwardRefReturnPattern.test(result)) {
+      const newContent = result.replace(forwardRefReturnPattern, injectTag);
+      if (newContent !== result) {
+        result = newContent;
+        modified = true;
+      }
+    }
+  }
+
+  // Pattern 3: Simple component that returns a single element
+  if (!modified) {
+    const simpleReturnPattern = /(return\s+<(?:[A-Z][a-zA-Z0-9]*|[a-z]+))(?![^>]*data-sonance-name=)(\s+)/;
+    if (simpleReturnPattern.test(result)) {
+      const newContent = result.replace(simpleReturnPattern, injectTag);
+      if (newContent !== result) {
+        result = newContent;
+        modified = true;
+      }
+    }
+  }
+
+  // Pattern 4: Semantic HTML tags
+  if (!modified) {
+    const semanticTagPattern = /(<(?:aside|nav|main|header|footer|section|article)(?:\s+[^>]*?)?)(\s+className=)/;
+    if (semanticTagPattern.test(result)) {
+      const newContent = result.replace(semanticTagPattern, injectTag);
+      if (newContent !== result) {
+        result = newContent;
+        modified = true;
+      }
+    }
+  }
+
+  // Pattern 5: div with className={cn( - common Shadcn pattern
+  if (!modified) {
+    const cnDivPattern = /(<div)(?![^>]*data-sonance-name=)(\s+className=\{cn\()/;
+    if (cnDivPattern.test(result)) {
+      const newContent = result.replace(cnDivPattern, injectTag);
+      if (newContent !== result) {
+        result = newContent;
+        modified = true;
+      }
+    }
+  }
+
+  // Pattern 6: forwardRef with implicit return (arrow function + parentheses)
+  if (!modified) {
+    const forwardRefImplicitPattern = /(\)\s*=>\s*\(\s*<(?:[A-Z][a-zA-Z0-9]*\.)?[A-Z][a-zA-Z0-9]*)(?![^>]*data-sonance-name=)(\s+)/;
+    if (forwardRefImplicitPattern.test(result)) {
+      const newContent = result.replace(forwardRefImplicitPattern, injectTag);
+      if (newContent !== result) {
+        result = newContent;
+        modified = true;
+      }
+    }
+  }
+
+  // Pattern 7: Arrow function component with implicit return
+  if (!modified) {
+    const arrowImplicitPattern = /(}\)\s*=>\s*\(\s*<(?:[A-Z][a-zA-Z0-9]*\.)?[A-Z][a-zA-Z0-9]*)(?![^>]*data-sonance-name=)(\s+)/;
+    if (arrowImplicitPattern.test(result)) {
+      const newContent = result.replace(arrowImplicitPattern, injectTag);
+      if (newContent !== result) {
+        result = newContent;
+        modified = true;
+      }
+    }
+  }
+
+  if (modified) {
+    return { success: true, content: result };
+  } else {
+    return { success: false, content: result, error: "No matching pattern found (may be pure re-export)" };
+  }
+}
+
+// ---- API Handlers ----
+
+export async function GET() {
+  // Security: Only allow in development
+  if (process.env.NODE_ENV !== "development") {
+    return NextResponse.json(
+      { error: "This endpoint is only available in development mode." },
+      { status: 403 }
+    );
+  }
+
+  const startTime = Date.now();
+  
+  try {
+    const projectRoot = process.cwd();
+    const srcDir = path.join(projectRoot, "src");
+    
+    // Scan the codebase
+    const { elements, images, themeFiles, colorSources, filesScanned } = scanDirectory(srcDir, projectRoot);
+    
+    // Analyze color architecture
+    const colorArchitecture = analyzeColorArchitecture(colorSources);
+    
+    // Helper to create category summary
+    const createCategorySummary = (category: ElementCategory): CategorySummary => {
+      const categoryElements = elements.filter(el => el.category === category);
+      return {
+        total: categoryElements.length,
+        withId: categoryElements.filter(el => el.hasId).length,
+        missingId: categoryElements.filter(el => !el.hasId).length,
+      };
+    };
+    
+    // Count brand logos (backwards compatibility)
+    const brandLogosDetected = images.filter(img => {
+      const src = (img.srcValue || "").toLowerCase();
+      return src.includes("logo") && 
+             (src.includes("sonance") || src.includes("iport") || src.includes("blaze"));
+    }).length;
+    
+    const result: AnalysisResult = {
+      timestamp: new Date().toISOString(),
+      scanDuration: Date.now() - startTime,
+      filesScanned,
+      elements,
+      images, // Backwards compatibility
+      themeFiles,
+      colorArchitecture,
+      summary: {
+        totalElements: elements.length,
+        elementsWithId: elements.filter(el => el.hasId).length,
+        elementsMissingId: elements.filter(el => !el.hasId).length,
+        byCategory: {
+          image: createCategorySummary("image"),
+          text: createCategorySummary("text"),
+          interactive: createCategorySummary("interactive"),
+          input: createCategorySummary("input"),
+          definition: createCategorySummary("definition"),
+        },
+        // Legacy fields
+        totalImages: images.length,
+        imagesWithId: images.filter(img => img.hasId).length,
+        imagesMissingId: images.filter(img => !img.hasId).length,
+        brandLogosDetected,
+      },
+    };
+    
+    return NextResponse.json(result);
+  } catch (error) {
+    console.error("Error analyzing project:", error);
+    return NextResponse.json(
+      { error: "Failed to analyze project", details: String(error) },
+      { status: 500 }
+    );
+  }
+}
+
+// POST handler for bulk operations
+export async function POST(request: Request) {
+  // Security: Only allow in development
+  if (process.env.NODE_ENV !== "development") {
+    return NextResponse.json(
+      { error: "This endpoint is only available in development mode." },
+      { status: 403 }
+    );
+  }
+
+  try {
+    const body = await request.json();
+    const { action, elementIds, category } = body;
+    
+    // Support legacy "imageIds" field
+    const targetIds: string[] | undefined = elementIds || body.imageIds;
+    
+    if (action === "auto-tag-all") {
+      // Bulk inject IDs into elements missing them
+      const projectRoot = process.cwd();
+      const srcDir = path.join(projectRoot, "src");
+      
+      // Re-scan to get fresh data
+      const { elements } = scanDirectory(srcDir, projectRoot);
+      
+      // Filter to elements that need IDs
+      let targetElements = elements.filter(el => !el.hasId);
+      
+      // Filter by specific IDs if provided
+      if (targetIds && targetIds.length > 0) {
+        targetElements = targetElements.filter(el => targetIds.includes(el.id));
+      }
+      
+      // Filter by category if provided (e.g., "image", "text", "component", "input")
+      if (category) {
+        targetElements = targetElements.filter(el => el.category === category);
+      }
+      
+      // Group elements by file and sort by character INDEX DESCENDING within each file
+      // This is critical: processing from right-to-left (end-to-start) prevents index shifts
+      // from affecting subsequent elements in the same file
+      // Using character index instead of line number handles multiple elements on the same line
+      const elementsByFile = new Map<string, typeof targetElements>();
+      for (const el of targetElements) {
+        const existing = elementsByFile.get(el.filePath) || [];
+        existing.push(el);
+        elementsByFile.set(el.filePath, existing);
+      }
+      
+      // Sort each file's elements by character index descending (process right-to-left)
+      for (const [, fileElements] of elementsByFile) {
+        fileElements.sort((a, b) => b.index - a.index);
+      }
+      
+      // Flatten back to array, processing by file, right-to-left within each file
+      targetElements = Array.from(elementsByFile.values()).flat();
+      
+      const results: { id: string; success: boolean; error?: string }[] = [];
+      
+      for (const element of targetElements) {
+        if (!element.suggestedId) {
+          results.push({ id: element.id, success: false, error: "No suggested ID" });
+          continue;
+        }
+        
+        try {
+          const fullPath = path.join(projectRoot, element.filePath);
+          let content = fs.readFileSync(fullPath, "utf-8");
+          
+          // Special handling for component definitions - use data-sonance-name instead of id
+          if (element.category === "definition") {
+            const componentName = element.context.parentComponent || element.suggestedId;
+            const tagResult = tagComponentDefinition(fullPath, content, componentName);
+            
+            if (tagResult.success) {
+              fs.writeFileSync(fullPath, tagResult.content, "utf-8");
+              results.push({ id: element.id, success: true });
+            } else {
+              results.push({ id: element.id, success: false, error: tagResult.error });
+            }
+            continue;
+          }
+          
+          const tagName = element.elementType; // e.g., "Image", "img", "h1", "Button", etc.
+          
+          // Use the stored character index directly for precise targeting
+          // This avoids ambiguity when multiple elements of same type are on one line
+          const absoluteTagStart = element.index;
+          
+          // Verify the tag is at the expected position
+          const expectedTag = `<${tagName}`;
+          if (!content.substring(absoluteTagStart, absoluteTagStart + expectedTag.length + 1).startsWith(expectedTag)) {
+            results.push({ id: element.id, success: false, error: `Tag mismatch at index ${absoluteTagStart}` });
+            continue;
+          }
+          
+          // Find the end of the opening tag (the closing > or />)
+          const afterTagName = absoluteTagStart + tagName.length + 1; // +1 for <
+          let tagEndPos = -1;
+          let inString = false;
+          let stringChar = '';
+          let inJsxExpr = 0;
+          
+          for (let i = afterTagName; i < content.length; i++) {
+            const char = content[i];
+            const prevChar = i > 0 ? content[i - 1] : '';
+            
+            // Track string boundaries
+            if ((char === '"' || char === "'" || char === '`') && prevChar !== '\\') {
+              if (!inString) {
+                inString = true;
+                stringChar = char;
+              } else if (char === stringChar) {
+                inString = false;
+                stringChar = '';
+              }
+              continue;
+            }
+            
+            if (inString) continue;
+            
+            // Track JSX expression boundaries
+            if (char === '{') {
+              inJsxExpr++;
+              continue;
+            }
+            if (char === '}') {
+              inJsxExpr--;
+              continue;
+            }
+            
+            if (inJsxExpr > 0) continue;
+            
+            // Check for self-closing or regular closing
+            if (char === '/' && content[i + 1] === '>') {
+              tagEndPos = i;
+              break;
+            }
+            if (char === '>') {
+              tagEndPos = i;
+              break;
+            }
+          }
+          
+          if (tagEndPos === -1) {
+            results.push({ id: element.id, success: false, error: "Could not find end of opening tag" });
+            continue;
+          }
+          
+          // Check if this tag already has an id (shouldn't happen, but safety check)
+          const tagContent = content.substring(absoluteTagStart, tagEndPos);
+          if (/\bid\s*=/.test(tagContent)) {
+            results.push({ id: element.id, success: false, error: "Tag already has id attribute" });
+            continue;
+          }
+          
+          // Inject the id after the tag name
+          const insertPos = absoluteTagStart + tagName.length + 1; // Right after <TagName
+          
+          // Determine what comes after the tag name
+          const charAfterTagName = content[insertPos];
+          let injection: string;
+          
+          if (charAfterTagName === '\n' || charAfterTagName === '\r') {
+            // Multi-line format: <Button\n  variant=...
+            const nextLineStart = content.indexOf('\n', insertPos) + 1;
+            const nextLineMatch = content.substring(nextLineStart).match(/^(\s*)/);
+            const indent = nextLineMatch ? nextLineMatch[1] : '  ';
+            injection = `\n${indent}id="${element.suggestedId}"`;
+          } else if (charAfterTagName === ' ' || charAfterTagName === '\t') {
+            // Single-line format with space: <h1 className=...
+            injection = ` id="${element.suggestedId}"`;
+          } else if (charAfterTagName === '>' || charAfterTagName === '/') {
+            // Self-closing without attributes: <Input/> or <h1>
+            injection = ` id="${element.suggestedId}"`;
+          } else {
+            // Unknown format, try with space
+            injection = ` id="${element.suggestedId}"`;
+          }
+          
+          // Perform the injection
+          const newContent = content.substring(0, insertPos) + injection + content.substring(insertPos);
+          
+          fs.writeFileSync(fullPath, newContent, "utf-8");
+          results.push({ id: element.id, success: true });
+        } catch (error) {
+          results.push({ id: element.id, success: false, error: String(error) });
+        }
+      }
+      
+      const successCount = results.filter(r => r.success).length;
+      const failCount = results.filter(r => !r.success).length;
+      const categoryLabel = category || "elements";
+      
+      return NextResponse.json({
+        success: true,
+        message: `Tagged ${successCount} ${categoryLabel}. ${failCount} failed.`,
+        results,
+      });
+    }
+    
+    return NextResponse.json(
+      { error: "Unknown action" },
+      { status: 400 }
+    );
+  } catch (error) {
+    console.error("Error in bulk operation:", error);
+    return NextResponse.json(
+      { error: "Failed to perform bulk operation", details: String(error) },
+      { status: 500 }
+    );
+  }
+}
+