@vizzly-testing/cli 0.23.2 → 0.24.0

package/dist/server/handlers/tdd-handler.js

@@ -386,21 +386,16 @@ export const createTddHandler = (config, workingDir, baselineBuild, baselineComp
     const vizzlyDir = join(workingDir, '.vizzly');
 
     // Record the comparison for the dashboard
+    // Spread the full comparison to include regionAnalysis, confirmedRegions, hotspotAnalysis, etc.
     const newComparison = {
-      id: comparison.id,
-      // Include unique ID for variant identification
-      name: comparison.name,
+      ...comparison,
       originalName: name,
-      status: comparison.status,
+      // Convert absolute file paths to web-accessible URLs
       baseline: convertPathToUrl(comparison.baseline, vizzlyDir),
       current: convertPathToUrl(comparison.current, vizzlyDir),
       diff: convertPathToUrl(comparison.diff, vizzlyDir),
-      diffPercentage: comparison.diffPercentage,
-      threshold: comparison.threshold,
-      properties: extractedProperties,
       // Use extracted properties with top-level viewport_width/browser
-      signature: comparison.signature,
-      // Include signature for debugging
+      properties: extractedProperties,
       timestamp: Date.now()
     };
 

package/dist/tdd/core/region-coverage.js

@@ -0,0 +1,115 @@
+/**
+ * Region Coverage Calculation
+ *
+ * Pure functions for calculating how much of a visual diff falls within
+ * user-defined "region" areas - 2D bounding boxes that users have confirmed
+ * as dynamic content areas (e.g., timestamps, animations, user avatars).
+ *
+ * Unlike hotspots (1D Y-bands from historical analysis), regions are explicit
+ * 2D boxes that users have manually confirmed via the cloud UI.
+ */
+
+/**
+ * Check if a diff cluster intersects with a region (2D box intersection)
+ *
+ * @param {Object} cluster - Diff cluster with boundingBox { x, y, width, height }
+ * @param {Object} region - Region with { x1, y1, x2, y2 }
+ * @returns {boolean} True if the cluster overlaps the region
+ */
+export function clusterIntersectsRegion(cluster, region) {
+  if (!cluster?.boundingBox || !region) {
+    return false;
+  }
+  let {
+    x,
+    y,
+    width,
+    height
+  } = cluster.boundingBox;
+
+  // Convert cluster to x1,y1,x2,y2 format
+  let clusterX1 = x;
+  let clusterY1 = y;
+  let clusterX2 = x + width;
+  let clusterY2 = y + height;
+
+  // Box intersection: NOT (one is completely outside the other)
+  // A is left of B: clusterX2 < region.x1
+  // A is right of B: clusterX1 > region.x2
+  // A is above B: clusterY2 < region.y1
+  // A is below B: clusterY1 > region.y2
+  let noOverlap = clusterX2 < region.x1 || clusterX1 > region.x2 || clusterY2 < region.y1 || clusterY1 > region.y2;
+  return !noOverlap;
+}
+
+/**
+ * Calculate what percentage of diff clusters fall within region boxes
+ *
+ * @param {Array} diffClusters - Array of diff clusters from honeydiff
+ * @param {Array} regions - Array of confirmed regions { x1, y1, x2, y2 }
+ * @returns {{ coverage: number, clustersInRegions: number, totalClusters: number, matchedRegions: string[] }}
+ */
+export function calculateRegionCoverage(diffClusters, regions) {
+  if (!diffClusters || diffClusters.length === 0) {
+    return {
+      coverage: 0,
+      clustersInRegions: 0,
+      totalClusters: 0,
+      matchedRegions: []
+    };
+  }
+  if (!regions || regions.length === 0) {
+    return {
+      coverage: 0,
+      clustersInRegions: 0,
+      totalClusters: diffClusters.length,
+      matchedRegions: []
+    };
+  }
+  let clustersInRegions = 0;
+  let matchedRegionIds = new Set();
+  for (let cluster of diffClusters) {
+    // Check if this cluster intersects any region
+    let intersectsAnyRegion = false;
+    for (let region of regions) {
+      if (clusterIntersectsRegion(cluster, region)) {
+        intersectsAnyRegion = true;
+        // Track which regions were matched (for debugging/display)
+        if (region.id) {
+          matchedRegionIds.add(region.id);
+        } else if (region.label) {
+          matchedRegionIds.add(region.label);
+        }
+      }
+    }
+    if (intersectsAnyRegion) {
+      clustersInRegions++;
+    }
+  }
+  let coverage = clustersInRegions / diffClusters.length;
+  return {
+    coverage,
+    clustersInRegions,
+    totalClusters: diffClusters.length,
+    matchedRegions: [...matchedRegionIds]
+  };
+}
+
+/**
+ * Determine if a comparison should auto-pass based on region coverage
+ *
+ * Unlike hotspots which require confidence scoring, user-defined regions
+ * are already confirmed by humans, so we only need the 80% threshold.
+ *
+ * @param {Array} regions - Confirmed regions (already filtered to confirmed status)
+ * @param {{ coverage: number }} coverageResult - Result from calculateRegionCoverage
+ * @returns {boolean} True if diff should auto-pass as region-filtered
+ */
+export function shouldAutoApproveFromRegions(regions, coverageResult) {
+  if (!regions || regions.length === 0 || !coverageResult) {
+    return false;
+  }
+
+  // Need at least 80% of diff clusters in confirmed regions
+  return coverageResult.coverage >= 0.8;
+}

package/dist/tdd/core/signature.js

@@ -52,7 +52,9 @@ export function generateScreenshotSignature(name, properties = {}, customPropert
         value = properties.viewport?.width;
       }
     } else if (propName === 'browser') {
-      value = properties.browser;
+      // Normalize browser to lowercase for consistent matching
+      // (Playwright reports "firefox", but cloud may store "Firefox")
+      value = properties.browser?.toLowerCase?.() ?? properties.browser;
     } else {
       // Custom property - check multiple locations
       value = properties[propName] ?? properties.metadata?.[propName] ?? properties.metadata?.properties?.[propName];

package/dist/tdd/metadata/region-metadata.js

@@ -0,0 +1,93 @@
+/**
+ * Region Metadata I/O
+ *
+ * Functions for reading and writing user-defined hotspot region data.
+ * Regions are 2D bounding boxes that users have confirmed as dynamic content areas.
+ * Unlike historical hotspots (1D Y-bands), these are explicit definitions.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * Load region data from disk
+ *
+ * @param {string} workingDir - Working directory containing .vizzly folder
+ * @returns {Object|null} Region data keyed by screenshot name, or null if not found
+ */
+export function loadRegionMetadata(workingDir) {
+  let regionsPath = join(workingDir, '.vizzly', 'regions.json');
+  if (!existsSync(regionsPath)) {
+    return null;
+  }
+  try {
+    let content = readFileSync(regionsPath, 'utf8');
+    let data = JSON.parse(content);
+    return data.regions || null;
+  } catch {
+    // Return null for parse/read errors
+    return null;
+  }
+}
+
+/**
+ * Save region data to disk
+ *
+ * @param {string} workingDir - Working directory containing .vizzly folder
+ * @param {Object} regionData - Region data keyed by screenshot name
+ * @param {Object} summary - Summary information about the regions
+ */
+export function saveRegionMetadata(workingDir, regionData, summary = {}) {
+  let vizzlyDir = join(workingDir, '.vizzly');
+
+  // Ensure directory exists
+  if (!existsSync(vizzlyDir)) {
+    mkdirSync(vizzlyDir, {
+      recursive: true
+    });
+  }
+  let regionsPath = join(vizzlyDir, 'regions.json');
+  let content = {
+    downloadedAt: new Date().toISOString(),
+    summary,
+    regions: regionData
+  };
+  writeFileSync(regionsPath, JSON.stringify(content, null, 2));
+}
+
+/**
+ * Get regions for a specific screenshot with caching support
+ *
+ * This is a pure function that takes a cache object as parameter
+ * for stateless operation. The cache is mutated if data needs to be loaded.
+ *
+ * @param {Object} cache - Cache object { data: Object|null, loaded: boolean }
+ * @param {string} workingDir - Working directory
+ * @param {string} screenshotName - Name of the screenshot
+ * @returns {Object|null} Region data or null if not available
+ */
+export function getRegionsForScreenshot(cache, workingDir, screenshotName) {
+  // Check cache first
+  if (cache.data?.[screenshotName]) {
+    return cache.data[screenshotName];
+  }
+
+  // Load from disk if not yet loaded
+  if (!cache.loaded) {
+    cache.data = loadRegionMetadata(workingDir);
+    cache.loaded = true;
+  }
+  return cache.data?.[screenshotName] || null;
+}
+
+/**
+ * Create an empty region cache object
+ *
+ * @returns {{ data: null, loaded: boolean }}
+ */
+export function createRegionCache() {
+  return {
+    data: null,
+    loaded: false
+  };
+}

package/dist/tdd/services/comparison-service.js

@@ -6,6 +6,7 @@
 
 import { compare } from '@vizzly-testing/honeydiff';
 import { calculateHotspotCoverage } from '../core/hotspot-coverage.js';
+import { calculateRegionCoverage, shouldAutoApproveFromRegions } from '../core/region-coverage.js';
 import { generateComparisonId } from '../core/signature.js';
 
 /**
@@ -122,6 +123,7 @@ export function buildNewComparison(params) {
  * @param {number} params.minClusterSize - Effective minClusterSize used
  * @param {Object} params.honeydiffResult - Result from honeydiff
  * @param {Object} params.hotspotAnalysis - Hotspot data for this screenshot (optional)
+ * @param {Object} params.regionData - User-defined region data { confirmed: [], candidates: [] } (optional)
  * @returns {Object} Comparison result
  */
 export function buildFailedComparison(params) {
@@ -135,27 +137,45 @@ export function buildFailedComparison(params) {
     threshold,
     minClusterSize,
     honeydiffResult,
-    hotspotAnalysis
+    hotspotAnalysis,
+    regionData
   } = params;
+  let diffClusters = honeydiffResult.diffClusters || [];
+  let isFiltered = false;
+  let filterReason = 'pixel-diff';
 
-  // Calculate hotspot coverage if we have hotspot data
+  // Region analysis (user-confirmed 2D boxes) - check FIRST (takes priority)
+  let regionCoverage = null;
+  let isRegionFiltered = false;
+  let confirmedRegions = regionData?.confirmed || [];
+  if (confirmedRegions.length > 0 && diffClusters.length > 0) {
+    regionCoverage = calculateRegionCoverage(diffClusters, confirmedRegions);
+    if (shouldAutoApproveFromRegions(confirmedRegions, regionCoverage)) {
+      isRegionFiltered = true;
+      isFiltered = true;
+      filterReason = 'region-filtered';
+    }
+  }
+
+  // Hotspot analysis (1D Y-bands from historical data) - check SECOND
   let hotspotCoverage = null;
   let isHotspotFiltered = false;
-  if (hotspotAnalysis && honeydiffResult.diffClusters?.length > 0) {
-    hotspotCoverage = calculateHotspotCoverage(honeydiffResult.diffClusters, hotspotAnalysis);
+  if (!isFiltered && hotspotAnalysis && diffClusters.length > 0) {
+    hotspotCoverage = calculateHotspotCoverage(diffClusters, hotspotAnalysis);
 
     // Check if diff should be filtered as hotspot noise
-    // Using shouldFilterAsHotspot helper but also checking confidence_score
     // (cloud uses confidence_score >= 70 which is >0.7 when normalized)
     let isHighConfidence = hotspotAnalysis.confidence === 'high' || hotspotAnalysis.confidence_score !== undefined && hotspotAnalysis.confidence_score >= 70;
     if (isHighConfidence && hotspotCoverage.coverage >= 0.8) {
       isHotspotFiltered = true;
+      isFiltered = true;
+      filterReason = 'hotspot-filtered';
     }
   }
   return {
     id: generateComparisonId(signature),
     name,
-    status: isHotspotFiltered ? 'passed' : 'failed',
+    status: isFiltered ? 'passed' : 'failed',
     baseline: baselinePath,
     current: currentPath,
     diff: diffPath,
@@ -165,14 +185,26 @@ export function buildFailedComparison(params) {
     minClusterSize,
     diffPercentage: honeydiffResult.diffPercentage,
     diffCount: honeydiffResult.diffPixels,
-    reason: isHotspotFiltered ? 'hotspot-filtered' : 'pixel-diff',
+    reason: filterReason,
     totalPixels: honeydiffResult.totalPixels,
     aaPixelsIgnored: honeydiffResult.aaPixelsIgnored,
     aaPercentage: honeydiffResult.aaPercentage,
     boundingBox: honeydiffResult.boundingBox,
     heightDiff: honeydiffResult.heightDiff,
     intensityStats: honeydiffResult.intensityStats,
-    diffClusters: honeydiffResult.diffClusters,
+    diffClusters,
+    // User-defined region analysis (2D boxes)
+    regionAnalysis: regionCoverage ? {
+      coverage: regionCoverage.coverage,
+      clustersInRegions: regionCoverage.clustersInRegions,
+      totalClusters: regionCoverage.totalClusters,
+      matchedRegions: regionCoverage.matchedRegions,
+      confirmedCount: confirmedRegions.length,
+      isFiltered: isRegionFiltered
+    } : null,
+    // Include confirmed regions for visualization in UI
+    confirmedRegions: confirmedRegions.length > 0 ? confirmedRegions : null,
+    // Historical hotspot analysis (1D Y-bands)
     hotspotAnalysis: hotspotCoverage ? {
       coverage: hotspotCoverage.coverage,
       linesInHotspots: hotspotCoverage.linesInHotspots,

package/dist/tdd/services/region-service.js

@@ -0,0 +1,75 @@
+/**
+ * Region Service
+ *
+ * Functions for downloading and managing user-defined hotspot regions from the cloud.
+ * Regions are 2D bounding boxes that users have confirmed as dynamic content areas.
+ */
+
+import { saveRegionMetadata } from '../metadata/region-metadata.js';
+
+/**
+ * Download user-defined regions from cloud API
+ *
+ * @param {Object} options
+ * @param {Object} options.api - ApiService instance
+ * @param {string} options.workingDir - Working directory
+ * @param {string[]} options.screenshotNames - Names of screenshots to get regions for
+ * @param {boolean} options.includeCandidates - Include candidate regions (default: false)
+ * @returns {Promise<{ success: boolean, count: number, regionCount: number, error?: string }>}
+ */
+export async function downloadRegions(options) {
+  let {
+    api,
+    workingDir,
+    screenshotNames,
+    includeCandidates = false
+  } = options;
+  if (!screenshotNames || screenshotNames.length === 0) {
+    return {
+      success: true,
+      count: 0,
+      regionCount: 0
+    };
+  }
+  try {
+    let response = await api.getRegions(screenshotNames, {
+      includeCandidates
+    });
+    if (!response || !response.regions) {
+      return {
+        success: false,
+        error: 'API returned no region data'
+      };
+    }
+
+    // Save regions to disk
+    saveRegionMetadata(workingDir, response.regions, response.summary);
+
+    // Calculate stats
+    let count = Object.keys(response.regions).length;
+    let regionCount = response.summary?.total_regions || 0;
+    return {
+      success: true,
+      count,
+      regionCount
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: error.message
+    };
+  }
+}
+
+/**
+ * Extract screenshot names from a list of screenshots
+ *
+ * @param {Array} screenshots - Screenshots with name property
+ * @returns {string[]}
+ */
+export function extractScreenshotNames(screenshots) {
+  if (!screenshots || !Array.isArray(screenshots)) {
+    return [];
+  }
+  return screenshots.map(s => s.name).filter(Boolean);
+}

package/dist/tdd/tdd-service.js

@@ -21,6 +21,7 @@ import { calculateHotspotCoverage as defaultCalculateHotspotCoverage } from './c
 import { generateBaselineFilename as defaultGenerateBaselineFilename, generateComparisonId as defaultGenerateComparisonId, generateScreenshotSignature as defaultGenerateScreenshotSignature } from './core/signature.js';
 import { createEmptyBaselineMetadata as defaultCreateEmptyBaselineMetadata, loadBaselineMetadata as defaultLoadBaselineMetadata, saveBaselineMetadata as defaultSaveBaselineMetadata, upsertScreenshotInMetadata as defaultUpsertScreenshotInMetadata } from './metadata/baseline-metadata.js';
 import { loadHotspotMetadata as defaultLoadHotspotMetadata, saveHotspotMetadata as defaultSaveHotspotMetadata } from './metadata/hotspot-metadata.js';
+import { loadRegionMetadata as defaultLoadRegionMetadata, saveRegionMetadata as defaultSaveRegionMetadata } from './metadata/region-metadata.js';
 import { baselineExists as defaultBaselineExists, clearBaselineData as defaultClearBaselineData, getBaselinePath as defaultGetBaselinePath, getCurrentPath as defaultGetCurrentPath, getDiffPath as defaultGetDiffPath, initializeDirectories as defaultInitializeDirectories, saveBaseline as defaultSaveBaseline, saveCurrent as defaultSaveCurrent } from './services/baseline-manager.js';
 import { buildErrorComparison as defaultBuildErrorComparison, buildFailedComparison as defaultBuildFailedComparison, buildNewComparison as defaultBuildNewComparison, buildPassedComparison as defaultBuildPassedComparison, compareImages as defaultCompareImages, isDimensionMismatchError as defaultIsDimensionMismatchError } from './services/comparison-service.js';
 import { buildResults as defaultBuildResults, getFailedComparisons as defaultGetFailedComparisons, getNewComparisons as defaultGetNewComparisons } from './services/result-service.js';
@@ -89,6 +90,8 @@ export class TddService {
       upsertScreenshotInMetadata: defaultUpsertScreenshotInMetadata,
       loadHotspotMetadata: defaultLoadHotspotMetadata,
       saveHotspotMetadata: defaultSaveHotspotMetadata,
+      loadRegionMetadata: defaultLoadRegionMetadata,
+      saveRegionMetadata: defaultSaveRegionMetadata,
       ...metadata
     };
     let baselineOps = {
@@ -175,6 +178,9 @@ export class TddService {
     // Hotspot data (loaded lazily from disk or downloaded from cloud)
     this.hotspotData = null;
 
+    // Region data (user-defined 2D bounding boxes, loaded lazily)
+    this.regionData = null;
+
     // Track whether results have been printed (to avoid duplicate output)
     this._resultsPrinted = false;
     if (this.setBaseline) {
@@ -319,6 +325,16 @@ export class TddService {
         }
         baselineBuild = apiResponse.build;
         baselineBuild.screenshots = apiResponse.screenshots;
+
+        // Store bundled hotspots and regions from API response
+        if (apiResponse.hotspots && Object.keys(apiResponse.hotspots).length > 0) {
+          this.hotspotData = apiResponse.hotspots;
+          saveHotspotMetadata(this.workingDir, apiResponse.hotspots, apiResponse.summary);
+        }
+        if (apiResponse.regions && Object.keys(apiResponse.regions).length > 0) {
+          this.regionData = apiResponse.regions;
+          saveRegionMetadata(this.workingDir, apiResponse.regions, apiResponse.summary);
+        }
       }
       let buildDetails = baselineBuild;
       if (!buildDetails.screenshots || buildDetails.screenshots.length === 0) {
@@ -466,8 +482,8 @@ export class TddService {
       };
       saveBaselineMetadata(this.baselinePath, this.baselineData);
 
-      // Download hotspots
-      await this.downloadHotspots(buildDetails.screenshots);
+      // Hotspots and regions are now bundled in the tdd-baselines API response
+      // and saved earlier when processing the API response
 
       // Save baseline build metadata for MCP plugin
       let baselineMetadataPath = safePath(this.workingDir, '.vizzly', 'baseline-metadata.json');
@@ -541,6 +557,20 @@ export class TddService {
       }
     }
     let baselineBuild = apiResponse.build;
+
+    // Store bundled hotspots and regions from API response
+    let {
+      saveHotspotMetadata,
+      saveRegionMetadata
+    } = this._deps;
+    if (apiResponse.hotspots && Object.keys(apiResponse.hotspots).length > 0) {
+      this.hotspotData = apiResponse.hotspots;
+      saveHotspotMetadata(this.workingDir, apiResponse.hotspots, apiResponse.summary);
+    }
+    if (apiResponse.regions && Object.keys(apiResponse.regions).length > 0) {
+      this.regionData = apiResponse.regions;
+      saveRegionMetadata(this.workingDir, apiResponse.regions, apiResponse.summary);
+    }
     if (baselineBuild.status === 'failed') {
       output.warn(`Build ${buildId} is marked as FAILED - falling back to local baselines`);
       return await this.handleLocalBaselines();
@@ -694,11 +724,8 @@ export class TddService {
     };
     saveBaselineMetadata(this.baselinePath, this.baselineData);
 
-    // Download hotspots if API key is available (requires SDK auth)
-    // OAuth-only users won't get hotspots since the hotspot endpoint requires project token
-    if (this.config.apiKey && buildDetails.screenshots?.length > 0) {
-      await this.downloadHotspots(buildDetails.screenshots);
-    }
+    // Hotspots and regions are now bundled in the tdd-baselines API response
+    // and saved earlier when processing the API response
 
     // Save baseline build metadata for MCP plugin
     let baselineMetadataPath = safePath(this.workingDir, '.vizzly', 'baseline-metadata.json');
@@ -800,6 +827,39 @@ export class TddService {
     return this.hotspotData?.[screenshotName] || null;
   }
 
+  /**
+   * Load region data from disk
+   */
+  loadRegions() {
+    let {
+      loadRegionMetadata
+    } = this._deps;
+    return loadRegionMetadata(this.workingDir);
+  }
+
+  /**
+   * Get user-defined regions for a specific screenshot
+   *
+   * Note: Once regionData is loaded (from disk or cloud), we don't reload.
+   * This is intentional - regions are downloaded once per session and cached.
+   * If a screenshot isn't in the cache, it means no region data exists for it.
+   *
+   * @param {string} screenshotName - Name of the screenshot
+   * @returns {Object|null} Region data { confirmed: [], candidates: [] } or null
+   */
+  getRegionsForScreenshot(screenshotName) {
+    // Check memory cache first
+    if (this.regionData?.[screenshotName]) {
+      return this.regionData[screenshotName];
+    }
+
+    // Try loading from disk (only if we haven't loaded yet)
+    if (!this.regionData) {
+      this.regionData = this.loadRegions();
+    }
+    return this.regionData?.[screenshotName] || null;
+  }
+
   /**
    * Calculate hotspot coverage (delegating to pure function)
    */
@@ -1000,6 +1060,7 @@ export class TddService {
         return result;
       } else {
         let hotspotAnalysis = this.getHotspotForScreenshot(name);
+        let regionData = this.getRegionsForScreenshot(name);
         let result = buildFailedComparison({
           name: sanitizedName,
           signature,
@@ -1010,7 +1071,8 @@ export class TddService {
           threshold: effectiveThreshold,
           minClusterSize: effectiveMinClusterSize,
           honeydiffResult,
-          hotspotAnalysis
+          hotspotAnalysis,
+          regionData
         });
 
         // Log at debug level only (shown with --verbose)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vizzly-testing/cli",
-  "version": "0.23.2",
+  "version": "0.24.0",
   "description": "Visual review platform for UI developers and designers",
   "keywords": [
     "visual-testing",
@@ -86,7 +86,7 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@vizzly-testing/honeydiff": "^0.8.0",
+    "@vizzly-testing/honeydiff": "^0.9.0",
     "ansis": "^4.2.0",
     "commander": "^14.0.0",
     "cosmiconfig": "^9.0.0",
@@ -119,7 +119,7 @@
     "@tanstack/react-query": "^5.90.11",
     "@types/node": "^25.0.2",
     "@vitejs/plugin-react": "^5.0.3",
-    "@vizzly-testing/observatory": "^0.2.1",
+    "@vizzly-testing/observatory": "^0.3.3",
     "autoprefixer": "^10.4.21",
     "babel-plugin-transform-remove-console": "^6.9.4",
     "postcss": "^8.5.6",