screenshotSegmenter.js

/**
 * Koda - Intelligent Browser Automation Library
 * This project uses Koda by Trent Pierce
 * https://github.com/TrentPierce/Koda
 * Licensed under the Koda Non-Commercial License
 *
 * Copyright (c) 2026 Trent Pierce. All rights reserved.
 * See LICENSE file for full terms.
 */

const EventEmitter = require('events');

/**
 * Region types identified in screenshots
 * @enum {string}
 */
const RegionType = {
    HEADER: 'header',
    NAVIGATION: 'navigation',
    CONTENT: 'content',
    SIDEBAR: 'sidebar',
    FOOTER: 'footer',
    MODAL: 'modal',
    POPUP: 'popup',
    UNKNOWN: 'unknown'
};

/**
 * Functional area types
 * @enum {string}
 */
const FunctionalAreaType = {
    FORM: 'form',
    BUTTON_GROUP: 'button_group',
    LIST: 'list',
    TABLE: 'table',
    CARD: 'card',
    MENU: 'menu',
    SEARCH: 'search',
    MEDIA: 'media',
    TEXT_CONTENT: 'text_content'
};

/**
 * Screenshot Segmenter for visual region analysis
 * @class
 * @extends EventEmitter
 */
class ScreenshotSegmenter extends EventEmitter {
    /**
     * Create a new ScreenshotSegmenter instance
     * @param {Object} options - Configuration options
     * @param {number} [options.minRegionHeight=50] - Minimum region height in pixels
     * @param {number} [options.headerMaxHeight=200] - Maximum header height
     * @param {number} [options.footerMaxHeight=150] - Maximum footer height
     * @param {number} [options.sidebarMinWidth=150] - Minimum sidebar width
     * @param {boolean} [options.detectResponsive=true] - Enable responsive detection
     */
    constructor(options = {}) {
        super();
        
        this.minRegionHeight = options.minRegionHeight || 50;
        this.headerMaxHeight = options.headerMaxHeight || 200;
        this.footerMaxHeight = options.footerMaxHeight || 150;
        this.sidebarMinWidth = options.sidebarMinWidth || 150;
        this.detectResponsive = options.detectResponsive !== undefined ? options.detectResponsive : true;
        
        this.analysisCache = new Map();
        this.stats = {
            totalAnalyses: 0,
            cacheHits: 0,
            averageAnalysisTime: 0
        };
        
        console.log('[ScreenshotSegmenter] Initialized');
    }
    
    /**
     * Analyze a screenshot to detect regions and functional areas
     * @param {Buffer|string} imageData - Screenshot data (Buffer or base64)
     * @param {Object} metadata - Screenshot metadata
     * @param {number} metadata.width - Image width
     * @param {number} metadata.height - Image height
     * @param {number} [metadata.scrollY=0] - Vertical scroll position
     * @param {number} [metadata.scrollX=0] - Horizontal scroll position
     * @param {Object} [options] - Analysis options
     * @param {boolean} [options.useCache=true] - Use cached results
     * @returns {Promise<Object>} Analysis results
     */
    async analyzeScreenshot(imageData, metadata, options = {}) {
        const startTime = Date.now();
        const useCache = options.useCache !== undefined ? options.useCache : true;
        
        console.log('[ScreenshotSegmenter] Analyzing screenshot:', metadata.width, 'x', metadata.height);
        
        // Check cache
        const cacheKey = this.generateCacheKey(imageData, metadata);
        if (useCache && this.analysisCache.has(cacheKey)) {
            console.log('[ScreenshotSegmenter] Using cached analysis');
            this.stats.cacheHits++;
            return this.analysisCache.get(cacheKey);
        }
        
        try {
            // Perform analysis
            const regions = await this.detectRegions(imageData, metadata);
            const functionalAreas = await this.identifyFunctionalAreas(imageData, metadata, regions);
            const viewport = this.analyzeViewport(metadata);
            const layout = this.analyzeLayout(regions, metadata);
            const responsive = this.detectResponsive ? await this.detectResponsivePatterns(metadata) : null;
            
            const analysis = {
                regions: regions,
                functionalAreas: functionalAreas,
                viewport: viewport,
                layout: layout,
                responsive: responsive,
                metadata: {
                    width: metadata.width,
                    height: metadata.height,
                    scrollY: metadata.scrollY || 0,
                    scrollX: metadata.scrollX || 0,
                    analyzedAt: Date.now()
                }
            };
            
            // Cache result
            this.analysisCache.set(cacheKey, analysis);
            
            // Limit cache size
            if (this.analysisCache.size > 50) {
                const firstKey = this.analysisCache.keys().next().value;
                this.analysisCache.delete(firstKey);
            }
            
            // Update stats
            const duration = Date.now() - startTime;
            this.stats.totalAnalyses++;
            this.stats.averageAnalysisTime = 
                (this.stats.averageAnalysisTime * (this.stats.totalAnalyses - 1) + duration) / this.stats.totalAnalyses;
            
            console.log(`[ScreenshotSegmenter] Analysis completed in ${duration}ms`);
            this.emit('analysis:complete', { analysis, duration });
            
            return analysis;
            
        } catch (error) {
            console.error('[ScreenshotSegmenter] Analysis failed:', error.message);
            this.emit('analysis:error', { error });
            throw error;
        }
    }
    
    /**
     * Detect major page regions
     * @private
     * @param {Buffer|string} imageData - Image data
     * @param {Object} metadata - Image metadata
     * @returns {Promise<Array>} Detected regions
     */
    async detectRegions(imageData, metadata) {
        const regions = [];
        const { width, height } = metadata;
        
        // Header detection (top of page)
        const headerRegion = this.detectHeaderRegion(width, height);
        if (headerRegion) {
            regions.push(headerRegion);
        }
        
        // Footer detection (bottom of page)
        const footerRegion = this.detectFooterRegion(width, height);
        if (footerRegion) {
            regions.push(footerRegion);
        }
        
        // Sidebar detection (left or right)
        const sidebarRegions = this.detectSidebarRegions(width, height);
        regions.push(...sidebarRegions);
        
        // Content area (remaining space)
        const contentRegion = this.detectContentRegion(width, height, regions);
        if (contentRegion) {
            regions.push(contentRegion);
        }
        
        // Modal/popup detection (overlays)
        const modalRegions = this.detectModalRegions(width, height);
        regions.push(...modalRegions);
        
        return regions;
    }
    
    /**
     * Detect header region
     * @private
     * @param {number} width - Image width
     * @param {number} height - Image height
     * @returns {Object|null} Header region
     */
    detectHeaderRegion(width, height) {
        // Headers typically occupy top 50-200px
        const headerHeight = Math.min(this.headerMaxHeight, height * 0.15);
        
        if (headerHeight < this.minRegionHeight) {
            return null;
        }
        
        return {
            type: RegionType.HEADER,
            x: 0,
            y: 0,
            width: width,
            height: headerHeight,
            confidence: 0.8,
            characteristics: {
                position: 'fixed-top',
                likelyContains: ['logo', 'navigation', 'search', 'account']
            }
        };
    }
    
    /**
     * Detect footer region
     * @private
     * @param {number} width - Image width
     * @param {number} height - Image height
     * @returns {Object|null} Footer region
     */
    detectFooterRegion(width, height) {
        // Footers typically occupy bottom 100-150px
        const footerHeight = Math.min(this.footerMaxHeight, height * 0.12);
        
        if (footerHeight < this.minRegionHeight) {
            return null;
        }
        
        return {
            type: RegionType.FOOTER,
            x: 0,
            y: height - footerHeight,
            width: width,
            height: footerHeight,
            confidence: 0.75,
            characteristics: {
                position: 'bottom',
                likelyContains: ['links', 'copyright', 'social', 'contact']
            }
        };
    }
    
    /**
     * Detect sidebar regions
     * @private
     * @param {number} width - Image width
     * @param {number} height - Image height
     * @returns {Array} Sidebar regions
     */
    detectSidebarRegions(width, height) {
        const sidebars = [];
        
        // Left sidebar detection (common in dashboards)
        const leftSidebarWidth = Math.min(300, width * 0.2);
        if (leftSidebarWidth >= this.sidebarMinWidth) {
            sidebars.push({
                type: RegionType.SIDEBAR,
                x: 0,
                y: this.headerMaxHeight,
                width: leftSidebarWidth,
                height: height - this.headerMaxHeight - this.footerMaxHeight,
                confidence: 0.6,
                characteristics: {
                    position: 'left',
                    likelyContains: ['navigation', 'filters', 'menu']
                }
            });
        }
        
        // Right sidebar detection (less common, usually ads or related content)
        const rightSidebarWidth = Math.min(250, width * 0.15);
        if (rightSidebarWidth >= this.sidebarMinWidth && width > 1200) {
            sidebars.push({
                type: RegionType.SIDEBAR,
                x: width - rightSidebarWidth,
                y: this.headerMaxHeight,
                width: rightSidebarWidth,
                height: height - this.headerMaxHeight - this.footerMaxHeight,
                confidence: 0.5,
                characteristics: {
                    position: 'right',
                    likelyContains: ['ads', 'related', 'widgets']
                }
            });
        }
        
        return sidebars;
    }
    
    /**
     * Detect content region
     * @private
     * @param {number} width - Image width
     * @param {number} height - Image height
     * @param {Array} existingRegions - Already detected regions
     * @returns {Object|null} Content region
     */
    detectContentRegion(width, height, existingRegions) {
        // Content is the remaining space after header, footer, sidebars
        let contentX = 0;
        let contentY = this.headerMaxHeight;
        let contentWidth = width;
        let contentHeight = height - this.headerMaxHeight - this.footerMaxHeight;
        
        // Adjust for sidebars
        const leftSidebar = existingRegions.find(r => 
            r.type === RegionType.SIDEBAR && r.characteristics.position === 'left'
        );
        const rightSidebar = existingRegions.find(r => 
            r.type === RegionType.SIDEBAR && r.characteristics.position === 'right'
        );
        
        if (leftSidebar) {
            contentX = leftSidebar.width;
            contentWidth -= leftSidebar.width;
        }
        
        if (rightSidebar) {
            contentWidth -= rightSidebar.width;
        }
        
        if (contentWidth < 100 || contentHeight < 100) {
            return null;
        }
        
        return {
            type: RegionType.CONTENT,
            x: contentX,
            y: contentY,
            width: contentWidth,
            height: contentHeight,
            confidence: 0.9,
            characteristics: {
                position: 'center',
                likelyContains: ['main-content', 'articles', 'forms', 'data']
            }
        };
    }
    
    /**
     * Detect modal/popup regions
     * @private
     * @param {number} width - Image width
     * @param {number} height - Image height
     * @returns {Array} Modal regions
     */
    detectModalRegions(width, height) {
        // Modals are typically centered and overlay content
        // This is a heuristic detection based on common patterns
        const modals = [];
        
        // Centered modal (common pattern)
        const modalWidth = Math.min(600, width * 0.7);
        const modalHeight = Math.min(400, height * 0.6);
        
        if (modalWidth > 200 && modalHeight > 150) {
            modals.push({
                type: RegionType.MODAL,
                x: (width - modalWidth) / 2,
                y: (height - modalHeight) / 2,
                width: modalWidth,
                height: modalHeight,
                confidence: 0.3, // Low confidence without actual detection
                characteristics: {
                    position: 'centered-overlay',
                    likelyContains: ['dialog', 'form', 'message']
                }
            });
        }
        
        return modals;
    }
    
    /**
     * Identify functional areas within regions
     * @private
     * @param {Buffer|string} imageData - Image data
     * @param {Object} metadata - Image metadata
     * @param {Array} regions - Detected regions
     * @returns {Promise<Array>} Functional areas
     */
    async identifyFunctionalAreas(imageData, metadata, regions) {
        const functionalAreas = [];
        
        // Search for common functional patterns
        for (const region of regions) {
            // Form detection
            const forms = this.detectForms(region, metadata);
            functionalAreas.push(...forms);
            
            // Button group detection
            const buttonGroups = this.detectButtonGroups(region, metadata);
            functionalAreas.push(...buttonGroups);
            
            // List detection
            const lists = this.detectLists(region, metadata);
            functionalAreas.push(...lists);
            
            // Table detection
            const tables = this.detectTables(region, metadata);
            functionalAreas.push(...tables);
            
            // Card layout detection
            const cards = this.detectCards(region, metadata);
            functionalAreas.push(...cards);
        }
        
        return functionalAreas;
    }
    
    /**
     * Detect form areas
     * @private
     * @param {Object} region - Region to analyze
     * @param {Object} metadata - Image metadata
     * @returns {Array} Form areas
     */
    detectForms(region, metadata) {
        const forms = [];
        
        // Forms typically have vertical stacking of input fields
        // Common in login pages, contact forms, etc.
        if (region.type === RegionType.CONTENT || region.type === RegionType.MODAL) {
            forms.push({
                type: FunctionalAreaType.FORM,
                region: region.type,
                x: region.x + region.width * 0.1,
                y: region.y + 50,
                width: region.width * 0.8,
                height: Math.min(400, region.height * 0.6),
                confidence: 0.5,
                characteristics: {
                    layout: 'vertical-stack',
                    expectedElements: ['input', 'label', 'button']
                }
            });
        }
        
        return forms;
    }
    
    /**
     * Detect button groups
     * @private
     * @param {Object} region - Region to analyze
     * @param {Object} metadata - Image metadata
     * @returns {Array} Button group areas
     */
    detectButtonGroups(region, metadata) {
        const buttonGroups = [];
        
        // Button groups typically appear in headers, footers, or form bottoms
        if (region.type === RegionType.HEADER || region.type === RegionType.FOOTER) {
            buttonGroups.push({
                type: FunctionalAreaType.BUTTON_GROUP,
                region: region.type,
                x: region.x + region.width * 0.7,
                y: region.y + 10,
                width: region.width * 0.25,
                height: 40,
                confidence: 0.6,
                characteristics: {
                    layout: 'horizontal',
                    expectedElements: ['button', 'link']
                }
            });
        }
        
        return buttonGroups;
    }
    
    /**
     * Detect list areas
     * @private
     * @param {Object} region - Region to analyze
     * @param {Object} metadata - Image metadata
     * @returns {Array} List areas
     */
    detectLists(region, metadata) {
        const lists = [];
        
        // Lists are common in sidebars and content areas
        if (region.type === RegionType.SIDEBAR) {
            lists.push({
                type: FunctionalAreaType.LIST,
                region: region.type,
                x: region.x + 10,
                y: region.y + 20,
                width: region.width - 20,
                height: region.height * 0.8,
                confidence: 0.7,
                characteristics: {
                    layout: 'vertical-list',
                    expectedElements: ['list-item', 'link']
                }
            });
        }
        
        return lists;
    }
    
    /**
     * Detect table areas
     * @private
     * @param {Object} region - Region to analyze
     * @param {Object} metadata - Image metadata
     * @returns {Array} Table areas
     */
    detectTables(region, metadata) {
        const tables = [];
        
        // Tables are common in content areas
        if (region.type === RegionType.CONTENT) {
            tables.push({
                type: FunctionalAreaType.TABLE,
                region: region.type,
                x: region.x + 20,
                y: region.y + 50,
                width: region.width - 40,
                height: Math.min(500, region.height * 0.7),
                confidence: 0.4,
                characteristics: {
                    layout: 'grid',
                    expectedElements: ['table', 'row', 'cell']
                }
            });
        }
        
        return tables;
    }
    
    /**
     * Detect card layouts
     * @private
     * @param {Object} region - Region to analyze
     * @param {Object} metadata - Image metadata
     * @returns {Array} Card areas
     */
    detectCards(region, metadata) {
        const cards = [];
        
        // Card layouts are common in modern web design
        if (region.type === RegionType.CONTENT) {
            const cardWidth = Math.min(300, region.width * 0.3);
            const cardHeight = 250;
            const cardsPerRow = Math.floor(region.width / (cardWidth + 20));
            
            for (let i = 0; i < Math.min(6, cardsPerRow * 2); i++) {
                const row = Math.floor(i / cardsPerRow);
                const col = i % cardsPerRow;
                
                cards.push({
                    type: FunctionalAreaType.CARD,
                    region: region.type,
                    x: region.x + col * (cardWidth + 20) + 10,
                    y: region.y + row * (cardHeight + 20) + 10,
                    width: cardWidth,
                    height: cardHeight,
                    confidence: 0.5,
                    characteristics: {
                        layout: 'card-grid',
                        expectedElements: ['image', 'title', 'description', 'button']
                    }
                });
            }
        }
        
        return cards;
    }
    
    /**
     * Analyze viewport information
     * @private
     * @param {Object} metadata - Image metadata
     * @returns {Object} Viewport analysis
     */
    analyzeViewport(metadata) {
        const { width, height, scrollY = 0, scrollX = 0 } = metadata;
        
        return {
            width: width,
            height: height,
            scrollY: scrollY,
            scrollX: scrollX,
            isAtTop: scrollY === 0,
            isAtBottom: false, // Would need page height to determine
            visiblePercentage: 100, // Percentage of page visible
            orientation: width > height ? 'landscape' : 'portrait',
            aspectRatio: (width / height).toFixed(2)
        };
    }
    
    /**
     * Analyze page layout
     * @private
     * @param {Array} regions - Detected regions
     * @param {Object} metadata - Image metadata
     * @returns {Object} Layout analysis
     */
    analyzeLayout(regions, metadata) {
        const hasHeader = regions.some(r => r.type === RegionType.HEADER);
        const hasFooter = regions.some(r => r.type === RegionType.FOOTER);
        const hasSidebar = regions.some(r => r.type === RegionType.SIDEBAR);
        const hasModal = regions.some(r => r.type === RegionType.MODAL);
        
        // Determine layout pattern
        let layoutPattern = 'simple';
        if (hasHeader && hasFooter && hasSidebar) {
            layoutPattern = 'dashboard';
        } else if (hasHeader && hasFooter) {
            layoutPattern = 'standard';
        } else if (hasSidebar) {
            layoutPattern = 'sidebar-content';
        }
        
        return {
            pattern: layoutPattern,
            hasHeader: hasHeader,
            hasFooter: hasFooter,
            hasSidebar: hasSidebar,
            hasModal: hasModal,
            regionCount: regions.length,
            complexity: this.calculateLayoutComplexity(regions),
            grid: this.detectGridSystem(metadata)
        };
    }
    
    /**
     * Calculate layout complexity
     * @private
     * @param {Array} regions - Detected regions
     * @returns {string} Complexity level
     */
    calculateLayoutComplexity(regions) {
        const score = regions.length;
        
        if (score <= 3) return 'simple';
        if (score <= 6) return 'moderate';
        return 'complex';
    }
    
    /**
     * Detect grid system
     * @private
     * @param {Object} metadata - Image metadata
     * @returns {Object} Grid information
     */
    detectGridSystem(metadata) {
        const { width } = metadata;
        
        // Common grid systems: 12-column, 16-column, etc.
        let columns = 12;
        if (width < 768) {
            columns = 4;
        } else if (width < 1024) {
            columns = 8;
        }
        
        return {
            columns: columns,
            columnWidth: width / columns,
            gutter: 20,
            type: width < 768 ? 'mobile' : width < 1024 ? 'tablet' : 'desktop'
        };
    }
    
    /**
     * Detect responsive design patterns
     * @private
     * @param {Object} metadata - Image metadata
     * @returns {Promise<Object>} Responsive analysis
     */
    async detectResponsivePatterns(metadata) {
        const { width, height } = metadata;
        
        // Breakpoint detection
        let breakpoint = 'desktop';
        if (width < 480) {
            breakpoint = 'mobile-small';
        } else if (width < 768) {
            breakpoint = 'mobile';
        } else if (width < 1024) {
            breakpoint = 'tablet';
        } else if (width < 1440) {
            breakpoint = 'desktop';
        } else {
            breakpoint = 'desktop-large';
        }
        
        return {
            breakpoint: breakpoint,
            isMobile: width < 768,
            isTablet: width >= 768 && width < 1024,
            isDesktop: width >= 1024,
            deviceType: width < 768 ? 'mobile' : width < 1024 ? 'tablet' : 'desktop',
            recommendedActions: this.getResponsiveRecommendations(breakpoint)
        };
    }
    
    /**
     * Get responsive-specific recommendations
     * @private
     * @param {string} breakpoint - Current breakpoint
     * @returns {Array} Recommendations
     */
    getResponsiveRecommendations(breakpoint) {
        const recommendations = {
            'mobile-small': ['Use larger tap targets', 'Simplify navigation', 'Stack content vertically'],
            'mobile': ['Optimize for touch', 'Use hamburger menu', 'Single column layout'],
            'tablet': ['Consider two-column layout', 'Balance content density', 'Support both touch and mouse'],
            'desktop': ['Utilize horizontal space', 'Multi-column layouts', 'Rich interactions'],
            'desktop-large': ['Wide content areas', 'Consider max-width', 'Advanced layouts']
        };
        
        return recommendations[breakpoint] || [];
    }
    
    /**
     * Generate cache key for analysis
     * @private
     * @param {Buffer|string} imageData - Image data
     * @param {Object} metadata - Image metadata
     * @returns {string} Cache key
     */
    generateCacheKey(imageData, metadata) {
        // Simple cache key based on dimensions and scroll position
        return `${metadata.width}x${metadata.height}-${metadata.scrollY || 0}`;
    }
    
    /**
     * Get segmentation statistics
     * @returns {Object} Statistics
     */
    getStats() {
        return {
            ...this.stats,
            cacheSize: this.analysisCache.size,
            cacheHitRate: this.stats.totalAnalyses > 0 
                ? (this.stats.cacheHits / this.stats.totalAnalyses * 100).toFixed(2) + '%'
                : '0%'
        };
    }
    
    /**
     * Clear analysis cache
     */
    clearCache() {
        const size = this.analysisCache.size;
        this.analysisCache.clear();
        console.log(`[ScreenshotSegmenter] Cleared ${size} cached analyses`);
    }
}

module.exports = { 
    ScreenshotSegmenter, 
    RegionType, 
    FunctionalAreaType 
};