@vizzly-testing/cli 0.15.1 → 0.16.1

package/dist/types/index.d.ts

@@ -1,9 +1,426 @@
-export { createVizzly } from "./sdk/index.js";
-export { createUploader } from "./services/uploader.js";
-export { createTDDService } from "./services/tdd-service.js";
-export { createServices } from "./services/index.js";
-export { loadConfig } from "./utils/config-loader.js";
-export * as output from "./utils/output.js";
-export { defineConfig } from "./utils/config-helpers.js";
-export { UploadError } from "./errors/vizzly-error.js";
-export { vizzlyScreenshot, configure, setEnabled } from "./client/index.js";
+/**
+ * Vizzly CLI Type Definitions
+ * @module @vizzly-testing/cli
+ */
+
+import { EventEmitter } from 'events';
+
+// ============================================================================
+// Configuration Types
+// ============================================================================
+
+export interface ServerConfig {
+  port?: number;
+  timeout?: number;
+}
+
+export interface BuildConfig {
+  name?: string;
+  environment?: string;
+  branch?: string;
+  commit?: string;
+  message?: string;
+}
+
+export interface UploadConfig {
+  screenshotsDir?: string | string[];
+  batchSize?: number;
+  timeout?: number;
+}
+
+export interface ComparisonConfig {
+  threshold?: number;
+}
+
+export interface TddConfig {
+  openReport?: boolean;
+}
+
+export interface VizzlyConfig {
+  apiKey?: string;
+  apiUrl?: string;
+  server?: ServerConfig;
+  build?: BuildConfig;
+  upload?: UploadConfig;
+  comparison?: ComparisonConfig;
+  tdd?: TddConfig;
+  plugins?: string[];
+  parallelId?: string;
+  baselineBuildId?: string;
+  baselineComparisonId?: string;
+  eager?: boolean;
+  wait?: boolean;
+  allowNoToken?: boolean;
+  /** Allow additional plugin-specific configuration */
+  [key: string]: unknown;
+}
+
+// ============================================================================
+// Screenshot Types
+// ============================================================================
+
+export interface ScreenshotOptions {
+  properties?: Record<string, unknown>;
+  threshold?: number;
+  fullPage?: boolean;
+  buildId?: string;
+}
+
+export interface ScreenshotResult {
+  success: boolean;
+  status?: 'passed' | 'failed' | 'new';
+  name?: string;
+  diffPercentage?: number;
+}
+
+// ============================================================================
+// Comparison Types
+// ============================================================================
+
+export interface ComparisonResult {
+  id: string;
+  name: string;
+  status: 'passed' | 'failed' | 'new' | 'error' | 'baseline-updated';
+  baseline: string;
+  current: string;
+  diff: string | null;
+  properties: Record<string, unknown>;
+  signature: string;
+  threshold?: number;
+  diffPercentage?: number;
+  diffCount?: number;
+  error?: string;
+}
+
+export interface TddResults {
+  total: number;
+  passed: number;
+  failed: number;
+  new: number;
+  errors: number;
+  comparisons: ComparisonResult[];
+  baseline: BaselineData | null;
+}
+
+export interface BaselineData {
+  buildId: string;
+  buildName: string;
+  environment?: string;
+  branch?: string;
+  threshold: number;
+  createdAt?: string;
+  screenshots: BaselineScreenshot[];
+}
+
+export interface BaselineScreenshot {
+  name: string;
+  originalName?: string;
+  sha256?: string;
+  id?: string;
+  properties: Record<string, unknown>;
+  path: string;
+  signature: string;
+}
+
+// ============================================================================
+// Upload Types
+// ============================================================================
+
+export interface UploadOptions {
+  screenshotsDir?: string;
+  buildName?: string;
+  branch?: string;
+  commit?: string;
+  message?: string;
+  environment?: string;
+  threshold?: number;
+  pullRequestNumber?: string;
+  parallelId?: string;
+  onProgress?: (progress: UploadProgress) => void;
+}
+
+export interface UploadProgress {
+  phase:
+    | 'scanning'
+    | 'processing'
+    | 'deduplication'
+    | 'uploading'
+    | 'completed';
+  message: string;
+  total?: number;
+  current?: number;
+  toUpload?: number;
+  existing?: number;
+  buildId?: string;
+  url?: string;
+}
+
+export interface UploadResult {
+  success: boolean;
+  buildId: string;
+  url: string | null;
+  stats: {
+    total: number;
+    uploaded: number;
+    skipped: number;
+  };
+}
+
+export interface BuildResult {
+  status: 'completed' | 'failed' | 'pending';
+  build: unknown;
+  comparisons?: number;
+  passedComparisons?: number;
+  failedComparisons?: number;
+  url?: string;
+}
+
+// ============================================================================
+// Error Types
+// ============================================================================
+
+export class VizzlyError extends Error {
+  code: string;
+  context: Record<string, unknown>;
+  timestamp: string;
+  constructor(
+    message: string,
+    code?: string,
+    context?: Record<string, unknown>
+  );
+  getUserMessage(): string;
+  toJSON(): {
+    name: string;
+    code: string;
+    message: string;
+    context: Record<string, unknown>;
+    timestamp: string;
+    stack?: string;
+  };
+}
+
+export class ConfigError extends VizzlyError {
+  constructor(message: string, context?: Record<string, unknown>);
+}
+
+export class AuthError extends VizzlyError {
+  constructor(message: string, context?: Record<string, unknown>);
+}
+
+export class NetworkError extends VizzlyError {
+  constructor(message: string, context?: Record<string, unknown>);
+}
+
+export class UploadError extends VizzlyError {
+  constructor(message: string, context?: Record<string, unknown>);
+}
+
+export class ScreenshotError extends VizzlyError {
+  constructor(message: string, context?: Record<string, unknown>);
+}
+
+export class BuildError extends VizzlyError {
+  constructor(message: string, context?: Record<string, unknown>);
+}
+
+export class TimeoutError extends VizzlyError {
+  duration: number;
+  constructor(
+    message: string,
+    duration?: number,
+    context?: Record<string, unknown>
+  );
+}
+
+export class ValidationError extends VizzlyError {
+  errors: string[];
+  constructor(
+    message: string,
+    errors?: string[],
+    context?: Record<string, unknown>
+  );
+}
+
+// ============================================================================
+// SDK Types
+// ============================================================================
+
+export interface VizzlySDKInstance extends EventEmitter {
+  config: VizzlyConfig;
+
+  /** Start the Vizzly server */
+  start(): Promise<{ port: number; url: string }>;
+
+  /** Stop the Vizzly server */
+  stop(): Promise<void>;
+
+  /** Get current configuration */
+  getConfig(): VizzlyConfig;
+
+  /** Capture a screenshot */
+  screenshot(
+    name: string,
+    imageBuffer: Buffer | string,
+    options?: ScreenshotOptions
+  ): Promise<void>;
+
+  /** Upload all captured screenshots */
+  upload(options?: UploadOptions): Promise<UploadResult>;
+
+  /** Run local comparison in TDD mode */
+  compare(
+    name: string,
+    imageBuffer: Buffer | string
+  ): Promise<ComparisonResult>;
+}
+
+export class VizzlySDK extends EventEmitter implements VizzlySDKInstance {
+  config: VizzlyConfig;
+
+  constructor(config: VizzlyConfig, services: unknown);
+
+  start(): Promise<{ port: number; url: string }>;
+  stop(): Promise<void>;
+  getConfig(): VizzlyConfig;
+  screenshot(
+    name: string,
+    imageBuffer: Buffer | string,
+    options?: ScreenshotOptions
+  ): Promise<void>;
+  upload(options?: UploadOptions): Promise<UploadResult>;
+  compare(
+    name: string,
+    imageBuffer: Buffer | string
+  ): Promise<ComparisonResult>;
+}
+
+// ============================================================================
+// Service Types
+// ============================================================================
+
+export interface Uploader {
+  upload(options: UploadOptions): Promise<UploadResult>;
+  waitForBuild(buildId: string, timeout?: number): Promise<BuildResult>;
+}
+
+export interface TddService {
+  downloadBaselines(
+    environment?: string,
+    branch?: string,
+    buildId?: string,
+    comparisonId?: string
+  ): Promise<BaselineData | null>;
+
+  loadBaseline(): Promise<BaselineData | null>;
+
+  compareScreenshot(
+    name: string,
+    imageBuffer: Buffer,
+    properties?: Record<string, unknown>
+  ): Promise<ComparisonResult>;
+
+  getResults(): TddResults;
+  printResults(): Promise<TddResults>;
+  updateBaselines(): number;
+  acceptBaseline(idOrComparison: string | ComparisonResult): Promise<{
+    name: string;
+    status: string;
+    message: string;
+  }>;
+}
+
+export interface Services {
+  apiService: unknown;
+  authService: unknown;
+  configService: unknown;
+  projectService: unknown;
+  uploader: Uploader;
+  buildManager: unknown;
+  serverManager: unknown;
+  tddService: TddService;
+  testRunner: unknown;
+}
+
+// ============================================================================
+// Output Utilities
+// ============================================================================
+
+export interface OutputUtils {
+  info(message: string): void;
+  warn(message: string): void;
+  error(message: string): void;
+  success(message: string): void;
+  debug(category: string, ...args: unknown[]): void;
+  configure(options: { verbose?: boolean }): void;
+}
+
+// ============================================================================
+// Main Exports
+// ============================================================================
+
+/** Create a new Vizzly SDK instance */
+export function createVizzly(
+  config?: VizzlyConfig,
+  options?: { verbose?: boolean }
+): Promise<VizzlySDKInstance>;
+
+/** Take a screenshot for visual regression testing */
+export function vizzlyScreenshot(
+  name: string,
+  imageBuffer: Buffer | string,
+  options?: {
+    properties?: Record<string, unknown>;
+    threshold?: number;
+    fullPage?: boolean;
+  }
+): Promise<void>;
+
+/** Configure the Vizzly client */
+export function configure(config?: {
+  serverUrl?: string;
+  enabled?: boolean;
+}): void;
+
+/** Enable or disable screenshot capture */
+export function setEnabled(enabled: boolean): void;
+
+/** Create an uploader instance */
+export function createUploader(
+  config?: {
+    apiKey?: string;
+    apiUrl?: string;
+    userAgent?: string;
+    command?: string;
+    upload?: UploadConfig;
+  },
+  options?: {
+    signal?: AbortSignal;
+    batchSize?: number;
+    timeout?: number;
+  }
+): Uploader;
+
+/** Create a TDD service instance */
+export function createTDDService(
+  config: VizzlyConfig,
+  options?: {
+    workingDir?: string;
+    setBaseline?: boolean;
+    authService?: unknown;
+  }
+): TddService;
+
+/** Create all services with dependencies */
+export function createServices(
+  config: VizzlyConfig,
+  command?: string
+): Services;
+
+/** Load configuration from file and environment */
+export function loadConfig(options?: { cwd?: string }): Promise<VizzlyConfig>;
+
+/** Define Vizzly configuration with type hints */
+export function defineConfig(config: VizzlyConfig): VizzlyConfig;
+
+/** Output utilities namespace */
+export const output: OutputUtils;

package/dist/types/sdk.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Vizzly SDK Type Definitions
+ * Full SDK for custom integrations
+ * @module @vizzly-testing/cli/sdk
+ */
+
+import { EventEmitter } from 'events';
+
+// Re-export common types
+export {
+  VizzlyConfig,
+  ScreenshotOptions,
+  UploadOptions,
+  UploadResult,
+  ComparisonResult,
+  TddResults,
+  BaselineData,
+  Uploader,
+  TddService,
+  OutputUtils,
+} from './index';
+
+/**
+ * VizzlySDK class - Full SDK for custom integrations
+ *
+ * @example
+ * import { createVizzly } from '@vizzly-testing/cli/sdk';
+ *
+ * const vizzly = await createVizzly({
+ *   apiKey: process.env.VIZZLY_TOKEN,
+ *   server: { port: 3003 }
+ * });
+ *
+ * await vizzly.start();
+ * await vizzly.screenshot('test', buffer);
+ * await vizzly.upload();
+ * await vizzly.stop();
+ */
+export class VizzlySDK extends EventEmitter {
+  config: import('./index').VizzlyConfig;
+
+  constructor(config: import('./index').VizzlyConfig, services: unknown);
+
+  /**
+   * Start the Vizzly server
+   * @returns Server information including port and URL
+   */
+  start(): Promise<{ port: number; url: string }>;
+
+  /**
+   * Stop the Vizzly server
+   */
+  stop(): Promise<void>;
+
+  /**
+   * Get current configuration
+   */
+  getConfig(): import('./index').VizzlyConfig;
+
+  /**
+   * Capture a screenshot
+   * @param name - Screenshot name
+   * @param imageBuffer - Image data as a Buffer, or a file path to an image
+   * @param options - Screenshot options
+   * @throws VizzlyError when server is not running
+   * @throws VizzlyError when file path is provided but file doesn't exist
+   */
+  screenshot(
+    name: string,
+    imageBuffer: Buffer | string,
+    options?: import('./index').ScreenshotOptions
+  ): Promise<void>;
+
+  /**
+   * Upload all captured screenshots
+   * @param options - Upload options
+   * @returns Upload result with build URL and stats
+   */
+  upload(
+    options?: import('./index').UploadOptions
+  ): Promise<import('./index').UploadResult>;
+
+  /**
+   * Run local comparison in TDD mode
+   * @param name - Screenshot name
+   * @param imageBuffer - Current image as a Buffer, or a file path to an image
+   * @returns Comparison result
+   */
+  compare(
+    name: string,
+    imageBuffer: Buffer | string
+  ): Promise<import('./index').ComparisonResult>;
+}
+
+/**
+ * Create a new Vizzly SDK instance
+ *
+ * @param config - Configuration options
+ * @param options - Additional options
+ * @returns Configured Vizzly SDK instance
+ *
+ * @example
+ * const vizzly = await createVizzly({
+ *   apiKey: process.env.VIZZLY_TOKEN,
+ *   apiUrl: 'https://app.vizzly.dev',
+ *   server: { port: 3003 }
+ * });
+ */
+export function createVizzly(
+  config?: import('./index').VizzlyConfig,
+  options?: { verbose?: boolean }
+): Promise<VizzlySDK>;
+
+/** Load configuration from file and environment */
+export function loadConfig(options?: {
+  cwd?: string;
+}): Promise<import('./index').VizzlyConfig>;
+
+/** Output utilities */
+export const output: import('./index').OutputUtils;
+
+/** Create an uploader instance */
+export function createUploader(
+  config?: {
+    apiKey?: string;
+    apiUrl?: string;
+    userAgent?: string;
+    command?: string;
+    upload?: import('./index').UploadConfig;
+  },
+  options?: {
+    signal?: AbortSignal;
+    batchSize?: number;
+    timeout?: number;
+  }
+): import('./index').Uploader;
+
+/** Create a TDD service instance */
+export function createTDDService(
+  config: import('./index').VizzlyConfig,
+  options?: {
+    workingDir?: string;
+    setBaseline?: boolean;
+    authService?: unknown;
+  }
+): import('./index').TddService;

package/dist/utils/config-helpers.js

@@ -1,7 +1,7 @@
 /**
  * Define Vizzly configuration with type hints
- * @param {import('../types/index.js').VizzlyConfig} config
- * @returns {import('../types/index.js').VizzlyConfig}
+ * @param {Object} config - Vizzly configuration object
+ * @returns {Object} The same configuration object (passthrough for type hints)
  */
 export function defineConfig(config) {
   return config;

package/docs/tdd-mode.md

@@ -311,6 +311,40 @@ npx vizzly tdd run "npm test"
 npx vizzly run "npm test" --build-name "Fix: Header alignment issue"
 ```
 
+## Hotspot Filtering
+
+When connected to Vizzly cloud, TDD mode automatically filters out "noise" from known hotspot areas - regions that frequently change across builds (like timestamps, animations, or dynamic content).
+
+### How It Works
+
+1. **Download baselines** - Use the TDD dashboard's Builds page to download baselines from the cloud (hotspot data is included automatically)
+2. **Automatic filtering** - During comparisons, if a diff falls within a known hotspot region, it's automatically marked as passed
+3. **Visual feedback** - You'll see output like:
+   ```
+   ✅ PASSED Dashboard - differences in known hotspots (0.15% different, 42 pixels, 1 region, 95% in hotspots)
+   ```
+
+### Requirements
+
+Hotspot filtering activates automatically when:
+- You have an API token configured (`vizzly login` or `VIZZLY_TOKEN`)
+- You've downloaded baselines from the cloud (via the TDD dashboard's Builds page)
+- The cloud has enough historical build data to calculate hotspot regions
+
+### Filtering Criteria
+
+A diff is filtered (auto-passed) when:
+- **80%+ of the diff** falls within known hotspot regions
+- **High confidence** hotspot data (confidence score ≥ 70)
+
+If the diff falls outside hotspots or confidence is low, the comparison fails normally so you can review it.
+
+### Benefits
+
+- **Reduced noise** - Stop seeing the same timestamp/animation diffs over and over
+- **Faster reviews** - Focus on real visual changes, not known dynamic areas
+- **Smart detection** - Hotspots are calculated from your actual build history, not manual configuration
+
 ## Comparison Settings
 
 TDD Mode uses the same comparison settings as production:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vizzly-testing/cli",
-  "version": "0.15.1",
+  "version": "0.16.1",
   "description": "Visual review platform for UI developers and designers",
   "keywords": [
     "visual-testing",
@@ -23,18 +23,22 @@
   "type": "module",
   "exports": {
     ".": {
+      "types": "./dist/types/index.d.ts",
       "import": "./dist/index.js",
       "require": "./dist/index.js"
     },
     "./client": {
+      "types": "./dist/types/client.d.ts",
       "import": "./dist/client/index.js",
       "require": "./dist/client/index.js"
     },
     "./sdk": {
+      "types": "./dist/types/sdk.d.ts",
       "import": "./dist/sdk/index.js",
       "require": "./dist/sdk/index.js"
     },
     "./config": {
+      "types": "./dist/types/config.d.ts",
       "import": "./dist/utils/config-helpers.js",
       "require": "./dist/utils/config-helpers.js"
     }
@@ -54,14 +58,15 @@
   ],
   "scripts": {
     "start": "node src/index.js",
-    "build": "npm run clean && npm run compile && npm run copy-assets && npm run build:reporter && npm run types",
+    "build": "npm run clean && npm run compile && npm run copy-assets && npm run build:reporter && npm run copy-types",
     "clean": "rimraf dist",
     "compile": "babel src --out-dir dist --ignore '**/*.test.js'",
     "copy-assets": "cp src/services/report-generator/report.css dist/services/report-generator/",
+    "copy-types": "mkdir -p dist/types && cp src/types/*.d.ts dist/types/",
     "build:reporter": "cd src/reporter && vite build",
     "dev:reporter": "cd src/reporter && vite --config vite.dev.config.js",
-    "types": "tsc --emitDeclarationOnly --outDir dist/types",
-    "prepublishOnly": "npm test && npm run build",
+    "test:types": "tsd",
+    "prepublishOnly": "npm run build",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:reporter": "playwright test --config=tests/reporter/playwright.config.js",
@@ -87,6 +92,16 @@
     "glob": "^13.0.0",
     "zod": "^4.1.12"
   },
+  "tsd": {
+    "directory": "test-d",
+    "typingsFile": "src/types/index.d.ts",
+    "compilerOptions": {
+      "esModuleInterop": true,
+      "module": "ESNext",
+      "moduleResolution": "node",
+      "strict": true
+    }
+  },
   "devDependencies": {
     "@babel/cli": "^7.28.0",
     "@babel/core": "^7.23.6",
@@ -99,6 +114,7 @@
     "@playwright/test": "^1.55.1",
     "@tailwindcss/postcss": "^4.1.13",
     "@tanstack/react-query": "^5.90.11",
+    "@types/node": "^24.10.1",
     "@vitejs/plugin-react": "^5.0.3",
     "@vitest/coverage-v8": "^4.0.3",
     "autoprefixer": "^10.4.21",
@@ -114,6 +130,7 @@
     "react-dom": "^19.1.1",
     "rimraf": "^6.0.1",
     "tailwindcss": "^4.1.13",
+    "tsd": "^0.33.0",
     "typescript": "^5.0.4",
     "vite": "^7.1.7",
     "vitest": "^4.0.3",