@vizzly-testing/cli 0.31.0 → 0.32.0

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

@@ -9,6 +9,8 @@
  * 2D boxes that users have manually confirmed via the cloud UI.
  */
 
+let REGION_CENTER_TOLERANCE = 10;
+
 /**
  * Check if a diff cluster intersects with a region (2D box intersection)
  *
@@ -41,13 +43,77 @@ export function clusterIntersectsRegion(cluster, region) {
   let noOverlap = clusterX2 < region.x1 || clusterX1 > region.x2 || clusterY2 < region.y1 || clusterY1 > region.y2;
   return !noOverlap;
 }
+function normalizeBoundingBox(cluster) {
+  let box = cluster?.boundingBox || cluster;
+  if (!box) {
+    return null;
+  }
+  if (Number.isFinite(box.x) && Number.isFinite(box.y) && Number.isFinite(box.width) && Number.isFinite(box.height)) {
+    return {
+      x1: box.x,
+      y1: box.y,
+      x2: box.x + box.width,
+      y2: box.y + box.height,
+      width: Math.abs(box.width),
+      height: Math.abs(box.height)
+    };
+  }
+  if (Number.isFinite(box.x1) && Number.isFinite(box.y1) && Number.isFinite(box.x2) && Number.isFinite(box.y2)) {
+    let width = Math.abs(box.x2 - box.x1);
+    let height = Math.abs(box.y2 - box.y1);
+    return {
+      x1: box.x1,
+      y1: box.y1,
+      x2: box.x2,
+      y2: box.y2,
+      width,
+      height
+    };
+  }
+  return null;
+}
+function getBoundingBoxCenter(box) {
+  return {
+    x: (box.x1 + box.x2) / 2,
+    y: (box.y1 + box.y2) / 2
+  };
+}
+function getRegionLabel(region) {
+  return region.id || region.label || null;
+}
+function clusterMatchesRegion(cluster, region) {
+  let clusterBox = normalizeBoundingBox(cluster);
+  let regionBox = normalizeBoundingBox(region);
+  if (!clusterBox || !regionBox) {
+    return false;
+  }
+  let clusterCenter = getBoundingBoxCenter(clusterBox);
+  let regionCenter = getBoundingBoxCenter(regionBox);
+  let distance = Math.sqrt((clusterCenter.x - regionCenter.x) ** 2 + (clusterCenter.y - regionCenter.y) ** 2);
+  return distance <= REGION_CENTER_TOLERANCE;
+}
+function estimateClusterPixels(cluster) {
+  if (Number.isFinite(cluster?.pixelCount)) {
+    return cluster.pixelCount;
+  }
+  let box = normalizeBoundingBox(cluster);
+  if (!box) {
+    return 0;
+  }
+  return box.width * box.height * 0.5;
+}
 
 /**
- * Calculate what percentage of diff clusters fall within region boxes
+ * Calculate what percentage of changed pixels match confirmed regions.
+ *
+ * This mirrors cloud dynamic-region approval: clusters match confirmed regions
+ * by center proximity, then coverage is weighted by changed pixels. A huge
+ * unmatched change should not be hidden just because several tiny clusters
+ * match confirmed regions.
  *
  * @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[] }}
+ * @returns {{ coverage: number, clustersInRegions: number, totalClusters: number, matchedRegions: string[], pixelsInRegions: number, totalPixels: number }}
  */
 export function calculateRegionCoverage(diffClusters, regions) {
   if (!diffClusters || diffClusters.length === 0) {
@@ -55,7 +121,9 @@ export function calculateRegionCoverage(diffClusters, regions) {
       coverage: 0,
       clustersInRegions: 0,
       totalClusters: 0,
-      matchedRegions: []
+      matchedRegions: [],
+      pixelsInRegions: 0,
+      totalPixels: 0
     };
   }
   if (!regions || regions.length === 0) {
@@ -63,35 +131,41 @@ export function calculateRegionCoverage(diffClusters, regions) {
       coverage: 0,
       clustersInRegions: 0,
       totalClusters: diffClusters.length,
-      matchedRegions: []
+      matchedRegions: [],
+      pixelsInRegions: 0,
+      totalPixels: 0
     };
   }
   let clustersInRegions = 0;
   let matchedRegionIds = new Set();
+  let pixelsInRegions = 0;
+  let totalPixels = 0;
   for (let cluster of diffClusters) {
-    // Check if this cluster intersects any region
-    let intersectsAnyRegion = false;
+    let pixelCount = estimateClusterPixels(cluster);
+    totalPixels += pixelCount;
+    let matchedAnyRegion = 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 (clusterMatchesRegion(cluster, region)) {
+        matchedAnyRegion = true;
+        let regionLabel = getRegionLabel(region);
+        if (regionLabel) {
+          matchedRegionIds.add(regionLabel);
         }
       }
     }
-    if (intersectsAnyRegion) {
+    if (matchedAnyRegion) {
       clustersInRegions++;
+      pixelsInRegions += pixelCount;
     }
   }
-  let coverage = clustersInRegions / diffClusters.length;
+  let coverage = totalPixels > 0 ? pixelsInRegions / totalPixels : 0;
   return {
     coverage,
     clustersInRegions,
     totalClusters: diffClusters.length,
-    matchedRegions: [...matchedRegionIds]
+    matchedRegions: [...matchedRegionIds],
+    pixelsInRegions,
+    totalPixels
   };
 }
 
@@ -99,17 +173,31 @@ export function calculateRegionCoverage(diffClusters, regions) {
  * 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.
+ * are already confirmed by humans. Cloud still requires strong structural
+ * similarity so a layout shift cannot hide inside a confirmed box.
  *
  * @param {Array} regions - Confirmed regions (already filtered to confirmed status)
  * @param {{ coverage: number }} coverageResult - Result from calculateRegionCoverage
+ * @param {Object} options - Approval thresholds
+ * @param {number|null} options.ssimScore - Honeydiff SSIM/perceptual score
+ * @param {number} options.coverageThreshold - Required region coverage
+ * @param {number} options.ssimThreshold - Required structural similarity
  * @returns {boolean} True if diff should auto-pass as region-filtered
  */
-export function shouldAutoApproveFromRegions(regions, coverageResult) {
+export function shouldAutoApproveFromRegions(regions, coverageResult, options = {}) {
   if (!regions || regions.length === 0 || !coverageResult) {
     return false;
   }
-
-  // Need at least 80% of diff clusters in confirmed regions
-  return coverageResult.coverage >= 0.8;
+  let {
+    ssimScore = null,
+    coverageThreshold = 0.9,
+    ssimThreshold = 0.95
+  } = options;
+  if (coverageResult.coverage < coverageThreshold) {
+    return false;
+  }
+  if (ssimScore === null || ssimScore === undefined) {
+    return false;
+  }
+  return ssimScore >= ssimThreshold;
 }

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

@@ -32,6 +32,9 @@ export async function compareImages(baselinePath, currentPath, diffPath, options
     diffPath,
     overwrite: true,
     includeClusters: true,
+    includeSSIM: true,
+    includeGMSD: true,
+    clusterMerge: true,
     minClusterSize
   });
 }
@@ -141,6 +144,7 @@ export function buildFailedComparison(params) {
     regionData
   } = params;
   let diffClusters = honeydiffResult.diffClusters || [];
+  let ssimScore = honeydiffResult.perceptualScore ?? honeydiffResult.ssimScore ?? honeydiffResult.ssim_score ?? null;
   let isFiltered = false;
   let filterReason = 'pixel-diff';
 
@@ -150,7 +154,9 @@ export function buildFailedComparison(params) {
   let confirmedRegions = regionData?.confirmed || [];
   if (confirmedRegions.length > 0 && diffClusters.length > 0) {
     regionCoverage = calculateRegionCoverage(diffClusters, confirmedRegions);
-    if (shouldAutoApproveFromRegions(confirmedRegions, regionCoverage)) {
+    if (shouldAutoApproveFromRegions(confirmedRegions, regionCoverage, {
+      ssimScore
+    })) {
       isRegionFiltered = true;
       isFiltered = true;
       filterReason = 'region-filtered';
@@ -198,8 +204,11 @@ export function buildFailedComparison(params) {
       coverage: regionCoverage.coverage,
       clustersInRegions: regionCoverage.clustersInRegions,
       totalClusters: regionCoverage.totalClusters,
+      pixelsInRegions: regionCoverage.pixelsInRegions,
+      totalPixels: regionCoverage.totalPixels,
       matchedRegions: regionCoverage.matchedRegions,
       confirmedCount: confirmedRegions.length,
+      ssimScore,
       isFiltered: isRegionFiltered
     } : null,
     // Include confirmed regions for visualization in UI

package/dist/tdd/tdd-service.js

@@ -9,7 +9,7 @@
  */
 
 import { existsSync as defaultExistsSync, mkdirSync as defaultMkdirSync, readFileSync as defaultReadFileSync, writeFileSync as defaultWriteFileSync } from 'node:fs';
-import { createApiClient as defaultCreateApiClient, getBatchHotspots as defaultGetBatchHotspots, getBuilds as defaultGetBuilds, getComparison as defaultGetComparison, getTddBaselines as defaultGetTddBaselines } from '../api/index.js';
+import { createApiClient as defaultCreateApiClient, getBatchHotspots as defaultGetBatchHotspots, getBuilds as defaultGetBuilds, getComparison as defaultGetComparison, getComparisonContext as defaultGetComparisonContext, getTddBaselines as defaultGetTddBaselines } from '../api/index.js';
 import { NetworkError } from '../errors/vizzly-error.js';
 import { colors as defaultColors } from '../utils/colors.js';
 import { fetchWithTimeout as defaultFetchWithTimeout } from '../utils/fetch-utils.js';
@@ -58,6 +58,7 @@ export class TddService {
         getTddBaselines: defaultGetTddBaselines,
         getBuilds: defaultGetBuilds,
         getComparison: defaultGetComparison,
+        getComparisonContext: defaultGetComparisonContext,
         getBatchHotspots: defaultGetBatchHotspots,
         fetchWithTimeout: defaultFetchWithTimeout,
         getDefaultBranch: defaultGetDefaultBranch
@@ -169,6 +170,7 @@ export class TddService {
       getTddBaselines,
       getBuilds,
       getComparison,
+      getComparisonContext,
       clearBaselineData,
       generateScreenshotSignature,
       generateBaselineFilename,
@@ -221,10 +223,19 @@ export class TddService {
           output.warn(`Build ${buildId} has status: ${baselineBuild.status} (expected: completed)`);
         }
         baselineBuild.screenshots = apiResponse.screenshots;
+        this.saveDynamicMetadataFromBaselineResponse(apiResponse);
       } else if (comparisonId) {
         // Handle specific comparison download
         output.info(`Using comparison: ${comparisonId}`);
         let comparison = await getComparison(this.client, comparisonId);
+        let comparisonContext = null;
+        if (!comparison.dynamic_content && getComparisonContext) {
+          try {
+            comparisonContext = await getComparisonContext(this.client, comparisonId);
+          } catch (error) {
+            output.debug('tdd', `comparison context unavailable for ${comparisonId}: ${error.message}`);
+          }
+        }
         if (!comparison.baseline_screenshot) {
           throw new Error(`Comparison ${comparisonId} has no baseline screenshot. This comparison may be a "new" screenshot.`);
         }
@@ -255,6 +266,11 @@ export class TddService {
           }
         }
         let screenshotName = comparison.baseline_name || comparison.current_name;
+        let dynamicContent = comparison.dynamic_content || {
+          hotspot_analysis: comparisonContext?.history?.hotspot_analysis,
+          confirmed_regions: comparisonContext?.history?.confirmed_regions
+        };
+        this.saveDynamicMetadataForScreenshot(screenshotName, dynamicContent);
         let signature = generateScreenshotSignature(screenshotName, screenshotProperties, this.signatureProperties);
         let filename = generateBaselineFilename(screenshotName, signature);
         baselineBuild = {
@@ -294,16 +310,7 @@ 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);
-        }
+        this.saveDynamicMetadataFromBaselineResponse(apiResponse);
       }
       let buildDetails = baselineBuild;
       if (!buildDetails.screenshots || buildDetails.screenshots.length === 0) {
@@ -488,6 +495,49 @@ export class TddService {
       throw error;
     }
   }
+  saveDynamicMetadataFromBaselineResponse(apiResponse = {}) {
+    let {
+      saveHotspotMetadata,
+      saveRegionMetadata
+    } = this._deps;
+    let hasHotspots = Object.keys(apiResponse.hotspots || {}).length > 0;
+    let hasRegions = Object.keys(apiResponse.regions || {}).length > 0;
+    if (hasHotspots) {
+      this.hotspotData = apiResponse.hotspots;
+      saveHotspotMetadata(this.workingDir, apiResponse.hotspots, apiResponse.summary);
+    }
+    if (hasRegions) {
+      this.regionData = apiResponse.regions;
+      saveRegionMetadata(this.workingDir, apiResponse.regions, apiResponse.summary);
+    }
+  }
+  saveDynamicMetadataForScreenshot(screenshotName, dynamicContent = {}) {
+    if (!screenshotName) {
+      return;
+    }
+    let hotspotAnalysis = dynamicContent.hotspot_analysis;
+    let confirmedRegions = dynamicContent.confirmed_regions || [];
+    let hasHotspotAnalysis = hotspotAnalysis?.total_builds_analyzed > 0;
+    let hasConfirmedRegions = confirmedRegions.length > 0;
+    let summary = {
+      screenshots: 1,
+      hotspots: hasHotspotAnalysis ? 1 : 0,
+      regions: hasConfirmedRegions ? 1 : 0,
+      total_regions: confirmedRegions.length
+    };
+    this.saveDynamicMetadataFromBaselineResponse({
+      hotspots: hasHotspotAnalysis ? {
+        [screenshotName]: hotspotAnalysis
+      } : {},
+      regions: hasConfirmedRegions ? {
+        [screenshotName]: {
+          confirmed: confirmedRegions,
+          candidates: []
+        }
+      } : {},
+      summary
+    });
+  }
 
   /**
    * Process already-fetched baseline data (for use when caller handles auth)
@@ -526,20 +576,7 @@ 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);
-    }
+    this.saveDynamicMetadataFromBaselineResponse(apiResponse);
     if (baselineBuild.status === 'failed') {
       output.warn(`Build ${buildId} is marked as FAILED - falling back to local baselines`);
       return await this.handleLocalBaselines();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vizzly-testing/cli",
-  "version": "0.31.0",
+  "version": "0.32.0",
   "description": "Visual review for agents and teams",
   "keywords": [
     "llm-context",
@@ -90,13 +90,15 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@vizzly-testing/honeydiff": "^0.10.0",
+    "@vizzly-testing/honeydiff": "^0.10.3",
     "ansis": "^4.2.0",
     "commander": "^14.0.0",
     "cosmiconfig": "^9.0.0",
     "dotenv": "^17.2.1",
     "form-data": "^4.0.0",
     "glob": "^13.0.0",
+    "react": "^19.1.1",
+    "react-dom": "^19.1.1",
     "zod": "^4.1.12"
   },
   "tsd": {
@@ -128,8 +130,6 @@
     "babel-plugin-react-compiler": "^1.0.0",
     "babel-plugin-transform-remove-console": "^6.9.4",
     "postcss": "^8.5.6",
-    "react": "^19.1.1",
-    "react-dom": "^19.1.1",
     "rimraf": "^6.0.1",
     "tailwindcss": "^4.1.13",
     "tsd": "^0.33.0",