@vizzly-testing/cli 0.30.0 → 0.32.0

package/dist/tdd/server-registry.js

@@ -1,4 +1,4 @@
-import { execSync } from 'node:child_process';
+import { execFileSync } from 'node:child_process';
 import { randomBytes } from 'node:crypto';
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { createServer } from 'node:net';
@@ -10,9 +10,13 @@ import { join } from 'node:path';
  * Enables the menubar app to discover and manage multiple concurrent servers.
  */
 export class ServerRegistry {
-  constructor() {
-    this.vizzlyHome = process.env.VIZZLY_HOME || join(homedir(), '.vizzly');
+  constructor({
+    vizzlyHome,
+    logger = console
+  } = {}) {
+    this.vizzlyHome = vizzlyHome || process.env.VIZZLY_HOME || join(homedir(), '.vizzly');
     this.registryPath = join(this.vizzlyHome, 'servers.json');
+    this.logger = logger;
   }
 
   /**
@@ -40,7 +44,7 @@ export class ServerRegistry {
       }
     } catch (_err) {
       // Corrupted file, start fresh
-      console.warn('Warning: Could not read server registry, starting fresh');
+      this.logger.warn('Warning: Could not read server registry, starting fresh');
     }
     return {
       version: 1,
@@ -64,10 +68,10 @@ export class ServerRegistry {
     if (!serverInfo.pid || !serverInfo.port || !serverInfo.directory) {
       throw new Error('Missing required fields: pid, port, directory');
     }
-    let port = Number(serverInfo.port);
-    let pid = Number(serverInfo.pid);
-    if (Number.isNaN(port) || Number.isNaN(pid)) {
-      throw new Error('Invalid port or pid - must be numbers');
+    let port = parsePositiveInteger(serverInfo.port);
+    let pid = parsePositiveInteger(serverInfo.pid);
+    if (port === null || pid === null) {
+      throw new Error('Invalid port or pid - must be positive integers');
     }
     let registry = this.read();
 
@@ -171,15 +175,7 @@ export class ServerRegistry {
    * The menubar app listens for this in addition to file watching.
    */
   notifyMenubar() {
-    if (process.platform !== 'darwin') return;
-    try {
-      execSync('notifyutil -p dev.vizzly.serverChanged', {
-        stdio: 'ignore',
-        timeout: 500
-      });
-    } catch {
-      // Non-fatal - menubar will still see changes via file watching
-    }
+    notifyServerRegistryChanged();
   }
 
   /**
@@ -218,6 +214,31 @@ export class ServerRegistry {
     return startPort;
   }
 }
+function parsePositiveInteger(value) {
+  if (typeof value === 'number') {
+    return Number.isInteger(value) && value > 0 ? value : null;
+  }
+  if (typeof value === 'string' && /^[1-9]\d*$/.test(value)) {
+    return Number(value);
+  }
+  return null;
+}
+export function notifyServerRegistryChanged({
+  platform = process.platform,
+  execFile = execFileSync
+} = {}) {
+  if (platform !== 'darwin') return false;
+  try {
+    execFile('notifyutil', ['-p', 'dev.vizzly.serverChanged'], {
+      stdio: 'ignore',
+      timeout: 500
+    });
+    return true;
+  } catch {
+    // Non-fatal - menubar will still see changes via file watching
+    return false;
+  }
+}
 
 /**
  * Check if a port is free (not in use by any process)

package/dist/tdd/services/baseline-manager.js

@@ -57,6 +57,29 @@ export function clearBaselineData(paths) {
   }
 }
 
+/**
+ * Clear per-run screenshot artifacts while preserving approved baselines.
+ *
+ * @param {{ currentPath: string, diffPath: string }} paths
+ */
+export function clearRunData(paths) {
+  let {
+    currentPath,
+    diffPath
+  } = paths;
+  for (let dir of [currentPath, diffPath]) {
+    if (existsSync(dir)) {
+      rmSync(dir, {
+        recursive: true,
+        force: true
+      });
+    }
+    mkdirSync(dir, {
+      recursive: true
+    });
+  }
+}
+
 /**
  * Save an image as baseline
  *

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/services/hotspot-service.js

@@ -55,17 +55,4 @@ export async function downloadHotspots(options) {
       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

@@ -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';
@@ -22,7 +22,8 @@ import { generateBaselineFilename as defaultGenerateBaselineFilename, generateCo
 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 { buildTddDependencyOps, resolveTddPaths, resolveTddWorkingDirectory } from './runtime-context.js';
+import { baselineExists as defaultBaselineExists, clearBaselineData as defaultClearBaselineData, clearRunData as defaultClearRunData, 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';
 
@@ -40,110 +41,80 @@ export function createTDDService(config, options = {}, deps = {}) {
 }
 export class TddService {
   constructor(config, workingDir = process.cwd(), setBaseline = false, authService = null, deps = {}) {
-    // Grouped dependencies with defaults
-    let {
-      // Core utilities
-      output = defaultOutput,
-      colors = defaultColors,
-      validatePathSecurity = defaultValidatePathSecurity,
-      initializeDirectories = defaultInitializeDirectories,
-      // File system operations
-      fs = {},
-      // API operations
-      api = {},
-      // Baseline metadata operations
-      metadata = {},
-      // Baseline file management
-      baseline = {},
-      // Screenshot comparison
-      comparison = {},
-      // Signature generation and security
-      signature = {},
-      // Result building
-      results = {},
-      // Other
-      calculateHotspotCoverage = defaultCalculateHotspotCoverage
-    } = deps;
-
-    // Merge grouped deps with defaults
-    let fsOps = {
-      existsSync: defaultExistsSync,
-      mkdirSync: defaultMkdirSync,
-      readFileSync: defaultReadFileSync,
-      writeFileSync: defaultWriteFileSync,
-      ...fs
-    };
-    let apiOps = {
-      createApiClient: defaultCreateApiClient,
-      getTddBaselines: defaultGetTddBaselines,
-      getBuilds: defaultGetBuilds,
-      getComparison: defaultGetComparison,
-      getBatchHotspots: defaultGetBatchHotspots,
-      fetchWithTimeout: defaultFetchWithTimeout,
-      getDefaultBranch: defaultGetDefaultBranch,
-      ...api
-    };
-    let metadataOps = {
-      loadBaselineMetadata: defaultLoadBaselineMetadata,
-      saveBaselineMetadata: defaultSaveBaselineMetadata,
-      createEmptyBaselineMetadata: defaultCreateEmptyBaselineMetadata,
-      upsertScreenshotInMetadata: defaultUpsertScreenshotInMetadata,
-      loadHotspotMetadata: defaultLoadHotspotMetadata,
-      saveHotspotMetadata: defaultSaveHotspotMetadata,
-      loadRegionMetadata: defaultLoadRegionMetadata,
-      saveRegionMetadata: defaultSaveRegionMetadata,
-      ...metadata
-    };
-    let baselineOps = {
-      baselineExists: defaultBaselineExists,
-      clearBaselineData: defaultClearBaselineData,
-      getBaselinePath: defaultGetBaselinePath,
-      getCurrentPath: defaultGetCurrentPath,
-      getDiffPath: defaultGetDiffPath,
-      saveBaseline: defaultSaveBaseline,
-      saveCurrent: defaultSaveCurrent,
-      ...baseline
-    };
-    let comparisonOps = {
-      compareImages: defaultCompareImages,
-      buildPassedComparison: defaultBuildPassedComparison,
-      buildNewComparison: defaultBuildNewComparison,
-      buildFailedComparison: defaultBuildFailedComparison,
-      buildErrorComparison: defaultBuildErrorComparison,
-      isDimensionMismatchError: defaultIsDimensionMismatchError,
-      ...comparison
-    };
-    let signatureOps = {
-      generateScreenshotSignature: defaultGenerateScreenshotSignature,
-      generateBaselineFilename: defaultGenerateBaselineFilename,
-      generateComparisonId: defaultGenerateComparisonId,
-      sanitizeScreenshotName: defaultSanitizeScreenshotName,
-      validateScreenshotProperties: defaultValidateScreenshotProperties,
-      safePath: defaultSafePath,
-      ...signature
-    };
-    let resultsOps = {
-      buildResults: defaultBuildResults,
-      getFailedComparisons: defaultGetFailedComparisons,
-      getNewComparisons: defaultGetNewComparisons,
-      ...results
+    let defaults = {
+      output: defaultOutput,
+      colors: defaultColors,
+      validatePathSecurity: defaultValidatePathSecurity,
+      initializeDirectories: defaultInitializeDirectories,
+      calculateHotspotCoverage: defaultCalculateHotspotCoverage,
+      fs: {
+        existsSync: defaultExistsSync,
+        mkdirSync: defaultMkdirSync,
+        readFileSync: defaultReadFileSync,
+        writeFileSync: defaultWriteFileSync
+      },
+      api: {
+        createApiClient: defaultCreateApiClient,
+        getTddBaselines: defaultGetTddBaselines,
+        getBuilds: defaultGetBuilds,
+        getComparison: defaultGetComparison,
+        getComparisonContext: defaultGetComparisonContext,
+        getBatchHotspots: defaultGetBatchHotspots,
+        fetchWithTimeout: defaultFetchWithTimeout,
+        getDefaultBranch: defaultGetDefaultBranch
+      },
+      metadata: {
+        loadBaselineMetadata: defaultLoadBaselineMetadata,
+        saveBaselineMetadata: defaultSaveBaselineMetadata,
+        createEmptyBaselineMetadata: defaultCreateEmptyBaselineMetadata,
+        upsertScreenshotInMetadata: defaultUpsertScreenshotInMetadata,
+        loadHotspotMetadata: defaultLoadHotspotMetadata,
+        saveHotspotMetadata: defaultSaveHotspotMetadata,
+        loadRegionMetadata: defaultLoadRegionMetadata,
+        saveRegionMetadata: defaultSaveRegionMetadata
+      },
+      baseline: {
+        baselineExists: defaultBaselineExists,
+        clearBaselineData: defaultClearBaselineData,
+        clearRunData: defaultClearRunData,
+        getBaselinePath: defaultGetBaselinePath,
+        getCurrentPath: defaultGetCurrentPath,
+        getDiffPath: defaultGetDiffPath,
+        saveBaseline: defaultSaveBaseline,
+        saveCurrent: defaultSaveCurrent
+      },
+      comparison: {
+        compareImages: defaultCompareImages,
+        buildPassedComparison: defaultBuildPassedComparison,
+        buildNewComparison: defaultBuildNewComparison,
+        buildFailedComparison: defaultBuildFailedComparison,
+        buildErrorComparison: defaultBuildErrorComparison,
+        isDimensionMismatchError: defaultIsDimensionMismatchError
+      },
+      signature: {
+        generateScreenshotSignature: defaultGenerateScreenshotSignature,
+        generateBaselineFilename: defaultGenerateBaselineFilename,
+        generateComparisonId: defaultGenerateComparisonId,
+        sanitizeScreenshotName: defaultSanitizeScreenshotName,
+        validateScreenshotProperties: defaultValidateScreenshotProperties,
+        safePath: defaultSafePath
+      },
+      results: {
+        buildResults: defaultBuildResults,
+        getFailedComparisons: defaultGetFailedComparisons,
+        getNewComparisons: defaultGetNewComparisons
+      }
     };
-
-    // Store flattened dependencies for use in methods
-    this._deps = {
+    let {
+      runtimeDeps,
+      apiOps
+    } = buildTddDependencyOps(deps, defaults);
+    let {
       output,
-      colors,
       validatePathSecurity,
-      initializeDirectories,
-      calculateHotspotCoverage,
-      ...fsOps,
-      ...apiOps,
-      ...metadataOps,
-      ...baselineOps,
-      ...comparisonOps,
-      ...signatureOps,
-      ...resultsOps
-    };
+      initializeDirectories
+    } = runtimeDeps;
+    this._deps = runtimeDeps;
     this.config = config;
     this.setBaseline = setBaseline;
     this.authService = authService;
@@ -155,15 +126,8 @@ export class TddService {
     });
 
     // Validate and secure the working directory
-    try {
-      this.workingDir = validatePathSecurity(workingDir, workingDir);
-    } catch (error) {
-      output.error(`Invalid working directory: ${error.message}`);
-      throw new Error(`Working directory validation failed: ${error.message}`);
-    }
-
-    // Initialize directories using extracted module
-    let paths = initializeDirectories(this.workingDir);
+    this.workingDir = resolveTddWorkingDirectory(workingDir, validatePathSecurity, output);
+    let paths = resolveTddPaths(this.workingDir, initializeDirectories);
     this.baselinePath = paths.baselinePath;
     this.currentPath = paths.currentPath;
     this.diffPath = paths.diffPath;
@@ -171,7 +135,7 @@ export class TddService {
     // State
     this.baselineData = null;
     this.comparisons = [];
-    this.threshold = config.comparison?.threshold || 2.0;
+    this.threshold = config.comparison?.threshold ?? 2.0;
     this.minClusterSize = config.comparison?.minClusterSize ?? 2;
     this.signatureProperties = config.signatureProperties ?? [];
 
@@ -187,6 +151,12 @@ export class TddService {
       output.info('[vizzly] Baseline update mode - will overwrite existing baselines with new ones');
     }
   }
+  clearRunData() {
+    this._deps.clearRunData({
+      currentPath: this.currentPath,
+      diffPath: this.diffPath
+    });
+  }
 
   /**
    * Download baselines from cloud
@@ -200,6 +170,7 @@ export class TddService {
       getTddBaselines,
       getBuilds,
       getComparison,
+      getComparisonContext,
       clearBaselineData,
       generateScreenshotSignature,
       generateBaselineFilename,
@@ -252,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.`);
         }
@@ -286,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 = {
@@ -325,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) {
@@ -519,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)
@@ -557,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();
@@ -915,7 +921,7 @@ export class TddService {
       return null;
     }
     this.baselineData = metadata;
-    this.threshold = metadata.threshold || this.threshold;
+    this.threshold = metadata.threshold ?? this.threshold;
     this.signatureProperties = metadata.signatureProperties || this.signatureProperties;
     if (this.signatureProperties.length > 0) {
       output.debug('tdd', `loaded signature properties: ${this.signatureProperties.join(', ')}`);

package/dist/types/client.d.ts

@@ -4,6 +4,40 @@
  * @module @vizzly-testing/cli/client
  */
 
+export type ClientLogLevel = 'debug' | 'info' | 'warn' | 'error';
+
+export const LOG_LEVELS: Readonly<Record<ClientLogLevel, number>>;
+
+/**
+ * Check whether client SDK output should log at the requested level.
+ */
+export function shouldLogClient(
+  level: string,
+  configuredLevel?: string
+): boolean;
+
+/**
+ * Auto-discover a local TDD server by searching for `.vizzly/server.json`.
+ */
+export function autoDiscoverTddServer(
+  startDir?: string,
+  deps?: {
+    exists?: (path: string) => boolean;
+    readFile?: (path: string, encoding: BufferEncoding) => string | Buffer;
+  }
+): string | null;
+
+/**
+ * Result returned by a successful screenshot capture.
+ */
+export interface ScreenshotResult {
+  success: boolean;
+  status?: 'passed' | 'failed' | 'new';
+  name?: string;
+  diffPercentage?: number;
+  [key: string]: unknown;
+}
+
 /**
  * Take a screenshot for visual regression testing
  *
@@ -38,8 +72,9 @@ export function vizzlyScreenshot(
     threshold?: number;
     minClusterSize?: number;
     fullPage?: boolean;
+    [key: string]: unknown;
   }
-): Promise<void>;
+): Promise<ScreenshotResult | null>;
 
 /**
  * Flush result summary returned by vizzlyFlush