ts migration, semantics and visual context

Author: mhmzdev

src/extractors/components/extractor.ts

@@ -16,6 +16,7 @@ import type {
     TextInfo,
     ComponentExtractionOptions
 } from './types.js';
+import { detectSemanticTypeAdvanced, generateSemanticContext } from '../../tools/flutter/semantic-detection.js';
 
 /**
  * Extract component metadata
@@ -163,7 +164,9 @@ export function analyzeChildren(
                 nestedComponents.push(createNestedComponentInfo(child));
             }
 
-            children.push(createComponentChild(child, importance, isComponent, options));
+            // Pass parent and siblings for better semantic detection
+            const siblings = visibleChildren.filter(sibling => sibling.id !== child.id);
+            children.push(createComponentChild(child, importance, isComponent, options, node, siblings));
         } else {
             // Track skipped nodes
             skippedNodes.push({
@@ -200,7 +203,9 @@ export function createComponentChild(
     node: FigmaNode,
     importance: number,
     isNestedComponent: boolean,
-    options: Required<ComponentExtractionOptions>
+    options: Required<ComponentExtractionOptions>,
+    parent?: FigmaNode,
+    siblings?: FigmaNode[]
 ): ComponentChild {
     const child: ComponentChild = {
         nodeId: node.id,
@@ -219,7 +224,7 @@ export function createComponentChild(
 
         // Extract text info for text nodes
         if (node.type === 'TEXT' && options.extractTextContent) {
-            child.basicInfo.text = extractTextInfo(node);
+            child.basicInfo.text = extractTextInfo(node, parent, siblings);
         }
     }
 
@@ -439,7 +444,7 @@ export function extractBasicStyling(node: FigmaNode): Partial<StylingInfo> {
 /**
  * Extract enhanced text information
  */
-export function extractTextInfo(node: FigmaNode): TextInfo | undefined {
+export function extractTextInfo(node: FigmaNode, parent?: FigmaNode, siblings?: FigmaNode[]): TextInfo | undefined {
     if (node.type !== 'TEXT') return undefined;
 
     const textContent = getActualTextContent(node);
@@ -453,7 +458,7 @@ export function extractTextInfo(node: FigmaNode): TextInfo | undefined {
         fontWeight: node.style?.fontWeight,
         textAlign: node.style?.textAlignHorizontal,
         textCase: detectTextCase(textContent),
-        semanticType: detectSemanticType(textContent, node.name),
+        semanticType: detectSemanticType(textContent, node.name, node, parent, siblings),
         placeholder: isPlaceholder
     };
 }
@@ -670,16 +675,52 @@ function detectTextCase(content: string): 'uppercase' | 'lowercase' | 'capitaliz
 
 /**
  * Detect semantic type of text based on content and context
+ * Enhanced with multi-factor analysis and confidence scoring
  */
-function detectSemanticType(content: string, nodeName: string): 'heading' | 'body' | 'label' | 'button' | 'link' | 'caption' | 'error' | 'success' | 'warning' | 'other' {
-    const lowerContent = content.toLowerCase().trim();
-    const lowerNodeName = nodeName.toLowerCase();
-
+function detectSemanticType(
+    content: string, 
+    nodeName: string, 
+    node?: any, 
+    parent?: any, 
+    siblings?: any[]
+): 'heading' | 'body' | 'label' | 'button' | 'link' | 'caption' | 'error' | 'success' | 'warning' | 'other' {
     // Skip detection for placeholder text
     if (isPlaceholderText(content)) {
         return 'other';
     }
 
+    // Use advanced semantic detection if node properties are available
+    if (node) {
+        try {
+            const context = generateSemanticContext(node, parent, siblings);
+            const classification = detectSemanticTypeAdvanced(content, nodeName, context, node);
+            
+            // Only use advanced classification if confidence is high enough
+            if (classification.confidence >= 0.6) {
+                return classification.type;
+            }
+            
+            // Log reasoning for debugging (in development)
+            if (process.env.NODE_ENV === 'development') {
+                console.debug(`Low confidence (${classification.confidence}) for "${content}": ${classification.reasoning.join(', ')}`);
+            }
+        } catch (error) {
+            // Fall back to legacy detection if advanced detection fails
+            console.warn('Advanced semantic detection failed, using legacy method:', error);
+        }
+    }
+
+    // Legacy detection as fallback
+    return detectSemanticTypeLegacy(content, nodeName);
+}
+
+/**
+ * Legacy semantic type detection (fallback)
+ */
+function detectSemanticTypeLegacy(content: string, nodeName: string): 'heading' | 'body' | 'label' | 'button' | 'link' | 'caption' | 'error' | 'success' | 'warning' | 'other' {
+    const lowerContent = content.toLowerCase().trim();
+    const lowerNodeName = nodeName.toLowerCase();
+
     // Button text patterns - exact matches for common button labels
     const buttonPatterns = [
         /^(click|tap|press|submit|send|save|cancel|ok|yes|no|continue|next|back|close|done|finish|start|begin)$/i,

src/extractors/screens/extractor.ts

@@ -21,6 +21,7 @@ import {
     calculateVisualImportance,
     isComponentNode
 } from '../components/extractor.js';
+import { detectSectionTypeAdvanced } from '../../tools/flutter/semantic-detection.js';
 
 /**
  * Extract screen metadata
@@ -100,11 +101,14 @@ export function analyzeScreenSections(
     });
 
     // Analyze each child as potential section
-    const sectionsWithImportance = visibleChildren.map(child => ({
-        node: child,
-        importance: calculateSectionImportance(child),
-        sectionType: detectSectionType(child)
-    }));
+    const sectionsWithImportance = visibleChildren.map(child => {
+        const siblings = visibleChildren.filter(sibling => sibling.id !== child.id);
+        return {
+            node: child,
+            importance: calculateSectionImportance(child),
+            sectionType: detectSectionType(child, node, siblings)
+        };
+    });
 
     // Sort by importance
     sectionsWithImportance.sort((a, b) => b.importance - a.importance);
@@ -193,13 +197,15 @@ function createScreenSection(
                 components.push(createNestedComponentInfo(child));
             }
 
+            // Pass parent and siblings for better semantic detection
+            const siblings = visibleChildren.filter(sibling => sibling.id !== child.id);
             children.push(createComponentChild(child, childImportance, isComponent, {
                 maxChildNodes: 20, // Higher limit for screens
                 maxDepth: options.maxDepth,
                 includeHiddenNodes: options.includeHiddenNodes,
                 prioritizeComponents: true,
                 extractTextContent: true
-            }));
+            }, node, siblings));
         });
     }
 
@@ -247,8 +253,35 @@ function calculateSectionImportance(node: FigmaNode): number {
 
 /**
  * Detect section type based on node properties
+ * Enhanced with multi-factor analysis and confidence scoring
+ */
+function detectSectionType(node: FigmaNode, parent?: FigmaNode, siblings?: FigmaNode[]): ScreenSection['type'] {
+    // Try advanced detection first
+    try {
+        const classification = detectSectionTypeAdvanced(node, parent, siblings);
+        
+        // Use advanced classification if confidence is high enough
+        if (classification.confidence >= 0.6) {
+            return classification.type as ScreenSection['type'];
+        }
+        
+        // Log reasoning for debugging (in development)
+        if (process.env.NODE_ENV === 'development') {
+            console.debug(`Low confidence (${classification.confidence}) for section "${node.name}": ${classification.reasoning.join(', ')}`);
+        }
+    } catch (error) {
+        // Fall back to legacy detection if advanced detection fails
+        console.warn('Advanced section detection failed, using legacy method:', error);
+    }
+
+    // Legacy detection as fallback
+    return detectSectionTypeLegacy(node);
+}
+
+/**
+ * Legacy section type detection (fallback)
  */
-function detectSectionType(node: FigmaNode): ScreenSection['type'] {
+function detectSectionTypeLegacy(node: FigmaNode): ScreenSection['type'] {
     const name = node.name.toLowerCase();
     const bounds = node.absoluteBoundingBox;
 

src/services/figma.ts

@@ -1,6 +1,6 @@
 // services/figma.mts
 import fetch from 'node-fetch';
-import type {FigmaFile, FigmaNode, FigmaFileInfo, FigmaPageInfo, NodeResponse, PageResponse} from '../types/figma.js';
+import type {FigmaNode, NodeResponse} from '../types/figma.js';
 import {
     FigmaError,
     FigmaAuthError,
@@ -88,30 +88,6 @@ export class FigmaService {
         });
     }
 
-    /**
-     * Get complete Figma file data
-     */
-    async getFile(fileId: string): Promise<FigmaFile> {
-        if (!fileId || fileId.trim().length === 0) {
-            throw new FigmaError('File ID is required', 'INVALID_INPUT');
-        }
-
-        try {
-            const data = await this.makeRequest<FigmaFile>(`/files/${fileId}`);
-
-            if (!data.document || !data.name) {
-                throw new FigmaParseError('Invalid file structure received from Figma API', data);
-            }
-
-            return data;
-        } catch (error) {
-            if (error instanceof FigmaError) {
-                throw error;
-            }
-            throw new FigmaError(`Failed to fetch file ${fileId}: ${error}`, 'FETCH_ERROR');
-        }
-    }
-
     /**
      * Get specific nodes by IDs
      */

src/tools/flutter/assets/assets.ts

@@ -136,12 +136,9 @@ export function registerFlutterAssetTools(server: McpServer, figmaApiKey: string
     );
 }
 
-// Helper functions for filtering image nodes (Figma-specific logic)
+// OPTIMIZED: Helper functions for filtering image nodes - only searches within target nodes
 async function filterImageNodes(fileId: string, targetNodeIds: string[], figmaService: any): Promise<Array<{id: string, name: string, node: any}>> {
-    // Get the full file to access all nodes
-    const file = await figmaService.getFile(fileId);
-
-    // Get the target nodes for boundary checking
+    // OPTIMIZED: Only get the target nodes instead of the entire file (massive performance improvement)
     const targetNodes = await figmaService.getNodes(fileId, targetNodeIds);
 
     const allNodesWithImages: Array<{id: string, name: string, node: any}> = [];
@@ -177,38 +174,17 @@ async function filterImageNodes(fileId: string, targetNodeIds: string[], figmaSe
         }
     }
 
-    // Extract from entire file
-    file.document.children?.forEach((page: any) => {
-        extractImageNodes(page);
-    });
-
-    // Filter to only those within our target nodes
-    const imageNodes = allNodesWithImages.filter(imageNode => {
-        return targetNodeIds.some(targetId => {
-            const targetNode = targetNodes[targetId];
-            return targetNode && isNodeWithinTarget(imageNode.node, targetNode);
-        });
+    // OPTIMIZED: Extract only from target nodes instead of entire file
+    // This eliminates the need for expensive boundary checking since we only search within target nodes
+    Object.values(targetNodes).forEach((node: any) => {
+        extractImageNodes(node);
     });
 
-    return imageNodes;
+    // OPTIMIZED: No filtering needed since we only searched within target nodes
+    return allNodesWithImages;
 }
 
-function isNodeWithinTarget(imageNode: any, targetNode: any): boolean {
-    if (!imageNode.absoluteBoundingBox || !targetNode.absoluteBoundingBox) {
-        return false;
-    }
-
-    const imageBounds = imageNode.absoluteBoundingBox;
-    const targetBounds = targetNode.absoluteBoundingBox;
-
-    // Check if image node is within target node bounds
-    return (
-        imageBounds.x >= targetBounds.x &&
-        imageBounds.y >= targetBounds.y &&
-        imageBounds.x + imageBounds.width <= targetBounds.x + targetBounds.width &&
-        imageBounds.y + imageBounds.height <= targetBounds.y + targetBounds.height
-    );
-}
+// REMOVED: isNodeWithinTarget function no longer needed since we only search within target nodes
 
 function toCamelCase(str: string): string {
     return str

src/tools/flutter/assets/svg-assets.ts

@@ -9,8 +9,8 @@ import {
     downloadImage,
     getFileStats,
     updatePubspecAssets,
-    generateSvgAssetConstants,
-    type AssetInfo
+    type AssetInfo,
+    generateSvgAssetConstants
 } from "./asset-manager.js";
 
 export function registerSvgAssetTools(server: McpServer, figmaApiKey: string) {

src/tools/flutter/components/component-tool.ts

@@ -20,10 +20,10 @@ import {
     generateStructureInspectionReport
 } from "./helpers.js";
 import {
-    generateDeduplicatedReport,
     generateFlutterImplementation,
     generateComprehensiveDeduplicatedReport,
-    generateStyleLibraryReport
+    generateStyleLibraryReport,
+    addVisualContextToDeduplicatedReport
 } from "./deduplicated-helpers.js";
 
 import {
@@ -191,6 +191,17 @@ export function registerComponentTools(server: McpServer, figmaApiKey: string) {
 
                     analysisReport = generateComprehensiveDeduplicatedReport(deduplicatedAnalysis, true);
 
+                    // Add visual context for deduplicated analysis
+                    if (parsedInput.source === 'url') {
+                        // Reconstruct the Figma URL from the parsed input
+                        const figmaUrl = `https://www.figma.com/design/${parsedInput.fileId}/?node-id=${parsedInput.nodeId}`;
+                        analysisReport += "\n\n" + addVisualContextToDeduplicatedReport(
+                            deduplicatedAnalysis, 
+                            figmaUrl, 
+                            parsedInput.nodeId
+                        );
+                    }
+                    
                     if (generateFlutterCode) {
                         analysisReport += "\n\n" + generateFlutterImplementation(deduplicatedAnalysis);
                     }
@@ -536,13 +547,10 @@ export function registerComponentTools(server: McpServer, figmaApiKey: string) {
 }
 
 /**
- * Filter image nodes within a component - reuses logic from assets.mts
+ * OPTIMIZED: Filter image nodes within a component - only searches within target nodes
  */
 async function filterImageNodesInComponent(fileId: string, targetNodeIds: string[], figmaService: FigmaService): Promise<Array<{id: string, name: string, node: any}>> {
-    // Get the full file to access all nodes
-    const file = await figmaService.getFile(fileId);
-
-    // Get the target nodes for boundary checking
+    // OPTIMIZED: Only get the target nodes instead of the entire file (massive performance improvement)
     const targetNodes = await figmaService.getNodes(fileId, targetNodeIds);
 
     const allNodesWithImages: Array<{id: string, name: string, node: any}> = [];
@@ -578,38 +586,17 @@ async function filterImageNodesInComponent(fileId: string, targetNodeIds: string
         }
     }
 
-    // Extract from entire file
-    file.document.children?.forEach((page: any) => {
-        extractImageNodes(page);
-    });
-
-    // Filter to only those within our target nodes
-    const imageNodes = allNodesWithImages.filter(imageNode => {
-        return targetNodeIds.some(targetId => {
-            const targetNode = targetNodes[targetId];
-            return targetNode && isNodeWithinTarget(imageNode.node, targetNode);
-        });
+    // OPTIMIZED: Extract only from target nodes instead of entire file
+    // This eliminates the need for expensive boundary checking since we only search within target nodes
+    Object.values(targetNodes).forEach((node: any) => {
+        extractImageNodes(node);
     });
 
-    return imageNodes;
+    // OPTIMIZED: No filtering needed since we only searched within target nodes
+    return allNodesWithImages;
 }
 
-function isNodeWithinTarget(imageNode: any, targetNode: any): boolean {
-    if (!imageNode.absoluteBoundingBox || !targetNode.absoluteBoundingBox) {
-        return false;
-    }
-
-    const imageBounds = imageNode.absoluteBoundingBox;
-    const targetBounds = targetNode.absoluteBoundingBox;
-
-    // Check if image node is within target node bounds
-    return (
-        imageBounds.x >= targetBounds.x &&
-        imageBounds.y >= targetBounds.y &&
-        imageBounds.x + imageBounds.width <= targetBounds.x + targetBounds.width &&
-        imageBounds.y + imageBounds.height <= targetBounds.y + targetBounds.height
-    );
-}
+// REMOVED: isNodeWithinTarget function no longer needed since we only search within target nodes
 
 /**
  * Export component assets to Flutter project