@vizzly-testing/cli 0.19.1 → 0.20.0

package/dist/client/index.js

@@ -120,7 +120,6 @@ function createSimpleClient(serverUrl) {
             name,
             image,
             properties: options,
-            threshold: options.threshold || 0,
             fullPage: options.fullPage || false
           }),
           signal: controller.signal

package/dist/services/tdd-service.js

@@ -21,7 +21,7 @@
  */
 
 import crypto from 'node:crypto';
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { compare } from '@vizzly-testing/honeydiff';
 import { NetworkError } from '../errors/vizzly-error.js';
@@ -142,7 +142,7 @@ export class TddService {
     this.comparisons = [];
     this.threshold = config.comparison?.threshold || 2.0;
     this.minClusterSize = config.comparison?.minClusterSize ?? 2; // Filter single-pixel noise by default
-    this.signatureProperties = []; // Custom properties from project's baseline_signature_properties
+    this.signatureProperties = config.signatureProperties ?? []; // Custom properties from project's baseline_signature_properties
 
     // Check if we're in baseline update mode
     if (this.setBaseline) {
@@ -184,11 +184,50 @@ export class TddService {
           throw new Error(`Build ${buildId} not found or API returned null`);
         }
 
+        // When downloading baselines, always start with a clean slate
+        // This handles signature property changes, build switches, and any stale state
+        output.info('Clearing local state before downloading baselines...');
+        try {
+          // Clear everything - baselines, current screenshots, diffs, and metadata
+          // This ensures we start fresh with the new baseline build
+          rmSync(this.baselinePath, {
+            recursive: true,
+            force: true
+          });
+          rmSync(this.currentPath, {
+            recursive: true,
+            force: true
+          });
+          rmSync(this.diffPath, {
+            recursive: true,
+            force: true
+          });
+          mkdirSync(this.baselinePath, {
+            recursive: true
+          });
+          mkdirSync(this.currentPath, {
+            recursive: true
+          });
+          mkdirSync(this.diffPath, {
+            recursive: true
+          });
+
+          // Clear baseline metadata file (will be regenerated with new baseline)
+          const baselineMetadataPath = safePath(this.workingDir, '.vizzly', 'baseline-metadata.json');
+          if (existsSync(baselineMetadataPath)) {
+            rmSync(baselineMetadataPath, {
+              force: true
+            });
+          }
+        } catch (error) {
+          output.error(`Failed to clear local state: ${error.message}`);
+        }
+
         // Extract signature properties from API response (for variant support)
         if (apiResponse.signatureProperties && Array.isArray(apiResponse.signatureProperties)) {
           this.signatureProperties = apiResponse.signatureProperties;
           if (this.signatureProperties.length > 0) {
-            output.info(`Using custom signature properties: ${this.signatureProperties.join(', ')}`);
+            output.info(`Using signature properties: ${this.signatureProperties.join(', ')}`);
           }
         }
         baselineBuild = apiResponse.build;
@@ -709,7 +748,7 @@ export class TddService {
       this.threshold = metadata.threshold || this.threshold;
 
       // Restore signature properties from saved metadata (for variant support)
-      this.signatureProperties = metadata.signatureProperties || [];
+      this.signatureProperties = metadata.signatureProperties || this.signatureProperties;
       if (this.signatureProperties.length > 0) {
         output.debug('tdd', `loaded signature properties: ${this.signatureProperties.join(', ')}`);
       }
@@ -818,16 +857,22 @@ export class TddService {
 
     // Baseline exists - compare with it
     try {
+      // Per-screenshot threshold/minClusterSize override support
+      // Priority: screenshot-level > config > defaults
+      // Validate overrides before using them
+      const effectiveThreshold = typeof validatedProperties.threshold === 'number' && validatedProperties.threshold >= 0 ? validatedProperties.threshold : this.threshold;
+      const effectiveMinClusterSize = Number.isInteger(validatedProperties.minClusterSize) && validatedProperties.minClusterSize >= 1 ? validatedProperties.minClusterSize : this.minClusterSize;
+
       // Try to compare - honeydiff will throw if dimensions don't match
       const result = await compare(baselineImagePath, currentImagePath, {
-        threshold: this.threshold,
+        threshold: effectiveThreshold,
         // CIEDE2000 Delta E (2.0 = recommended default)
         antialiasing: true,
         diffPath: diffImagePath,
         overwrite: true,
         includeClusters: true,
         // Enable spatial clustering analysis
-        minClusterSize: this.minClusterSize // Filter single-pixel noise (default: 2)
+        minClusterSize: effectiveMinClusterSize // Filter single-pixel noise (default: 2)
       });
       if (!result.isDifferent) {
         // Images match
@@ -840,7 +885,8 @@ export class TddService {
           diff: null,
           properties: validatedProperties,
           signature,
-          threshold: this.threshold,
+          threshold: effectiveThreshold,
+          minClusterSize: effectiveMinClusterSize,
           // Include honeydiff metrics even for passing comparisons
           totalPixels: result.totalPixels,
           aaPixelsIgnored: result.aaPixelsIgnored,
@@ -886,7 +932,8 @@ export class TddService {
           diff: diffImagePath,
           properties: validatedProperties,
           signature,
-          threshold: this.threshold,
+          threshold: effectiveThreshold,
+          minClusterSize: effectiveMinClusterSize,
           diffPercentage: result.diffPercentage,
           diffCount: result.diffPixels,
           reason: isHotspotFiltered ? 'hotspot-filtered' : 'pixel-diff',

package/dist/services/test-runner.js

@@ -189,10 +189,11 @@ export class TestRunner extends EventEmitter {
         };
 
         // Only include metadata if we have meaningful config to send
-        if (this.config.comparison?.threshold != null) {
+        if (this.config.comparison?.threshold != null || this.config.comparison?.minClusterSize != null) {
           buildPayload.metadata = {
             comparison: {
-              threshold: this.config.comparison.threshold
+              threshold: this.config.comparison.threshold,
+              minClusterSize: this.config.comparison.minClusterSize
             }
           };
         }

package/dist/types/client.d.ts

@@ -23,10 +23,11 @@
  * await vizzlyScreenshot('homepage', './screenshots/homepage.png');
  *
  * @example
- * // With properties and threshold
+ * // With properties and comparison settings
  * await vizzlyScreenshot('checkout-form', screenshot, {
  *   properties: { browser: 'chrome', viewport: '1920x1080' },
- *   threshold: 5
+ *   threshold: 5,
+ *   minClusterSize: 10
  * });
  */
 export function vizzlyScreenshot(
@@ -35,6 +36,7 @@ export function vizzlyScreenshot(
   options?: {
     properties?: Record<string, unknown>;
     threshold?: number;
+    minClusterSize?: number;
     fullPage?: boolean;
   }
 ): Promise<void>;

package/dist/types/index.d.ts

@@ -54,6 +54,8 @@ export interface VizzlyConfig {
   upload?: UploadConfig;
   comparison?: ComparisonConfig;
   tdd?: TddConfig;
+  /** Custom properties for baseline matching (e.g., ['theme', 'device']) */
+  signatureProperties?: string[];
   plugins?: string[];
   parallelId?: string;
   baselineBuildId?: string;
@@ -72,6 +74,7 @@ export interface VizzlyConfig {
 export interface ScreenshotOptions {
   properties?: Record<string, unknown>;
   threshold?: number;
+  minClusterSize?: number;
   fullPage?: boolean;
   buildId?: string;
 }
@@ -97,6 +100,7 @@ export interface ComparisonResult {
   properties: Record<string, unknown>;
   signature: string;
   threshold?: number;
+  minClusterSize?: number;
   diffPercentage?: number;
   diffCount?: number;
   error?: string;
@@ -465,6 +469,7 @@ export function vizzlyScreenshot(
   options?: {
     properties?: Record<string, unknown>;
     threshold?: number;
+    minClusterSize?: number;
     fullPage?: boolean;
   }
 ): Promise<void>;

package/dist/utils/config-schema.js

@@ -36,9 +36,11 @@ const uploadSchema = z.object({
 /**
  * Comparison configuration schema
  * threshold: CIEDE2000 Delta E units (0.0 = exact, 1.0 = JND, 2.0 = recommended, 3.0+ = permissive)
+ * minClusterSize: pixels (1 = exact)
  */
 const comparisonSchema = z.object({
-  threshold: z.number().min(0).default(2.0)
+  threshold: z.number().min(0).default(2.0),
+  minClusterSize: z.int().min(1).default(2)
 });
 
 /**
@@ -70,11 +72,13 @@ export const vizzlyConfigSchema = z.object({
     timeout: 30000
   }),
   comparison: comparisonSchema.default({
-    threshold: 2.0
+    threshold: 2.0,
+    minClusterSize: 2
   }),
   tdd: tddSchema.default({
     openReport: false
   }),
+  signatureProperties: z.array(z.string()).default([]),
   plugins: z.array(z.string()).default([]),
   // Additional optional fields
   parallelId: z.string().optional(),
@@ -99,7 +103,8 @@ export const vizzlyConfigSchema = z.object({
     timeout: 30000
   },
   comparison: {
-    threshold: 2.0
+    threshold: 2.0,
+    minClusterSize: 2
   },
   tdd: {
     openReport: false

package/dist/utils/security.js

@@ -13,6 +13,62 @@ import * as output from './output.js';
  * @param {boolean} allowSlashes - Whether to allow forward slashes (for browser version strings)
  * @returns {string} Sanitized screenshot name
  */
+/**
+ * Validate screenshot name for security (no transformations, just validation)
+ * Throws if name contains path traversal or other dangerous patterns
+ *
+ * @param {string} name - Screenshot name to validate
+ * @param {number} maxLength - Maximum allowed length
+ * @returns {string} The original name (unchanged) if valid
+ * @throws {Error} If name contains dangerous patterns
+ */
+export function validateScreenshotName(name, maxLength = 255) {
+  if (typeof name !== 'string' || name.length === 0) {
+    throw new Error('Screenshot name must be a non-empty string');
+  }
+  if (name.length > maxLength) {
+    throw new Error(`Screenshot name exceeds maximum length of ${maxLength} characters`);
+  }
+
+  // Block directory traversal patterns
+  if (name.includes('..') || name.includes('\\')) {
+    throw new Error('Screenshot name contains invalid path characters');
+  }
+
+  // Block forward slashes (path separators)
+  if (name.includes('/')) {
+    throw new Error('Screenshot name cannot contain forward slashes');
+  }
+
+  // Block absolute paths
+  if (isAbsolute(name)) {
+    throw new Error('Screenshot name cannot be an absolute path');
+  }
+
+  // Return the original name unchanged - validation only!
+  return name;
+}
+
+/**
+ * Validate screenshot name for security (allows spaces, preserves original name)
+ *
+ * This function only validates for security - it does NOT transform spaces.
+ * Spaces are preserved so that:
+ * 1. generateScreenshotSignature() uses the original name with spaces (matches cloud)
+ * 2. generateBaselineFilename() handles space→hyphen conversion (matches cloud)
+ *
+ * Flow: "VBtn dark" → sanitize → "VBtn dark" → signature: "VBtn dark|1265||" → filename: "VBtn-dark_hash.png"
+ *
+ * @param {string} name - Screenshot name to validate
+ * @param {number} maxLength - Maximum allowed length (default: 255)
+ * @param {boolean} allowSlashes - Whether to allow forward slashes (for browser version strings)
+ * @returns {string} The validated name (unchanged if valid, spaces preserved)
+ * @throws {Error} If name contains dangerous patterns
+ *
+ * @example
+ * sanitizeScreenshotName("VBtn dark") // Returns "VBtn dark" (spaces preserved)
+ * sanitizeScreenshotName("My/Component") // Throws error (contains /)
+ */
 export function sanitizeScreenshotName(name, maxLength = 255, allowSlashes = false) {
   if (typeof name !== 'string' || name.length === 0) {
     throw new Error('Screenshot name must be a non-empty string');
@@ -36,9 +92,10 @@ export function sanitizeScreenshotName(name, maxLength = 255, allowSlashes = fal
     throw new Error('Screenshot name cannot be an absolute path');
   }
 
-  // Allow only safe characters: alphanumeric, hyphens, underscores, dots, and optionally slashes
+  // Allow only safe characters: alphanumeric, hyphens, underscores, dots, spaces, and optionally slashes
+  // Spaces are allowed here and will be converted to hyphens in generateBaselineFilename() to match cloud behavior
   // Replace other characters with underscores
-  const allowedChars = allowSlashes ? /[^a-zA-Z0-9._/-]/g : /[^a-zA-Z0-9._-]/g;
+  const allowedChars = allowSlashes ? /[^a-zA-Z0-9._ /-]/g : /[^a-zA-Z0-9._ -]/g;
   let sanitized = name.replace(allowedChars, '_');
 
   // Prevent names that start with dots (hidden files)

package/package.json

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