sonance-brand-mcp 1.3.56 → 1.3.58

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

@@ -40,12 +40,14 @@ interface VisionFileModification {
 }
 
 interface ApplyFirstRequest {
-  action: "apply" | "accept" | "revert";
+  action: "apply" | "accept" | "revert" | "preview";
   sessionId?: string;
   screenshot?: string;
   pageRoute?: string;
   userPrompt?: string;
   focusedElements?: VisionFocusedElement[];
+  // For applying a previously previewed set of modifications
+  previewedModifications?: VisionFileModification[];
 }
 
 interface BackupManifest {
@@ -436,102 +438,41 @@ function searchFilesSmart(
   return sortedResults.map(r => ({ path: r.path, content: r.content, score: r.score }));
 }
 
-const VISION_SYSTEM_PROMPT = `You are an expert React/TypeScript developer with vision capabilities. You can see screenshots and modify code.
-
-═══════════════════════════════════════════════════════════════════════════════
-UNDERSTAND THE USER'S REQUEST NATURALLY
-═══════════════════════════════════════════════════════════════════════════════
-
-Read the user's request and do exactly what they ask. You know React, TypeScript, Tailwind CSS, and JSX - use that knowledge naturally.
-
-- If they say "add X", ADD X to the code (don't replace or remove anything else)
-- If they say "change X to Y", find X and change it to Y
-- If they say "make X bigger/smaller/different color", adjust the relevant properties
-- If they say "remove X", remove X
-- If they say "wrap X with Y", add Y as a parent around X
-
-For any change:
-1. Read the code context provided
-2. Understand what the user wants
-3. Generate patches that accomplish exactly that
-4. If adding a component/icon requires an import, include a patch for the import too
-
-Don't overthink - just make the change the user requested.
-
-═══════════════════════════════════════════════════════════════════════════════
-PATCH FORMAT
-═══════════════════════════════════════════════════════════════════════════════
-
-Return search/replace patches (NOT full files). The system applies your patches to the original.
-
-**Patch Rules:**
-- "search" must match the original code EXACTLY (including whitespace/indentation)
-- "replace" contains your modified version
-- Include 2-4 lines of context in "search" to make it unique
-- You may ONLY edit files provided in the PAGE CONTEXT section
-- CRITICAL: NEVER invent or guess code. Your "search" string MUST be copied EXACTLY from the provided file content. If you cannot find the exact code to modify, return an empty modifications array.
-- If the file content appears truncated, only modify code that is visible in the provided content.
-
-═══════════════════════════════════════════════════════════════════════════════
-SONANCE BRAND COLOR SYSTEM
-═══════════════════════════════════════════════════════════════════════════════
-
-**Core Colors:**
-- Primary (Charcoal): #333F48 - main text, dark backgrounds
-- Accent (Cyan "The Beam"): #00D3C8 - highlights, interactive elements, CTAs
-- Success: Green tones - positive states, confirmations
-- Warning: Amber/Orange tones - caution states, alerts
-- Destructive: Red tones - errors, delete actions
-
-**CRITICAL CONTRAST RULES:**
-When using colored backgrounds, ALWAYS use high-contrast text:
-
-| Background        | Use This Text                      | NEVER Use              |
-|-------------------|------------------------------------|-----------------------|
-| bg-accent         | text-white                         | text-accent-foreground |
-| bg-primary        | text-primary-foreground, text-white | text-primary          |
-| bg-success        | text-white                         | text-success          |
-| bg-warning        | text-white                         | text-warning          |
-| bg-destructive    | text-white                         | text-destructive      |
-
-**SEMANTIC TOKEN PATTERNS:**
-- text-{color} = the color itself (use on NEUTRAL backgrounds like white/gray)
-- text-{color}-foreground = INTENDED for text on {color} backgrounds, but MAY have contrast issues
-- bg-{color} = background in that color
-- WHEN IN DOUBT: Use text-white on any colored background for guaranteed contrast
-
-**BUTTON PATTERNS (Sonance Standard):**
-- Primary CTA: bg-primary text-primary-foreground
-- Accent/Highlight: bg-accent text-white (NOT text-accent-foreground)
-- Success: bg-success text-white
-- Warning: bg-warning text-white
-- Destructive: bg-destructive text-white
-- Outlined: border-border bg-transparent text-foreground
-
-**COMMON MISTAKES TO AVOID:**
-- WRONG: bg-accent text-accent-foreground (accent-foreground is often dark = invisible text)
-- RIGHT: bg-accent text-white (white text on cyan = visible)
-- WRONG: bg-primary text-primary (same color = invisible)
-- RIGHT: bg-primary text-primary-foreground OR text-white
-
-**RESPONSE FORMAT:**
-CRITICAL: Return ONLY the JSON object below. Do NOT include any text, explanation, or thinking before or after the JSON. No preamble. No "Looking at the screenshot..." No markdown code blocks. Just raw JSON:
+const VISION_SYSTEM_PROMPT = `You are a code editor. Make ONLY the change the user requested.
+
+RULES:
+1. Make the SMALLEST possible change to accomplish the request
+2. Do NOT refactor, rebrand, or "improve" anything else
+3. Do NOT change import statements unless explicitly required
+4. Do NOT change component libraries (e.g., heroui to shadcn)
+5. If fixing a color/visibility issue, change ONLY that element's classes
+6. Your patch should typically be 1-5 lines, not 50+
+7. NEVER invent or guess code - your "search" string MUST match the file EXACTLY
+8. NEVER change data mappings (icon names, keys, enum values) unless user explicitly provides the new values
+9. If you don't know what values exist in a database or data source, DO NOT guess - ask for clarification
+
+CRITICAL - DATA INTEGRITY:
+- If code references database values (like icon_name, type, status), DO NOT change the mapping keys
+- You cannot see database content - only change STRUCTURE, not DATA MAPPINGS
+- Example: If you see iconMap["EyeOff"] = SomeIcon, do NOT change "EyeOff" to something else
+- If user wants different icons, they must tell you the EXACT icon names they want
+
+PATCH FORMAT:
+Return ONLY raw JSON (no markdown, no preamble):
 {
-  "reasoning": "What you understood from the request and your plan",
-  "modifications": [
-    {
-      "filePath": "path/to/file.tsx",
-      "patches": [
-        {
-          "search": "exact code to find",
-          "replace": "the replacement code",
-          "explanation": "what this patch does"
-        }
-      ]
-    }
-  ],
-  "explanation": "summary of changes made"
-}`;
+  "reasoning": "brief explanation",
+  "modifications": [{
+    "filePath": "path/to/file.tsx",
+    "patches": [{
+      "search": "exact original code (copy from provided file)",
+      "replace": "minimal change",
+      "explanation": "what this does"
+    }]
+  }],
+  "explanation": "summary"
+}
+
+If you cannot find the exact code to modify, OR if you would need to guess data values, return empty modifications array with explanation.`;
 
 export async function POST(request: Request) {
   // Only allow in development
@@ -544,7 +485,7 @@ export async function POST(request: Request) {
 
   try {
     const body: ApplyFirstRequest = await request.json();
-    const { action, sessionId, screenshot, pageRoute, userPrompt, focusedElements } = body;
+    const { action, sessionId, screenshot, pageRoute, userPrompt, focusedElements, previewedModifications } = body;
     const projectRoot = process.cwd();
 
     // ========== ACCEPT ACTION ==========
@@ -571,6 +512,8 @@ export async function POST(request: Request) {
 
     // ========== REVERT ACTION ==========
     if (action === "revert") {
+      console.log(`[Apply-First] Revert requested for session: ${sessionId}`);
+      
       if (!sessionId) {
         return NextResponse.json(
           { error: "sessionId is required for revert action" },
@@ -579,6 +522,7 @@ export async function POST(request: Request) {
       }
 
       const result = await revertFromBackups(sessionId, projectRoot);
+      console.log(`[Apply-First] Revert result:`, result);
 
       return NextResponse.json({
         success: result.success,
@@ -588,11 +532,44 @@ export async function POST(request: Request) {
       });
     }
 
-    // ========== APPLY ACTION ==========
-    if (action === "apply") {
+    // ========== APPLY FROM PREVIEW ACTION ==========
+    // When user accepts a preview, apply the previously generated modifications
+    if (action === "apply" && previewedModifications && previewedModifications.length > 0) {
+      debugLog("Applying previewed modifications", { 
+        count: previewedModifications.length,
+        files: previewedModifications.map(m => m.filePath)
+      });
+      
+      const newSessionId = randomUUID().slice(0, 8);
+      
+      const applyResult = await applyChangesWithBackup(
+        previewedModifications,
+        newSessionId,
+        projectRoot
+      );
+
+      if (!applyResult.success) {
+        return NextResponse.json(
+          { error: applyResult.error || "Failed to apply previewed changes" },
+          { status: 500 }
+        );
+      }
+
+      return NextResponse.json({
+        success: true,
+        sessionId: newSessionId,
+        modifications: previewedModifications,
+        backupPaths: applyResult.backupPaths,
+        explanation: "Applied previewed changes",
+      });
+    }
+
+    // ========== APPLY/PREVIEW ACTION (with LLM) ==========
+    // Both actions do LLM work; "preview" returns without writing, "apply" writes to files
+    if (action === "apply" || action === "preview") {
       if (!userPrompt) {
         return NextResponse.json(
-          { error: "userPrompt is required for apply action" },
+          { error: "userPrompt is required for apply/preview action" },
           { status: 400 }
         );
       }
@@ -699,111 +676,6 @@ export async function POST(request: Request) {
         });
       }
 
-      // ========== PHASE A: VISUAL PROBLEM ANALYSIS ==========
-      // Before generating patches, analyze WHAT is visually wrong
-      // This forces the LLM to articulate the problem before trying to fix it
-      interface VisualAnalysis {
-        element: string;
-        problem: string;
-        currentState: string;
-        solution: string;
-        confidence: "high" | "medium" | "low";
-      }
-      
-      let visualAnalysis: VisualAnalysis | null = null;
-      
-      if (screenshot && userPrompt) {
-        debugLog("Phase A: Starting visual problem analysis");
-        
-        const analysisClient = new Anthropic({ apiKey });
-        
-        try {
-          const analysisResponse = await analysisClient.messages.create({
-            model: "claude-sonnet-4-20250514",
-            max_tokens: 1024,
-            messages: [
-              {
-                role: "user",
-                content: [
-                  {
-                    type: "image",
-                    source: {
-                      type: "base64",
-                      media_type: "image/png",
-                      data: base64Data,
-                    },
-                  },
-                  {
-                    type: "text",
-                    text: `You are analyzing a UI screenshot to understand a visual problem.
-
-User request: "${userPrompt}"
-
-${focusedElements && focusedElements.length > 0 ? `User clicked on these elements:
-${focusedElements.map((el) => `- ${el.name} (${el.type}) at position (${el.coordinates.x}, ${el.coordinates.y})`).join("\n")}
-` : ""}
-
-BEFORE any code changes can be made, you must analyze the visual problem.
-
-Answer these questions:
-1. ELEMENT: Which specific UI element has the problem? (describe its location, text content, appearance)
-2. PROBLEM: What exactly is visually wrong? (invisible text, wrong color, poor contrast, wrong size, etc.)
-3. CURRENT STATE: What styling/colors appear to be applied to this element?
-4. SOLUTION: What specific CSS/Tailwind change would fix this problem?
-5. CONFIDENCE: How confident are you that you've identified the correct element and problem? (high/medium/low)
-
-Return ONLY valid JSON with no other text:
-{
-  "element": "specific description of the UI element",
-  "problem": "what is visually wrong",
-  "currentState": "what styling appears to be applied",
-  "solution": "specific CSS/Tailwind fix needed",
-  "confidence": "high"
-}`,
-                  },
-                ],
-              },
-            ],
-          });
-          
-          const analysisText = analysisResponse.content.find((block) => block.type === "text");
-          if (analysisText && analysisText.type === "text") {
-            // Parse the JSON response
-            let jsonText = analysisText.text.trim();
-            // Extract JSON if wrapped in code blocks
-            const jsonMatch = jsonText.match(/```(?:json)?\s*([\s\S]*?)\s*```/) || jsonText.match(/(\{[\s\S]*\})/);
-            if (jsonMatch) {
-              jsonText = jsonMatch[1];
-            }
-            
-            try {
-              visualAnalysis = JSON.parse(jsonText) as VisualAnalysis;
-              debugLog("Phase A: Visual problem analysis complete", visualAnalysis);
-              
-              // If low confidence, return early with clarification request
-              if (visualAnalysis.confidence === "low") {
-                debugLog("Phase A: Low confidence - requesting clarification");
-                return NextResponse.json({
-                  success: false,
-                  needsClarification: true,
-                  analysis: visualAnalysis,
-                  message: `I can see "${visualAnalysis.element}" but I'm not certain about the problem: "${visualAnalysis.problem}". Can you be more specific about what needs to change?`,
-                });
-              }
-            } catch (parseError) {
-              debugLog("Phase A: Failed to parse analysis response", { 
-                error: String(parseError), 
-                response: jsonText.substring(0, 500) 
-              });
-              // Continue without analysis if parsing fails
-            }
-          }
-        } catch (analysisError) {
-          debugLog("Phase A: Analysis call failed", { error: String(analysisError) });
-          // Continue without analysis - fall back to existing behavior
-        }
-      }
-
       // ========== SMART CONTEXT BUDGETING ==========
       // Claude can handle 200k tokens (~800k chars), so we can safely include large files
       // Priority: Recommended file (NEVER truncate) > Page file (limited) > Other components (dynamic)
@@ -837,24 +709,6 @@ User Request: "${userPrompt}"
         textContent += `FOCUSED ELEMENTS (user clicked on these):
 ${focusedElements.map((el) => `- ${el.name} (${el.type}) at (${el.coordinates.x}, ${el.coordinates.y})`).join("\n")}
 
-`;
-      }
-
-      // ========== VISUAL PROBLEM ANALYSIS (from Phase A) ==========
-      if (visualAnalysis) {
-        textContent += `═══════════════════════════════════════════════════════════════════════════════
-🔍 VISUAL PROBLEM ANALYSIS (I analyzed the screenshot first)
-═══════════════════════════════════════════════════════════════════════════════
-
-**Element:** ${visualAnalysis.element}
-**Problem:** ${visualAnalysis.problem}
-**Current State:** ${visualAnalysis.currentState}
-**Required Fix:** ${visualAnalysis.solution}
-**Confidence:** ${visualAnalysis.confidence}
-
-⚠️ IMPORTANT: Your patches MUST implement the fix described above for the element described above.
-Find the code that renders "${visualAnalysis.element}" and apply "${visualAnalysis.solution}".
-
 `;
       }
 
@@ -922,17 +776,27 @@ ${truncatedContent}${wasTruncated ? "\n// ... (truncated)" : ""}
         }
       }
 
-      // ========== THEME DISCOVERY ==========
+      // ========== THEME DISCOVERY (REFERENCE ONLY) ==========
       // Dynamically discover theme tokens from the target codebase
+      // This is marked as REFERENCE ONLY so the LLM doesn't use it to justify extra changes
       const discoveredTheme = await discoverTheme(projectRoot);
       const themeContext = formatThemeForPrompt(discoveredTheme);
       
       if (discoveredTheme.discoveredFiles.length > 0) {
         textContent += `
 ═══════════════════════════════════════════════════════════════════════════════
-${themeContext}
+REFERENCE ONLY (do not use this to justify additional changes)
 ═══════════════════════════════════════════════════════════════════════════════
 
+If you need to pick a color for a VISIBILITY fix, these are safe choices:
+- bg-accent text-white (cyan button with white text)
+- bg-primary text-white (charcoal button with white text)
+- bg-success text-white (green button with white text)
+- bg-destructive text-white (red button with white text)
+
+But ONLY use these if the user is asking for a color/visibility change.
+Do NOT rebrand or change other elements to match.
+
 `;
         debugLog("Theme discovery complete", {
           filesFound: discoveredTheme.discoveredFiles,
@@ -1305,7 +1169,23 @@ This is better than generating patches with made-up code.`,
         break;
       } // End of retry loop
 
-      // Create backups and apply changes atomically
+      // ========== PREVIEW MODE: Return modifications without writing ==========
+      if (action === "preview") {
+        debugLog("Preview mode: returning modifications without applying", {
+          fileCount: modifications.length,
+          files: modifications.map(m => m.filePath)
+        });
+        
+        return NextResponse.json({
+          success: true,
+          preview: true,
+          modifications,
+          explanation: finalExplanation,
+          reasoning: finalReasoning,
+        });
+      }
+
+      // ========== APPLY MODE: Create backups and apply changes atomically ==========
       const applyResult = await applyChangesWithBackup(
         modifications,
         newSessionId,
@@ -1330,7 +1210,7 @@ This is better than generating patches with made-up code.`,
     }
 
     return NextResponse.json(
-      { error: "Invalid action. Use 'apply', 'accept', or 'revert'." },
+      { error: "Invalid action. Use 'apply', 'preview', 'accept', or 'revert'." },
       { status: 400 }
     );
   } catch (error) {
@@ -1350,6 +1230,12 @@ async function applyChangesWithBackup(
   sessionId: string,
   projectRoot: string
 ): Promise<{ success: boolean; backupPaths: string[]; error?: string }> {
+  console.log(`[Apply-First] applyChangesWithBackup called`, {
+    sessionId,
+    fileCount: modifications.length,
+    files: modifications.map(m => m.filePath)
+  });
+  
   const backupDir = path.join(projectRoot, BACKUP_ROOT, sessionId);
   const backupPaths: string[] = [];
 
@@ -1364,6 +1250,7 @@ async function applyChangesWithBackup(
 
   try {
     // Step 1: Create backup directory
+    console.log(`[Apply-First] Creating backup directory: ${backupDir}`);
     fs.mkdirSync(backupDir, { recursive: true });
 
     // Step 2: Create ALL backups FIRST (before any writes)
@@ -1377,6 +1264,9 @@ async function applyChangesWithBackup(
         fs.mkdirSync(backupDirForFile, { recursive: true });
         fs.copyFileSync(fullPath, backupPath);
         backupPaths.push(backupPath);
+        console.log(`[Apply-First] Backed up: ${mod.filePath}`);
+      } else {
+        console.log(`[Apply-First] New file (no backup needed): ${mod.filePath}`);
       }
     }
 
@@ -1391,10 +1281,9 @@ async function applyChangesWithBackup(
       })),
     };
 
-    fs.writeFileSync(
-      path.join(backupDir, "manifest.json"),
-      JSON.stringify(manifest, null, 2)
-    );
+    const manifestPath = path.join(backupDir, "manifest.json");
+    fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+    console.log(`[Apply-First] Manifest written: ${manifestPath}`);
 
     // Step 4: Apply all changes
     for (const mod of modifications) {
@@ -1412,8 +1301,10 @@ async function applyChangesWithBackup(
       }
 
       fs.writeFileSync(fullPath, mod.modifiedContent, "utf-8");
+      console.log(`[Apply-First] File written: ${mod.filePath}`);
     }
 
+    console.log(`[Apply-First] All changes applied successfully, session: ${sessionId}`);
     return { success: true, backupPaths };
   } catch (error) {
     // Rollback on error - restore all backed up files

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

@@ -434,104 +434,43 @@ function searchFilesSmart(
   return sortedResults.map(r => ({ path: r.path, content: r.content, score: r.score }));
 }
 
-const VISION_SYSTEM_PROMPT = `You are an expert React/TypeScript developer with vision capabilities. You can see screenshots and modify code.
-
-═══════════════════════════════════════════════════════════════════════════════
-UNDERSTAND THE USER'S REQUEST NATURALLY
-═══════════════════════════════════════════════════════════════════════════════
-
-Read the user's request and do exactly what they ask. You know React, TypeScript, Tailwind CSS, and JSX - use that knowledge naturally.
-
-- If they say "add X", ADD X to the code (don't replace or remove anything else)
-- If they say "change X to Y", find X and change it to Y
-- If they say "make X bigger/smaller/different color", adjust the relevant properties
-- If they say "remove X", remove X
-- If they say "wrap X with Y", add Y as a parent around X
-
-For any change:
-1. Read the code context provided
-2. Understand what the user wants
-3. Generate patches that accomplish exactly that
-4. If adding a component/icon requires an import, include a patch for the import too
-
-Don't overthink - just make the change the user requested.
-
-═══════════════════════════════════════════════════════════════════════════════
-PATCH FORMAT
-═══════════════════════════════════════════════════════════════════════════════
-
-Return search/replace patches (NOT full files). The system applies your patches to the original.
-
-**Patch Rules:**
-- "search" must match the original code EXACTLY (including whitespace/indentation)
-- "replace" contains your modified version
-- Include 2-4 lines of context in "search" to make it unique
-- You may ONLY edit files provided in the PAGE CONTEXT section
-- CRITICAL: NEVER invent or guess code. Your "search" string MUST be copied EXACTLY from the provided file content. If you cannot find the exact code to modify, return an empty modifications array.
-- If the file content appears truncated, only modify code that is visible in the provided content.
-
-═══════════════════════════════════════════════════════════════════════════════
-SONANCE BRAND COLOR SYSTEM
-═══════════════════════════════════════════════════════════════════════════════
-
-**Core Colors:**
-- Primary (Charcoal): #333F48 - main text, dark backgrounds
-- Accent (Cyan "The Beam"): #00D3C8 - highlights, interactive elements, CTAs
-- Success: Green tones - positive states, confirmations
-- Warning: Amber/Orange tones - caution states, alerts
-- Destructive: Red tones - errors, delete actions
-
-**CRITICAL CONTRAST RULES:**
-When using colored backgrounds, ALWAYS use high-contrast text:
-
-| Background        | Use This Text                      | NEVER Use              |
-|-------------------|------------------------------------|-----------------------|
-| bg-accent         | text-white                         | text-accent-foreground |
-| bg-primary        | text-primary-foreground, text-white | text-primary          |
-| bg-success        | text-white                         | text-success          |
-| bg-warning        | text-white                         | text-warning          |
-| bg-destructive    | text-white                         | text-destructive      |
-
-**SEMANTIC TOKEN PATTERNS:**
-- text-{color} = the color itself (use on NEUTRAL backgrounds like white/gray)
-- text-{color}-foreground = INTENDED for text on {color} backgrounds, but MAY have contrast issues
-- bg-{color} = background in that color
-- WHEN IN DOUBT: Use text-white on any colored background for guaranteed contrast
-
-**BUTTON PATTERNS (Sonance Standard):**
-- Primary CTA: bg-primary text-primary-foreground
-- Accent/Highlight: bg-accent text-white (NOT text-accent-foreground)
-- Success: bg-success text-white
-- Warning: bg-warning text-white
-- Destructive: bg-destructive text-white
-- Outlined: border-border bg-transparent text-foreground
-
-**COMMON MISTAKES TO AVOID:**
-- WRONG: bg-accent text-accent-foreground (accent-foreground is often dark = invisible text)
-- RIGHT: bg-accent text-white (white text on cyan = visible)
-- WRONG: bg-primary text-primary (same color = invisible)
-- RIGHT: bg-primary text-primary-foreground OR text-white
-
-**RESPONSE FORMAT:**
-CRITICAL: Return ONLY the JSON object below. Do NOT include any text, explanation, or thinking before or after the JSON. No preamble. No "Looking at the screenshot..." No markdown code blocks. Just raw JSON:
+const VISION_SYSTEM_PROMPT = `You are a code editor. Make ONLY the change the user requested.
+
+RULES:
+1. Make the SMALLEST possible change to accomplish the request
+2. Do NOT refactor, rebrand, or "improve" anything else
+3. Do NOT change import statements unless explicitly required
+4. Do NOT change component libraries (e.g., heroui to shadcn)
+5. If fixing a color/visibility issue, change ONLY that element's classes
+6. Your patch should typically be 1-5 lines, not 50+
+7. NEVER invent or guess code - your "search" string MUST match the file EXACTLY
+8. NEVER change data mappings (icon names, keys, enum values) unless user explicitly provides the new values
+9. If you don't know what values exist in a database or data source, DO NOT guess - ask for clarification
+
+CRITICAL - DATA INTEGRITY:
+- If code references database values (like icon_name, type, status), DO NOT change the mapping keys
+- You cannot see database content - only change STRUCTURE, not DATA MAPPINGS
+- Example: If you see iconMap["EyeOff"] = SomeIcon, do NOT change "EyeOff" to something else
+- If user wants different icons, they must tell you the EXACT icon names they want
+
+PATCH FORMAT:
+Return ONLY raw JSON (no markdown, no preamble):
 {
-  "reasoning": "What you understood from the request and your plan",
-  "modifications": [
-    {
-      "filePath": "path/to/file.tsx",
-      "patches": [
-        {
-          "search": "exact code to find",
-          "replace": "the replacement code",
-          "explanation": "what this patch does"
-        }
-      ],
-      "previewCSS": "optional CSS for live preview"
-    }
-  ],
+  "reasoning": "brief explanation",
+  "modifications": [{
+    "filePath": "path/to/file.tsx",
+    "patches": [{
+      "search": "exact original code (copy from provided file)",
+      "replace": "minimal change",
+      "explanation": "what this does"
+    }],
+    "previewCSS": "optional CSS for live preview"
+  }],
   "aggregatedPreviewCSS": "combined CSS for all changes",
-  "explanation": "summary of changes made"
-}`;
+  "explanation": "summary"
+}
+
+If you cannot find the exact code to modify, OR if you would need to guess data values, return empty modifications array with explanation.`;
 
 export async function POST(request: Request) {
   // Only allow in development
@@ -708,111 +647,6 @@ export async function POST(request: Request) {
         });
       }
 
-      // ========== PHASE A: VISUAL PROBLEM ANALYSIS ==========
-      // Before generating patches, analyze WHAT is visually wrong
-      // This forces the LLM to articulate the problem before trying to fix it
-      interface VisualAnalysis {
-        element: string;
-        problem: string;
-        currentState: string;
-        solution: string;
-        confidence: "high" | "medium" | "low";
-      }
-      
-      let visualAnalysis: VisualAnalysis | null = null;
-      
-      if (screenshot && userPrompt) {
-        debugLog("Phase A: Starting visual problem analysis");
-        
-        const analysisClient = new Anthropic({ apiKey });
-        
-        try {
-          const analysisResponse = await analysisClient.messages.create({
-            model: "claude-sonnet-4-20250514",
-            max_tokens: 1024,
-            messages: [
-              {
-                role: "user",
-                content: [
-                  {
-                    type: "image",
-                    source: {
-                      type: "base64",
-                      media_type: "image/png",
-                      data: base64Data,
-                    },
-                  },
-                  {
-                    type: "text",
-                    text: `You are analyzing a UI screenshot to understand a visual problem.
-
-User request: "${userPrompt}"
-
-${focusedElements && focusedElements.length > 0 ? `User clicked on these elements:
-${focusedElements.map((el) => `- ${el.name} (${el.type}) at position (${el.coordinates.x}, ${el.coordinates.y})`).join("\n")}
-` : ""}
-
-BEFORE any code changes can be made, you must analyze the visual problem.
-
-Answer these questions:
-1. ELEMENT: Which specific UI element has the problem? (describe its location, text content, appearance)
-2. PROBLEM: What exactly is visually wrong? (invisible text, wrong color, poor contrast, wrong size, etc.)
-3. CURRENT STATE: What styling/colors appear to be applied to this element?
-4. SOLUTION: What specific CSS/Tailwind change would fix this problem?
-5. CONFIDENCE: How confident are you that you've identified the correct element and problem? (high/medium/low)
-
-Return ONLY valid JSON with no other text:
-{
-  "element": "specific description of the UI element",
-  "problem": "what is visually wrong",
-  "currentState": "what styling appears to be applied",
-  "solution": "specific CSS/Tailwind fix needed",
-  "confidence": "high"
-}`,
-                  },
-                ],
-              },
-            ],
-          });
-          
-          const analysisText = analysisResponse.content.find((block) => block.type === "text");
-          if (analysisText && analysisText.type === "text") {
-            // Parse the JSON response
-            let jsonText = analysisText.text.trim();
-            // Extract JSON if wrapped in code blocks
-            const jsonMatch = jsonText.match(/```(?:json)?\s*([\s\S]*?)\s*```/) || jsonText.match(/(\{[\s\S]*\})/);
-            if (jsonMatch) {
-              jsonText = jsonMatch[1];
-            }
-            
-            try {
-              visualAnalysis = JSON.parse(jsonText) as VisualAnalysis;
-              debugLog("Phase A: Visual problem analysis complete", visualAnalysis);
-              
-              // If low confidence, return early with clarification request
-              if (visualAnalysis.confidence === "low") {
-                debugLog("Phase A: Low confidence - requesting clarification");
-                return NextResponse.json({
-                  success: false,
-                  needsClarification: true,
-                  analysis: visualAnalysis,
-                  message: `I can see "${visualAnalysis.element}" but I'm not certain about the problem: "${visualAnalysis.problem}". Can you be more specific about what needs to change?`,
-                });
-              }
-            } catch (parseError) {
-              debugLog("Phase A: Failed to parse analysis response", { 
-                error: String(parseError), 
-                response: jsonText.substring(0, 500) 
-              });
-              // Continue without analysis if parsing fails
-            }
-          }
-        } catch (analysisError) {
-          debugLog("Phase A: Analysis call failed", { error: String(analysisError) });
-          // Continue without analysis - fall back to existing behavior
-        }
-      }
-
       // ========== SMART CONTEXT BUDGETING ==========
       // Claude can handle 200k tokens (~800k chars), so we can safely include large files
       // Priority: Recommended file (NEVER truncate) > Page file (limited) > Other components (dynamic)
@@ -846,24 +680,6 @@ User Request: "${userPrompt}"
         textContent += `FOCUSED ELEMENTS (user clicked on these):
 ${focusedElements.map((el) => `- ${el.name} (${el.type}) at (${el.coordinates.x}, ${el.coordinates.y})`).join("\n")}
 
-`;
-      }
-
-      // ========== VISUAL PROBLEM ANALYSIS (from Phase A) ==========
-      if (visualAnalysis) {
-        textContent += `═══════════════════════════════════════════════════════════════════════════════
-🔍 VISUAL PROBLEM ANALYSIS (I analyzed the screenshot first)
-═══════════════════════════════════════════════════════════════════════════════
-
-**Element:** ${visualAnalysis.element}
-**Problem:** ${visualAnalysis.problem}
-**Current State:** ${visualAnalysis.currentState}
-**Required Fix:** ${visualAnalysis.solution}
-**Confidence:** ${visualAnalysis.confidence}
-
-⚠️ IMPORTANT: Your patches MUST implement the fix described above for the element described above.
-Find the code that renders "${visualAnalysis.element}" and apply "${visualAnalysis.solution}".
-
 `;
       }
 
@@ -931,17 +747,27 @@ ${truncatedContent}${wasTruncated ? "\n// ... (truncated)" : ""}
         }
       }
 
-      // ========== THEME DISCOVERY ==========
+      // ========== THEME DISCOVERY (REFERENCE ONLY) ==========
       // Dynamically discover theme tokens from the target codebase
+      // This is marked as REFERENCE ONLY so the LLM doesn't use it to justify extra changes
       const discoveredTheme = await discoverTheme(projectRoot);
       const themeContext = formatThemeForPrompt(discoveredTheme);
       
       if (discoveredTheme.discoveredFiles.length > 0) {
         textContent += `
 ═══════════════════════════════════════════════════════════════════════════════
-${themeContext}
+REFERENCE ONLY (do not use this to justify additional changes)
 ═══════════════════════════════════════════════════════════════════════════════
 
+If you need to pick a color for a VISIBILITY fix, these are safe choices:
+- bg-accent text-white (cyan button with white text)
+- bg-primary text-white (charcoal button with white text)
+- bg-success text-white (green button with white text)
+- bg-destructive text-white (red button with white text)
+
+But ONLY use these if the user is asking for a color/visibility change.
+Do NOT rebrand or change other elements to match.
+
 `;
         debugLog("Theme discovery complete", {
           filesFound: discoveredTheme.discoveredFiles,

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

@@ -1,16 +1,148 @@
 "use client";
 
-import React, { useState, useEffect } from "react";
-import { X, Zap, Loader2, Check, Undo, ChevronDown, ChevronRight, FileCode, AlertTriangle, RefreshCw, Info } from "lucide-react";
+import React, { useState, useEffect, useCallback } from "react";
+import { X, Zap, Loader2, Check, ChevronDown, ChevronRight, FileCode, AlertTriangle, Info, Eye, EyeOff } from "lucide-react";
 import { cn } from "../../../lib/utils";
 import { ApplyFirstSession, ApplyFirstStatus, VisionFileModification } from "../types";
 
+// CSS Injection Preview ID
+const PREVIEW_STYLE_ID = "sonance-preview-css";
+
+/**
+ * Extract className changes from a diff
+ * Returns: { removed: string[], added: string[] }
+ */
+function extractClassNameChanges(diff: string): { removed: string[]; added: string[] } {
+  const removed: string[] = [];
+  const added: string[] = [];
+  
+  // Regex to find className="..." patterns
+  const classNameRegex = /className=["']([^"']+)["']/g;
+  
+  const lines = diff.split("\n");
+  for (const line of lines) {
+    if (line.startsWith("-") && !line.startsWith("---")) {
+      // Removed line - extract className
+      let match;
+      while ((match = classNameRegex.exec(line)) !== null) {
+        removed.push(...match[1].split(/\s+/));
+      }
+    } else if (line.startsWith("+") && !line.startsWith("+++")) {
+      // Added line - extract className
+      let match;
+      while ((match = classNameRegex.exec(line)) !== null) {
+        added.push(...match[1].split(/\s+/));
+      }
+    }
+  }
+  
+  return { removed, added };
+}
+
+/**
+ * Common Tailwind class to CSS mapping for preview
+ * Only covers the most common styling classes for quick previews
+ */
+const TAILWIND_TO_CSS: Record<string, string> = {
+  // Text colors
+  "text-white": "color: white !important;",
+  "text-black": "color: black !important;",
+  "text-gray-900": "color: rgb(17, 24, 39) !important;",
+  "text-gray-700": "color: rgb(55, 65, 81) !important;",
+  "text-gray-500": "color: rgb(107, 114, 128) !important;",
+  
+  // Sonance brand colors
+  "text-sonance-charcoal": "color: #333F48 !important;",
+  "text-sonance-blue": "color: #00D3C8 !important;",
+  "border-sonance-charcoal": "border-color: #333F48 !important;",
+  "border-sonance-blue": "border-color: #00D3C8 !important;",
+  "bg-sonance-charcoal": "background-color: #333F48 !important;",
+  "bg-sonance-blue": "background-color: #00D3C8 !important;",
+  
+  // Semantic colors
+  "text-primary": "color: var(--primary) !important;",
+  "text-primary-foreground": "color: var(--primary-foreground) !important;",
+  "text-accent": "color: var(--accent) !important;",
+  "text-accent-foreground": "color: var(--accent-foreground) !important;",
+  "bg-primary": "background-color: hsl(var(--primary)) !important;",
+  "bg-accent": "background-color: hsl(var(--accent)) !important;",
+  
+  // Common backgrounds
+  "bg-white": "background-color: white !important;",
+  "bg-black": "background-color: black !important;",
+  "bg-gray-100": "background-color: rgb(243, 244, 246) !important;",
+  "bg-gray-200": "background-color: rgb(229, 231, 235) !important;",
+  
+  // Borders
+  "border-gray-200": "border-color: rgb(229, 231, 235) !important;",
+  "border-gray-300": "border-color: rgb(209, 213, 219) !important;",
+};
+
+/**
+ * Generate CSS for preview based on class changes
+ */
+function generatePreviewCSS(modifications: VisionFileModification[]): string {
+  const cssRules: string[] = [];
+  
+  for (const mod of modifications) {
+    const { added } = extractClassNameChanges(mod.diff);
+    
+    // Generate CSS for added classes
+    for (const cls of added) {
+      if (TAILWIND_TO_CSS[cls]) {
+        // We can't know the exact selector, so we apply to elements with data-sonance-preview
+        cssRules.push(TAILWIND_TO_CSS[cls]);
+      }
+    }
+  }
+  
+  if (cssRules.length === 0) return "";
+  
+  // Apply to changed elements (marked by InspectorOverlay)
+  return `
+    [data-sonance-changed="true"] {
+      ${cssRules.join("\n      ")}
+      outline: 2px dashed #00D3C8 !important;
+      outline-offset: 2px !important;
+    }
+  `;
+}
+
+/**
+ * Inject preview CSS into the document
+ */
+function injectPreviewCSS(css: string): void {
+  // Remove existing preview styles first
+  removePreviewCSS();
+  
+  if (!css.trim()) return;
+  
+  const style = document.createElement("style");
+  style.id = PREVIEW_STYLE_ID;
+  style.textContent = css;
+  document.head.appendChild(style);
+  
+  console.log("[Preview CSS] Injected:", css.substring(0, 200));
+}
+
+/**
+ * Remove preview CSS from the document
+ */
+function removePreviewCSS(): void {
+  const existing = document.getElementById(PREVIEW_STYLE_ID);
+  if (existing) {
+    existing.remove();
+    console.log("[Preview CSS] Removed");
+  }
+}
+
 export interface ApplyFirstPreviewProps {
   session: ApplyFirstSession;
   status: ApplyFirstStatus;
   onAccept: () => void;
   onRevert: () => void;
   onForceClear?: () => void; // Force clear stale sessions
+  onApplyPreview?: () => void; // Apply previewed changes (for preview mode)
 }
 
 function FileModificationCard({
@@ -78,7 +210,7 @@ function HMRStatusBadge({ status }: { status: ApplyFirstStatus }) {
   if (status === "waiting-hmr") {
     return (
       <span className="flex items-center gap-1 text-[10px] px-1.5 py-0.5 rounded bg-amber-100 text-amber-700">
-        <RefreshCw className="h-3 w-3 animate-spin" />
+        <Loader2 className="h-3 w-3 animate-spin" />
         Refreshing...
       </span>
     );
@@ -92,6 +224,15 @@ function HMRStatusBadge({ status }: { status: ApplyFirstStatus }) {
       </span>
     );
   }
+  
+  if (status === "previewing") {
+    return (
+      <span className="flex items-center gap-1 text-[10px] px-1.5 py-0.5 rounded bg-blue-100 text-blue-700">
+        <Eye className="h-3 w-3" />
+        Preview Mode
+      </span>
+    );
+  }
 
   return null;
 }
@@ -102,8 +243,10 @@ export function ApplyFirstPreview({
   onAccept,
   onRevert,
   onForceClear,
+  onApplyPreview,
 }: ApplyFirstPreviewProps) {
   const [expandedFiles, setExpandedFiles] = useState<Set<string>>(new Set());
+  const [cssPreviewEnabled, setCssPreviewEnabled] = useState(true);
 
   // Expand first file by default
   useEffect(() => {
@@ -111,6 +254,32 @@ export function ApplyFirstPreview({
       setExpandedFiles(new Set([session.modifications[0].filePath]));
     }
   }, [session]);
+  
+  // CSS Preview injection for preview mode
+  useEffect(() => {
+    const isPreviewMode = session.isPreview === true;
+    
+    if (isPreviewMode && cssPreviewEnabled) {
+      // Generate and inject preview CSS
+      const previewCSS = generatePreviewCSS(session.modifications);
+      if (previewCSS) {
+        injectPreviewCSS(previewCSS);
+      }
+    } else {
+      // Remove preview CSS when not in preview mode or disabled
+      removePreviewCSS();
+    }
+    
+    // Cleanup on unmount
+    return () => {
+      removePreviewCSS();
+    };
+  }, [session, cssPreviewEnabled]);
+  
+  // Toggle CSS preview
+  const toggleCssPreview = useCallback(() => {
+    setCssPreviewEnabled(prev => !prev);
+  }, []);
 
   const toggleFile = (filePath: string) => {
     setExpandedFiles((prev) => {
@@ -125,26 +294,55 @@ export function ApplyFirstPreview({
   };
 
   const fileCount = session.modifications.length;
-  const isLoading = status === "accepting" || status === "reverting";
+  const isLoading = status === "accepting" || status === "reverting" || status === "applying";
   const isStaleSession = fileCount === 0 || status === "error";
+  const isPreviewMode = session.isPreview === true;
 
   return (
-    <div className="space-y-3 p-3 rounded border border-green-300 bg-green-50">
+    <div className={cn(
+      "space-y-3 p-3 rounded border",
+      isPreviewMode 
+        ? "border-blue-300 bg-blue-50" 
+        : "border-green-300 bg-green-50"
+    )}>
       {/* Header */}
       <div className="flex items-center justify-between">
         <div className="flex items-center gap-2">
-          <Zap className="h-4 w-4 text-green-600" />
+          <Zap className={cn("h-4 w-4", isPreviewMode ? "text-blue-600" : "text-green-600")} />
           <span className="text-xs font-semibold text-gray-900">
-            Changes Applied
+            {isPreviewMode ? "Proposed Changes" : "Changes Applied"}
           </span>
-          <span className="text-[10px] px-1.5 py-0.5 rounded bg-green-200 text-green-700 font-medium">
+          <span className={cn(
+            "text-[10px] px-1.5 py-0.5 rounded font-medium",
+            isPreviewMode 
+              ? "bg-blue-200 text-blue-700" 
+              : "bg-green-200 text-green-700"
+          )}>
             {fileCount} file{fileCount !== 1 ? "s" : ""}
           </span>
         </div>
-        <HMRStatusBadge status={status} />
+        <div className="flex items-center gap-2">
+          {/* CSS Preview Toggle (only in preview mode) */}
+          {isPreviewMode && (
+            <button
+              onClick={toggleCssPreview}
+              className={cn(
+                "flex items-center gap-1 text-[10px] px-1.5 py-0.5 rounded transition-colors",
+                cssPreviewEnabled
+                  ? "bg-blue-200 text-blue-700"
+                  : "bg-gray-200 text-gray-500"
+              )}
+              title={cssPreviewEnabled ? "Hide CSS preview" : "Show CSS preview"}
+            >
+              {cssPreviewEnabled ? <Eye className="h-3 w-3" /> : <EyeOff className="h-3 w-3" />}
+              CSS
+            </button>
+          )}
+          <HMRStatusBadge status={status} />
+        </div>
       </div>
 
-      {/* Info Banner - show different message for stale sessions */}
+      {/* Info Banner - different messages for preview vs applied vs stale */}
       {isStaleSession ? (
         <div className="flex items-start gap-2 p-2 rounded bg-amber-50 border border-amber-200">
           <AlertTriangle className="h-3.5 w-3.5 text-amber-600 mt-0.5 flex-shrink-0" />
@@ -153,6 +351,14 @@ export function ApplyFirstPreview({
             Use &quot;Force Clear&quot; to dismiss this panel.
           </span>
         </div>
+      ) : isPreviewMode ? (
+        <div className="flex items-start gap-2 p-2 rounded bg-blue-50 border border-blue-200">
+          <Info className="h-3.5 w-3.5 text-blue-600 mt-0.5 flex-shrink-0" />
+          <span className="text-xs text-blue-700">
+            <strong>Review the changes below.</strong> Click Accept to apply them to your files,
+            or Reject to discard.
+          </span>
+        </div>
       ) : (
         <div className="flex items-start gap-2 p-2 rounded bg-blue-50 border border-blue-200">
           <Info className="h-3.5 w-3.5 text-blue-600 mt-0.5 flex-shrink-0" />
@@ -175,43 +381,47 @@ export function ApplyFirstPreview({
         ))}
       </div>
 
-      {/* Warning about navigation */}
-      <div className="flex items-start gap-2 p-2 rounded bg-amber-50 border border-amber-200">
-        <AlertTriangle className="h-3.5 w-3.5 text-amber-600 mt-0.5 flex-shrink-0" />
-        <span className="text-xs text-amber-700">
-          Navigating away will automatically revert changes. Make sure to accept or revert first.
-        </span>
-      </div>
+      {/* Warning about navigation - only show for applied mode */}
+      {!isPreviewMode && (
+        <div className="flex items-start gap-2 p-2 rounded bg-amber-50 border border-amber-200">
+          <AlertTriangle className="h-3.5 w-3.5 text-amber-600 mt-0.5 flex-shrink-0" />
+          <span className="text-xs text-amber-700">
+            Navigating away will automatically revert changes. Make sure to accept or revert first.
+          </span>
+        </div>
+      )}
 
       {/* Action Buttons */}
       <div className="flex gap-2">
-        {/* Accept Button - hide for stale sessions */}
+        {/* Accept/Apply Button - behavior depends on mode */}
         {!isStaleSession && (
           <button
-            onClick={onAccept}
+            onClick={isPreviewMode && onApplyPreview ? onApplyPreview : onAccept}
             disabled={isLoading}
             className={cn(
               "flex-1 flex items-center justify-center gap-2 py-2.5",
               "text-xs font-medium rounded transition-colors",
-              "bg-green-600 text-white hover:bg-green-700",
+              isPreviewMode 
+                ? "bg-blue-600 text-white hover:bg-blue-700"
+                : "bg-green-600 text-white hover:bg-green-700",
               "disabled:opacity-50 disabled:cursor-not-allowed"
             )}
           >
-            {status === "accepting" ? (
+            {status === "accepting" || status === "applying" ? (
               <>
                 <Loader2 className="h-3.5 w-3.5 animate-spin" />
-                Accepting...
+                {isPreviewMode ? "Applying..." : "Accepting..."}
               </>
             ) : (
               <>
                 <Check className="h-3.5 w-3.5" />
-                Keep Changes
+                {isPreviewMode ? "Accept & Apply" : "Keep Changes"}
               </>
             )}
           </button>
         )}
 
-        {/* Revert Button */}
+        {/* Reject/Revert Button */}
         <button
           onClick={onRevert}
           disabled={isLoading}
@@ -225,12 +435,12 @@ export function ApplyFirstPreview({
           {status === "reverting" ? (
             <>
               <Loader2 className="h-3.5 w-3.5 animate-spin" />
-              Reverting...
+              {isPreviewMode ? "Discarding..." : "Reverting..."}
             </>
           ) : (
             <>
-              <Undo className="h-3.5 w-3.5" />
-              Revert
+              <X className="h-3.5 w-3.5" />
+              {isPreviewMode ? "Reject" : "Revert"}
             </>
           )}
         </button>
@@ -255,7 +465,7 @@ export function ApplyFirstPreview({
 
       {/* Session Info (for debugging) */}
       <div className="text-[10px] text-gray-400 font-mono">
-        Session: {session.sessionId} | Applied: {new Date(session.appliedAt).toLocaleTimeString()}
+        {isPreviewMode ? "Preview" : "Session"}: {session.sessionId} | {isPreviewMode ? "Generated" : "Applied"}: {new Date(session.appliedAt).toLocaleTimeString()}
       </div>
     </div>
   );

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

@@ -144,6 +144,7 @@ export function ChatInterface({
         method: "POST",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify({
+          // Apply-First: write files immediately so HMR shows changes
           action: useApplyFirst ? "apply" : "edit",
           screenshot,
           pageRoute: window.location.pathname,
@@ -176,7 +177,7 @@ export function ChatInterface({
 
       if (data.success && data.modifications) {
         if (useApplyFirst && onApplyFirstComplete) {
-          // Apply-First mode: files are already written
+          // Apply-First mode: files are already written, user can see changes via HMR
           console.log("[Apply-First] Calling onApplyFirstComplete with:", {
             sessionId: data.sessionId,
             modifications: data.modifications.map((m: { filePath: string }) => m.filePath),

package/dist/assets/dev-tools/panels/ComponentsPanel.tsx

@@ -50,13 +50,14 @@ export interface ComponentsPanelProps {
   visionPendingEdit?: VisionPendingEdit | null;
   onSaveVisionEdit?: () => void;
   onClearVisionPendingEdit?: () => void;
-  // Apply-First Mode props
+  // Apply-First Mode props (now Preview-First for Cursor-style flow)
   applyFirstSession?: ApplyFirstSession | null;
   applyFirstStatus?: ApplyFirstStatus;
   onApplyFirstComplete?: (session: ApplyFirstSession) => void;
   onApplyFirstAccept?: () => void;
   onApplyFirstRevert?: () => void;
   onApplyFirstForceClear?: () => void;
+  onApplyPreview?: () => void; // Apply previewed modifications to files
 }
 
 export function ComponentsPanel({ 
@@ -97,6 +98,7 @@ export function ComponentsPanel({
   onApplyFirstAccept,
   onApplyFirstRevert,
   onApplyFirstForceClear,
+  onApplyPreview,
 }: ComponentsPanelProps) {
   // Auto-activate inspector when entering this tab
   useEffect(() => {
@@ -573,7 +575,7 @@ export function ComponentsPanel({
               />
             )}
 
-            {/* Apply-First Mode Preview - NEW: Changes already applied */}
+            {/* Preview-First Mode - Shows diff, user accepts/rejects before applying */}
             {applyFirstSession && onApplyFirstAccept && onApplyFirstRevert && (
               <ApplyFirstPreview
                 session={applyFirstSession}
@@ -581,6 +583,7 @@ export function ComponentsPanel({
                 onAccept={onApplyFirstAccept}
                 onRevert={onApplyFirstRevert}
                 onForceClear={onApplyFirstForceClear}
+                onApplyPreview={onApplyPreview}
               />
             )}
 

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

@@ -255,28 +255,31 @@ export interface VisionPendingEdit {
   explanation: string;
 }
 
-// ---- Apply-First Mode Types (Cursor-style instant preview) ----
+// ---- Preview-First Mode Types (Cursor-style) ----
+// Flow: LLM generates patches -> Show diff preview -> User accepts/rejects -> Apply to files
 
 export interface ApplyFirstSession {
   sessionId: string;
   modifications: VisionFileModification[];
   appliedAt: number;
-  status: 'applied' | 'accepted' | 'reverted';
+  status: 'preview' | 'applied' | 'accepted' | 'reverted';
   backupPaths: string[];
+  isPreview?: boolean; // True if changes are not yet written to disk
 }
 
 export type ApplyFirstStatus =
   | 'idle'           // No active session
   | 'generating'     // AI is generating changes
+  | 'previewing'     // User is reviewing proposed changes (not yet applied)
   | 'applying'       // Writing files to disk
   | 'waiting-hmr'    // Waiting for HMR to show changes
-  | 'reviewing'      // User is reviewing actual changes
+  | 'reviewing'      // User is reviewing actual changes (files written)
   | 'accepting'      // User clicked accept, cleaning up backups
   | 'reverting'      // User clicked revert, restoring backups
   | 'error';         // Something went wrong
 
 export interface ApplyFirstRequest {
-  action: "apply" | "accept" | "revert";
+  action: "apply" | "preview" | "accept" | "revert";
   sessionId?: string;
   screenshot?: string;
   pageRoute?: string;

package/package.json

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