@fragments-sdk/cli 0.2.2

package/src/service/diff.ts

@@ -0,0 +1,279 @@
+import pixelmatch from 'pixelmatch';
+import { PNG } from 'pngjs';
+import {
+  BRAND,
+  DEFAULTS,
+  type Screenshot,
+  type DiffResult,
+  type BoundingBox,
+} from '../core/index.js';
+import { ServiceError, Timer } from './utils.js';
+
+/**
+ * Options for diff comparison
+ */
+export interface DiffOptions {
+  /** Percentage threshold for matching (0-100). Default: 5 */
+  threshold?: number;
+
+  /** Color difference sensitivity (0-1). Lower = more sensitive. Default: 0.1 */
+  colorThreshold?: number;
+
+  /** Include anti-aliased pixels in comparison. Default: false */
+  includeAA?: boolean;
+}
+
+/**
+ * Diff engine for comparing screenshots.
+ */
+export class DiffEngine {
+  private readonly defaultThreshold: number;
+
+  constructor(defaultThreshold: number = DEFAULTS.diffThreshold) {
+    this.defaultThreshold = defaultThreshold;
+  }
+
+  /**
+   * Compare two screenshots and return diff result
+   */
+  compare(
+    current: Screenshot,
+    baseline: Screenshot,
+    options: DiffOptions = {}
+  ): DiffResult {
+    const timer = new Timer();
+
+    // Parse PNG images
+    const img1 = PNG.sync.read(current.data);
+    const img2 = PNG.sync.read(baseline.data);
+
+    // Validate dimensions match
+    if (img1.width !== img2.width || img1.height !== img2.height) {
+      throw new DiffError(
+        `Dimension mismatch: current is ${img1.width}x${img1.height}, baseline is ${img2.width}x${img2.height}`,
+        'DIMENSION_MISMATCH',
+        'Ensure both screenshots use the same viewport size'
+      );
+    }
+
+    const { width, height } = img1;
+    const totalPixels = width * height;
+
+    // Create diff image
+    const diffPng = new PNG({ width, height });
+
+    // Run pixelmatch comparison
+    const diffPixelCount = pixelmatch(
+      img1.data,
+      img2.data,
+      diffPng.data,
+      width,
+      height,
+      {
+        threshold: options.colorThreshold ?? 0.1,
+        includeAA: options.includeAA ?? false,
+        alpha: 0.1,
+        diffColor: [255, 0, 0], // Red for differences
+        diffColorAlt: [0, 255, 0], // Green for anti-aliased
+      }
+    );
+
+    // Calculate diff percentage
+    const diffPercentage = (diffPixelCount / totalPixels) * 100;
+    const threshold = options.threshold ?? this.defaultThreshold;
+
+    // Find changed regions
+    const changedRegions = this.findChangedRegions(diffPng);
+
+    // Only include diff image if there are differences
+    const diffImage = diffPixelCount > 0 ? PNG.sync.write(diffPng) : undefined;
+
+    return {
+      matches: diffPercentage <= threshold,
+      diffPercentage: Math.round(diffPercentage * 100) / 100,
+      diffPixelCount,
+      totalPixels,
+      diffImage: diffImage ? Buffer.from(diffImage) : undefined,
+      changedRegions,
+      diffTimeMs: timer.elapsed(),
+    };
+  }
+
+  /**
+   * Quick check if two screenshots are identical (by hash)
+   */
+  areIdentical(current: Screenshot, baseline: Screenshot): boolean {
+    return current.hash === baseline.hash;
+  }
+
+  /**
+   * Find bounding boxes of changed regions in the diff image
+   */
+  private findChangedRegions(diffPng: PNG): BoundingBox[] {
+    const { width, height, data } = diffPng;
+    const regions: BoundingBox[] = [];
+    const visited = new Set<number>();
+
+    // Scan for red pixels (differences)
+    for (let y = 0; y < height; y++) {
+      for (let x = 0; x < width; x++) {
+        const idx = (y * width + x) * 4;
+        const pixelKey = y * width + x;
+
+        // Check if this is a diff pixel (red channel > 200) and not visited
+        if (data[idx] > 200 && !visited.has(pixelKey)) {
+          // Flood fill to find region bounds
+          const region = this.floodFillBounds(diffPng, x, y, visited);
+          if (region) {
+            regions.push(region);
+          }
+        }
+      }
+    }
+
+    // Merge overlapping regions
+    return this.mergeOverlappingRegions(regions);
+  }
+
+  /**
+   * Flood fill to find bounds of a contiguous changed region
+   */
+  private floodFillBounds(
+    diffPng: PNG,
+    startX: number,
+    startY: number,
+    visited: Set<number>
+  ): BoundingBox | null {
+    const { width, height, data } = diffPng;
+    const stack: Array<[number, number]> = [[startX, startY]];
+
+    let minX = startX;
+    let maxX = startX;
+    let minY = startY;
+    let maxY = startY;
+    let pixelCount = 0;
+
+    while (stack.length > 0) {
+      const [x, y] = stack.pop()!;
+      const pixelKey = y * width + x;
+
+      if (
+        x < 0 ||
+        x >= width ||
+        y < 0 ||
+        y >= height ||
+        visited.has(pixelKey)
+      ) {
+        continue;
+      }
+
+      const idx = (y * width + x) * 4;
+
+      // Check if this is a diff pixel
+      if (data[idx] <= 200) {
+        continue;
+      }
+
+      visited.add(pixelKey);
+      pixelCount++;
+
+      // Update bounds
+      minX = Math.min(minX, x);
+      maxX = Math.max(maxX, x);
+      minY = Math.min(minY, y);
+      maxY = Math.max(maxY, y);
+
+      // Add neighbors (4-connectivity)
+      stack.push([x + 1, y], [x - 1, y], [x, y + 1], [x, y - 1]);
+    }
+
+    // Filter out tiny regions (noise)
+    if (pixelCount < 10) {
+      return null;
+    }
+
+    return {
+      x: minX,
+      y: minY,
+      width: maxX - minX + 1,
+      height: maxY - minY + 1,
+    };
+  }
+
+  /**
+   * Merge overlapping bounding boxes
+   */
+  private mergeOverlappingRegions(regions: BoundingBox[]): BoundingBox[] {
+    if (regions.length <= 1) {
+      return regions;
+    }
+
+    // Sort by x coordinate
+    const sorted = [...regions].sort((a, b) => a.x - b.x);
+    const merged: BoundingBox[] = [];
+
+    let current = sorted[0];
+
+    for (let i = 1; i < sorted.length; i++) {
+      const next = sorted[i];
+
+      // Check if regions overlap or are adjacent (with 10px margin)
+      if (this.regionsOverlap(current, next, 10)) {
+        // Merge into current
+        current = this.mergeBoxes(current, next);
+      } else {
+        merged.push(current);
+        current = next;
+      }
+    }
+
+    merged.push(current);
+    return merged;
+  }
+
+  /**
+   * Check if two bounding boxes overlap (with margin)
+   */
+  private regionsOverlap(a: BoundingBox, b: BoundingBox, margin: number): boolean {
+    return !(
+      a.x + a.width + margin < b.x ||
+      b.x + b.width + margin < a.x ||
+      a.y + a.height + margin < b.y ||
+      b.y + b.height + margin < a.y
+    );
+  }
+
+  /**
+   * Merge two bounding boxes
+   */
+  private mergeBoxes(a: BoundingBox, b: BoundingBox): BoundingBox {
+    const minX = Math.min(a.x, b.x);
+    const minY = Math.min(a.y, b.y);
+    const maxX = Math.max(a.x + a.width, b.x + b.width);
+    const maxY = Math.max(a.y + a.height, b.y + b.height);
+
+    return {
+      x: minX,
+      y: minY,
+      width: maxX - minX,
+      height: maxY - minY,
+    };
+  }
+}
+
+/**
+ * Error class for diff errors
+ */
+export class DiffError extends ServiceError {
+  constructor(message: string, code: string, suggestion?: string) {
+    super(message, code, suggestion);
+    this.name = `${BRAND.name}DiffError`;
+  }
+}
+
+/**
+ * Create a diff engine
+ */
+export function createDiffEngine(defaultThreshold?: number): DiffEngine {
+  return new DiffEngine(defaultThreshold);
+}