# iVisionQA API Reference

Complete TypeScript API for the iVisionQA AI analyzer engine.

## Core Functions

### `analyzeScreenshot(screenshotPath, context)`

Sends a screenshot to Claude Vision for quality analysis. Returns a structured score, issue list, and summary.

```typescript
import { analyzeScreenshot } from "lib/ivisionqa/ai-analyzer";

const result = await analyzeScreenshot("screenshot.png", {
  pageName: "Dashboard",
  pageDescription: "Main dashboard with stats and activity feed",
  expectedElements: ["Stats cards", "Activity list", "Sidebar"],
  strictness: "medium",
  focusAreas: ["layout", "spacing", "accessibility"],
});
```

**Parameters:**

| Parameter        | Type              | Description                                           |
| ---------------- | ----------------- | ----------------------------------------------------- |
| `screenshotPath` | `string`          | Absolute or relative path to a PNG or JPEG screenshot |
| `context`        | `AnalysisContext` | Analysis configuration (see below)                    |

**Returns:** `Promise<AIAnalysisResult>`

---

### `compareScreenshots(baselinePath, currentPath, context)`

Compares a baseline screenshot against a current screenshot using Claude Vision. Identifies unintended visual regressions while ignoring expected changes.

```typescript
import { compareScreenshots } from "lib/ivisionqa/ai-analyzer";

const result = await compareScreenshots(
  "test-baselines/dashboard.png",
  "test-results/screenshots/dashboard-current.png",
  {
    pageName: "Dashboard",
    allowedChanges: ["Dynamic data", "Timestamps", "Avatars"],
    strictness: "medium",
  },
);
```

**Parameters:**

| Parameter      | Type                | Description                                |
| -------------- | ------------------- | ------------------------------------------ |
| `baselinePath` | `string`            | Path to the baseline (expected) screenshot |
| `currentPath`  | `string`            | Path to the current (actual) screenshot    |
| `context`      | `ComparisonContext` | Comparison configuration (see below)       |

**Returns:** `Promise<AIAnalysisResult>`

---

### `saveAnalysisReport(result, outputPath)`

Saves an analysis result as a timestamped JSON file. Creates directories if needed.

```typescript
import { saveAnalysisReport } from "lib/ivisionqa/ai-analyzer";

saveAnalysisReport(result, "test-results/ai-reports/dashboard.json");
```

**Parameters:**

| Parameter    | Type               | Description                   |
| ------------ | ------------------ | ----------------------------- |
| `result`     | `AIAnalysisResult` | The analysis result to save   |
| `outputPath` | `string`           | Path for the JSON report file |

---

### `formatIssuesForConsole(issues)`

Formats an issue array into a human-readable console string with severity icons.

```typescript
import { formatIssuesForConsole } from "lib/ivisionqa/ai-analyzer";

console.log(formatIssuesForConsole(result.issues));
// Output:
//   🔴 [CRITICAL] layout: Navigation menu overlaps main content (top-left)
//   🟡 [MINOR] spacing: Inconsistent padding between cards (middle section)
```

**Parameters:**

| Parameter | Type        | Description                             |
| --------- | ----------- | --------------------------------------- |
| `issues`  | `AIIssue[]` | Array of issues from an analysis result |

**Returns:** `string`

---

## Types

### `AIAnalysisResult`

The return type from both `analyzeScreenshot` and `compareScreenshots`.

```typescript
interface AIAnalysisResult {
  /** Whether the page passed the strictness threshold */
  passed: boolean;
  /** Quality score from 0-100 */
  score: number;
  /** List of identified issues */
  issues: AIIssue[];
  /** Brief overall assessment from Claude */
  summary: string;
  /** Raw JSON response from Claude (for debugging) */
  rawResponse: string;
}
```

---

### `AIIssue`

An individual issue identified by Claude Vision.

```typescript
interface AIIssue {
  /** Issue severity level */
  severity: "critical" | "major" | "minor" | "suggestion";
  /** Issue category */
  category: string;
  /** Human-readable description of the issue */
  description: string;
  /** Where on the page the issue occurs */
  location?: string;
}
```

**Categories for `analyzeScreenshot`:**
`layout` | `typography` | `color` | `spacing` | `accessibility` | `functionality` | `responsiveness`

**Categories for `compareScreenshots`:**
`layout` | `typography` | `color` | `spacing` | `alignment` | `missing-element` | `extra-element`

---

### `AnalysisContext`

Configuration passed to `analyzeScreenshot`.

```typescript
interface AnalysisContext {
  /** Name of the page being analyzed (shown in reports) */
  pageName: string;
  /** Description of the page's purpose and expected content */
  pageDescription?: string;
  /** List of UI elements that should be present */
  expectedElements?: string[];
  /** Pass/fail threshold: 'low' (50), 'medium' (70), 'high' (85) */
  strictness?: "low" | "medium" | "high";
  /** Areas for Claude to focus on during analysis */
  focusAreas?: string[];
}
```

**Default `focusAreas`:** `['layout', 'typography', 'spacing', 'color', 'responsiveness', 'accessibility']`

---

### `ComparisonContext`

Configuration passed to `compareScreenshots`. Extends `AnalysisContext`.

```typescript
interface ComparisonContext extends AnalysisContext {
  /** Changes that are intentional and should be ignored */
  allowedChanges?: string[];
}
```

---

## Strictness Thresholds

| Strictness | Min Score to Pass | Recommended Use                   |
| ---------- | ----------------- | --------------------------------- |
| `low`      | 50                | Prototypes, early development     |
| `medium`   | 70                | Staging, pre-release QA           |
| `high`     | 85                | Production readiness, polished UI |

---

## Model Configuration

iVisionQA uses Claude Sonnet for analysis. The model is configured in `ai-analyzer.ts`:

```typescript
model: "claude-sonnet-4-5-20250929";
```

Each `analyzeScreenshot` call uses approximately 1,500--2,000 tokens. Each `compareScreenshots` call uses approximately 2,500--3,000 tokens (two images).

**Estimated cost per call:** ~$0.01--0.02 at current Anthropic pricing.