@vizzly-testing/cli 0.15.0 → 0.16.0

package/dist/cli.js

@@ -50,7 +50,9 @@ try {
       let registerPromise = plugin.register(program, {
         config,
         services,
-        output
+        output,
+        // Backwards compatibility alias for plugins using old API
+        logger: output
       });
       let timeoutPromise = new Promise((_, reject) => setTimeout(() => reject(new Error('Plugin registration timeout (5s)')), 5000));
       await Promise.race([registerPromise, timeoutPromise]);

package/dist/services/api-service.js

@@ -357,4 +357,46 @@ export class ApiService {
       }
     });
   }
+
+  /**
+   * Get hotspot analysis for a single screenshot
+   * @param {string} screenshotName - Screenshot name to get hotspots for
+   * @param {Object} options - Optional settings
+   * @param {number} [options.windowSize=20] - Number of historical builds to analyze
+   * @returns {Promise<Object>} Hotspot analysis data
+   */
+  async getScreenshotHotspots(screenshotName, options = {}) {
+    let {
+      windowSize = 20
+    } = options;
+    let queryParams = new URLSearchParams({
+      windowSize: String(windowSize)
+    });
+    let encodedName = encodeURIComponent(screenshotName);
+    return this.request(`/api/sdk/screenshots/${encodedName}/hotspots?${queryParams}`);
+  }
+
+  /**
+   * Batch get hotspot analysis for multiple screenshots
+   * More efficient than calling getScreenshotHotspots for each screenshot
+   * @param {string[]} screenshotNames - Array of screenshot names
+   * @param {Object} options - Optional settings
+   * @param {number} [options.windowSize=20] - Number of historical builds to analyze
+   * @returns {Promise<Object>} Hotspots keyed by screenshot name
+   */
+  async getBatchHotspots(screenshotNames, options = {}) {
+    let {
+      windowSize = 20
+    } = options;
+    return this.request('/api/sdk/screenshots/hotspots', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json'
+      },
+      body: JSON.stringify({
+        screenshot_names: screenshotNames,
+        windowSize
+      })
+    });
+  }
 }

package/dist/services/tdd-service.js

@@ -420,6 +420,9 @@ export class TddService {
       const metadataPath = join(this.baselinePath, 'metadata.json');
       writeFileSync(metadataPath, JSON.stringify(this.baselineData, null, 2));
 
+      // Download hotspot data for noise filtering
+      await this.downloadHotspots(buildDetails.screenshots);
+
       // Save baseline build metadata for MCP plugin
       const baselineMetadataPath = safePath(this.workingDir, '.vizzly', 'baseline-metadata.json');
       const buildMetadata = {
@@ -459,6 +462,152 @@ export class TddService {
     }
   }
 
+  /**
+   * Download hotspot data for screenshots from the cloud
+   * Hotspots identify regions that frequently change (timestamps, IDs, etc.)
+   * Used to filter out known dynamic content during comparisons
+   * @param {Array} screenshots - Array of screenshot objects with name property
+   */
+  async downloadHotspots(screenshots) {
+    // Only attempt if we have an API token
+    if (!this.config.apiKey) {
+      output.debug('tdd', 'Skipping hotspot download - no API token configured');
+      return;
+    }
+    try {
+      // Get unique screenshot names
+      let screenshotNames = [...new Set(screenshots.map(s => s.name))];
+      if (screenshotNames.length === 0) {
+        return;
+      }
+      output.info(`🔥 Fetching hotspot data for ${screenshotNames.length} screenshots...`);
+
+      // Use batch endpoint for efficiency
+      let response = await this.api.getBatchHotspots(screenshotNames);
+      if (!response.hotspots || Object.keys(response.hotspots).length === 0) {
+        output.debug('tdd', 'No hotspot data available from cloud');
+        return;
+      }
+
+      // Store hotspots in a separate file for easy access during comparisons
+      this.hotspotData = response.hotspots;
+      let hotspotsPath = safePath(this.workingDir, '.vizzly', 'hotspots.json');
+      writeFileSync(hotspotsPath, JSON.stringify({
+        downloadedAt: new Date().toISOString(),
+        summary: response.summary,
+        hotspots: response.hotspots
+      }, null, 2));
+      let hotspotCount = Object.keys(response.hotspots).length;
+      let totalRegions = Object.values(response.hotspots).reduce((sum, h) => sum + (h.regions?.length || 0), 0);
+      output.info(`✅ Downloaded hotspot data for ${hotspotCount} screenshots (${totalRegions} regions total)`);
+    } catch (error) {
+      // Don't fail baseline download if hotspot fetch fails
+      output.debug('tdd', `Hotspot download failed: ${error.message}`);
+      output.warn('⚠️  Could not fetch hotspot data - comparisons will run without noise filtering');
+    }
+  }
+
+  /**
+   * Load hotspot data from disk
+   * @returns {Object|null} Hotspot data keyed by screenshot name, or null if not available
+   */
+  loadHotspots() {
+    try {
+      let hotspotsPath = safePath(this.workingDir, '.vizzly', 'hotspots.json');
+      if (!existsSync(hotspotsPath)) {
+        return null;
+      }
+      let data = JSON.parse(readFileSync(hotspotsPath, 'utf8'));
+      return data.hotspots || null;
+    } catch (error) {
+      output.debug('tdd', `Failed to load hotspots: ${error.message}`);
+      return null;
+    }
+  }
+
+  /**
+   * Get hotspot analysis for a specific screenshot
+   * @param {string} screenshotName - Name of the screenshot
+   * @returns {Object|null} Hotspot analysis or null if not available
+   */
+  getHotspotForScreenshot(screenshotName) {
+    // Check memory cache first
+    if (this.hotspotData && this.hotspotData[screenshotName]) {
+      return this.hotspotData[screenshotName];
+    }
+
+    // Try loading from disk
+    if (!this.hotspotData) {
+      this.hotspotData = this.loadHotspots();
+    }
+    return this.hotspotData?.[screenshotName] || null;
+  }
+
+  /**
+   * Calculate what percentage of diff falls within hotspot regions
+   * Uses 1D Y-coordinate matching (same algorithm as cloud)
+   * @param {Array} diffClusters - Array of diff clusters from honeydiff
+   * @param {Object} hotspotAnalysis - Hotspot data with regions array
+   * @returns {Object} Coverage info { coverage, linesInHotspots, totalLines }
+   */
+  calculateHotspotCoverage(diffClusters, hotspotAnalysis) {
+    if (!diffClusters || diffClusters.length === 0) {
+      return {
+        coverage: 0,
+        linesInHotspots: 0,
+        totalLines: 0
+      };
+    }
+    if (!hotspotAnalysis || !hotspotAnalysis.regions || hotspotAnalysis.regions.length === 0) {
+      return {
+        coverage: 0,
+        linesInHotspots: 0,
+        totalLines: 0
+      };
+    }
+
+    // Extract Y-coordinates (diff lines) from clusters
+    // Each cluster has a boundingBox with y and height
+    let diffLines = [];
+    for (let cluster of diffClusters) {
+      if (cluster.boundingBox) {
+        let {
+          y,
+          height
+        } = cluster.boundingBox;
+        // Add all Y lines covered by this cluster
+        for (let line = y; line < y + height; line++) {
+          diffLines.push(line);
+        }
+      }
+    }
+    if (diffLines.length === 0) {
+      return {
+        coverage: 0,
+        linesInHotspots: 0,
+        totalLines: 0
+      };
+    }
+
+    // Remove duplicates and sort
+    diffLines = [...new Set(diffLines)].sort((a, b) => a - b);
+
+    // Check how many diff lines fall within hotspot regions
+    let linesInHotspots = 0;
+    for (let line of diffLines) {
+      let inHotspot = hotspotAnalysis.regions.some(region => line >= region.y1 && line <= region.y2);
+      if (inHotspot) {
+        linesInHotspots++;
+      }
+    }
+    let coverage = linesInHotspots / diffLines.length;
+    return {
+      coverage,
+      linesInHotspots,
+      totalLines: diffLines.length
+    };
+  }
+
   /**
    * Download baselines using OAuth authentication
    * Used when user is logged in via device flow but no API token is configured
@@ -784,17 +933,36 @@ export class TddService {
         this.comparisons.push(comparison);
         return comparison;
       } else {
-        // Images differ
+        // Images differ - check if differences are in known hotspot regions
+        let hotspotAnalysis = this.getHotspotForScreenshot(name);
+        let hotspotCoverage = null;
+        let isHotspotFiltered = false;
+        if (hotspotAnalysis && result.diffClusters && result.diffClusters.length > 0) {
+          hotspotCoverage = this.calculateHotspotCoverage(result.diffClusters, hotspotAnalysis);
+
+          // Consider it filtered if:
+          // 1. High confidence hotspot data (score >= 70)
+          // 2. 80%+ of the diff is within hotspot regions
+          let isHighConfidence = hotspotAnalysis.confidence === 'high' || hotspotAnalysis.confidence_score && hotspotAnalysis.confidence_score >= 70;
+          if (isHighConfidence && hotspotCoverage.coverage >= 0.8) {
+            isHotspotFiltered = true;
+          }
+        }
         let diffInfo = ` (${result.diffPercentage.toFixed(2)}% different, ${result.diffPixels} pixels)`;
 
         // Add cluster info to log if available
         if (result.diffClusters && result.diffClusters.length > 0) {
           diffInfo += `, ${result.diffClusters.length} region${result.diffClusters.length > 1 ? 's' : ''}`;
         }
+
+        // Add hotspot info if applicable
+        if (hotspotCoverage && hotspotCoverage.coverage > 0) {
+          diffInfo += `, ${Math.round(hotspotCoverage.coverage * 100)}% in hotspots`;
+        }
         const comparison = {
           id: generateComparisonId(signature),
           name: sanitizedName,
-          status: 'failed',
+          status: isHotspotFiltered ? 'passed' : 'failed',
           baseline: baselineImagePath,
           current: currentImagePath,
           diff: diffImagePath,
@@ -803,7 +971,7 @@ export class TddService {
           threshold: this.threshold,
           diffPercentage: result.diffPercentage,
           diffCount: result.diffPixels,
-          reason: 'pixel-diff',
+          reason: isHotspotFiltered ? 'hotspot-filtered' : 'pixel-diff',
           // Honeydiff metrics
           totalPixels: result.totalPixels,
           aaPixelsIgnored: result.aaPixelsIgnored,
@@ -811,10 +979,25 @@ export class TddService {
           boundingBox: result.boundingBox,
           heightDiff: result.heightDiff,
           intensityStats: result.intensityStats,
-          diffClusters: result.diffClusters
+          diffClusters: result.diffClusters,
+          // Hotspot analysis data
+          hotspotAnalysis: hotspotCoverage ? {
+            coverage: hotspotCoverage.coverage,
+            linesInHotspots: hotspotCoverage.linesInHotspots,
+            totalLines: hotspotCoverage.totalLines,
+            confidence: hotspotAnalysis?.confidence,
+            confidenceScore: hotspotAnalysis?.confidence_score,
+            regionCount: hotspotAnalysis?.regions?.length || 0,
+            isFiltered: isHotspotFiltered
+          } : null
         };
-        output.warn(`❌ ${colors.red('FAILED')} ${sanitizedName} - differences detected${diffInfo}`);
-        output.info(`    Diff saved to: ${diffImagePath}`);
+        if (isHotspotFiltered) {
+          output.info(`✅ ${colors.green('PASSED')} ${sanitizedName} - differences in known hotspots${diffInfo}`);
+          output.debug('tdd', `Hotspot filtered: ${Math.round(hotspotCoverage.coverage * 100)}% coverage, confidence: ${hotspotAnalysis.confidence}`);
+        } else {
+          output.warn(`❌ ${colors.red('FAILED')} ${sanitizedName} - differences detected${diffInfo}`);
+          output.info(`    Diff saved to: ${diffImagePath}`);
+        }
         this.comparisons.push(comparison);
         return comparison;
       }

package/dist/types/services/api-service.d.ts

@@ -97,4 +97,25 @@ export class ApiService {
      * @returns {Promise<Object>} Finalization result
      */
     finalizeParallelBuild(parallelId: string): Promise<any>;
+    /**
+     * Get hotspot analysis for a single screenshot
+     * @param {string} screenshotName - Screenshot name to get hotspots for
+     * @param {Object} options - Optional settings
+     * @param {number} [options.windowSize=20] - Number of historical builds to analyze
+     * @returns {Promise<Object>} Hotspot analysis data
+     */
+    getScreenshotHotspots(screenshotName: string, options?: {
+        windowSize?: number;
+    }): Promise<any>;
+    /**
+     * Batch get hotspot analysis for multiple screenshots
+     * More efficient than calling getScreenshotHotspots for each screenshot
+     * @param {string[]} screenshotNames - Array of screenshot names
+     * @param {Object} options - Optional settings
+     * @param {number} [options.windowSize=20] - Number of historical builds to analyze
+     * @returns {Promise<Object>} Hotspots keyed by screenshot name
+     */
+    getBatchHotspots(screenshotNames: string[], options?: {
+        windowSize?: number;
+    }): Promise<any>;
 }

package/dist/types/services/tdd-service.d.ts

@@ -16,6 +16,33 @@ export class TddService {
     comparisons: any[];
     threshold: any;
     downloadBaselines(environment?: string, branch?: any, buildId?: any, comparisonId?: any): Promise<any>;
+    /**
+     * Download hotspot data for screenshots from the cloud
+     * Hotspots identify regions that frequently change (timestamps, IDs, etc.)
+     * Used to filter out known dynamic content during comparisons
+     * @param {Array} screenshots - Array of screenshot objects with name property
+     */
+    downloadHotspots(screenshots: any[]): Promise<void>;
+    hotspotData: any;
+    /**
+     * Load hotspot data from disk
+     * @returns {Object|null} Hotspot data keyed by screenshot name, or null if not available
+     */
+    loadHotspots(): any | null;
+    /**
+     * Get hotspot analysis for a specific screenshot
+     * @param {string} screenshotName - Name of the screenshot
+     * @returns {Object|null} Hotspot analysis or null if not available
+     */
+    getHotspotForScreenshot(screenshotName: string): any | null;
+    /**
+     * Calculate what percentage of diff falls within hotspot regions
+     * Uses 1D Y-coordinate matching (same algorithm as cloud)
+     * @param {Array} diffClusters - Array of diff clusters from honeydiff
+     * @param {Object} hotspotAnalysis - Hotspot data with regions array
+     * @returns {Object} Coverage info { coverage, linesInHotspots, totalLines }
+     */
+    calculateHotspotCoverage(diffClusters: any[], hotspotAnalysis: any): any;
     /**
      * Download baselines using OAuth authentication
      * Used when user is logged in via device flow but no API token is configured

package/docs/plugins.md

@@ -356,7 +356,7 @@ register(program, { output }) {
 export default {
   name: 'hello',
   version: '1.0.0',
-  register(program, { logger }) {
+  register(program, { output }) {
     program
       .command('hello <name>')
       .description('Say hello')
@@ -366,7 +366,7 @@ export default {
         if (options.loud) {
           greeting = greeting.toUpperCase();
         }
-        logger.info(greeting);
+        output.info(greeting);
       });
   }
 };
@@ -378,13 +378,13 @@ export default {
 export default {
   name: 'storybook',
   version: '1.0.0',
-  register(program, { config, logger, services }) {
+  register(program, { config, output, services }) {
     program
       .command('storybook <path>')
       .description('Capture screenshots from Storybook build')
       .option('--viewports <list>', 'Comma-separated viewports', '1280x720')
       .action(async (path, options) => {
-        logger.info(`Crawling Storybook at ${path}`);
+        output.info(`Crawling Storybook at ${path}`);
 
         // Import dependencies lazily
         let { crawlStorybook } = await import('./crawler.js');
@@ -392,16 +392,15 @@ export default {
         // Capture screenshots
         let screenshots = await crawlStorybook(path, {
           viewports: options.viewports.split(','),
-          logger,
         });
 
-        logger.info(`Captured ${screenshots.length} screenshots`);
+        output.info(`Captured ${screenshots.length} screenshots`);
 
         // Upload using Vizzly's uploader service
         let uploader = await services.get('uploader');
         await uploader.uploadScreenshots(screenshots);
 
-        logger.info('Upload complete!');
+        output.success('Upload complete!');
       });
   }
 };
@@ -413,7 +412,7 @@ export default {
 export default {
   name: 'reports',
   version: '1.0.0',
-  register(program, { logger }) {
+  register(program, { output }) {
     let reports = program
       .command('reports')
       .description('Report generation commands');
@@ -422,14 +421,14 @@ export default {
       .command('generate')
       .description('Generate a new report')
       .action(() => {
-        logger.info('Generating report...');
+        output.info('Generating report...');
       });
 
     reports
       .command('list')
       .description('List all reports')
       .action(() => {
-        logger.info('Listing reports...');
+        output.info('Listing reports...');
       });
   }
 };
@@ -474,10 +473,10 @@ If you're using TypeScript or want better IDE support, you can add JSDoc types:
  * @param {import('commander').Command} program
  * @param {Object} context
  * @param {Object} context.config
- * @param {Object} context.logger
+ * @param {Object} context.output
  * @param {Object} context.services
  */
-function register(program, { config, logger, services }) {
+function register(program, { config, output, services }) {
   // Your plugin code with full autocomplete!
 }
 

package/docs/tdd-mode.md

@@ -311,6 +311,40 @@ npx vizzly tdd run "npm test"
 npx vizzly run "npm test" --build-name "Fix: Header alignment issue"
 ```
 
+## Hotspot Filtering
+
+When connected to Vizzly cloud, TDD mode automatically filters out "noise" from known hotspot areas - regions that frequently change across builds (like timestamps, animations, or dynamic content).
+
+### How It Works
+
+1. **Download baselines** - Use the TDD dashboard's Builds page to download baselines from the cloud (hotspot data is included automatically)
+2. **Automatic filtering** - During comparisons, if a diff falls within a known hotspot region, it's automatically marked as passed
+3. **Visual feedback** - You'll see output like:
+   ```
+   ✅ PASSED Dashboard - differences in known hotspots (0.15% different, 42 pixels, 1 region, 95% in hotspots)
+   ```
+
+### Requirements
+
+Hotspot filtering activates automatically when:
+- You have an API token configured (`vizzly login` or `VIZZLY_TOKEN`)
+- You've downloaded baselines from the cloud (via the TDD dashboard's Builds page)
+- The cloud has enough historical build data to calculate hotspot regions
+
+### Filtering Criteria
+
+A diff is filtered (auto-passed) when:
+- **80%+ of the diff** falls within known hotspot regions
+- **High confidence** hotspot data (confidence score ≥ 70)
+
+If the diff falls outside hotspots or confidence is low, the comparison fails normally so you can review it.
+
+### Benefits
+
+- **Reduced noise** - Stop seeing the same timestamp/animation diffs over and over
+- **Faster reviews** - Focus on real visual changes, not known dynamic areas
+- **Smart detection** - Hotspots are calculated from your actual build history, not manual configuration
+
 ## Comparison Settings
 
 TDD Mode uses the same comparison settings as production:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vizzly-testing/cli",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Visual review platform for UI developers and designers",
   "keywords": [
     "visual-testing",