@bughunters/vision 1.0.0

package/README.md

@@ -0,0 +1,167 @@
+# 🐞 BugHunters Vision
+
+**InfoSec-friendly AI Visual Testing for Playwright.**
+
+Stop fighting 1-pixel false positives. BugHunters Vision uses Multimodal AI (Claude) to evaluate visual regression tests like a human QA — while keeping all your screenshots 100% local.
+
+> Images are **never stored on our servers**. They are Base64-encoded, evaluated in-memory for a single request, and immediately discarded.
+
+---
+
+## How it works
+
+1. A test takes a screenshot of the current page.
+2. BugHunters Vision looks for a baseline in `./bhv-snapshots/`.
+3. **No baseline** → saves it as the new baseline, test passes ✅
+4. **Baseline found → Fast Pixel Match** → pixel-perfect = instant PASS, no AI call needed ⚡
+5. **Pixels differ** → both images are sent (Base64, HTTPS) to the BugHunters Vision API.
+6. The API calls **Anthropic Claude** (multimodal vision) to evaluate the diff like a human QA.
+7. Returns `{ status: "PASS" | "FAIL", reason: "..." }` — test passes or fails accordingly.
+8. After all tests finish, a **standalone HTML report** is generated locally.
+
+---
+
+## Quick start
+
+### 1. Install
+
+```bash
+npm install @bughunters/vision --save-dev
+```
+
+### 2. Set your API token
+
+Get a token at [bughunters.vision](https://bughunters.vision).
+
+```bash
+# .env or your CI secrets manager
+BUGHUNTERS_VISION_TOKEN=bhv_your_token_here
+```
+
+### 3. Configure `playwright.config.ts`
+
+```typescript
+import { defineConfig, devices } from '@playwright/test';
+import type { VisionFixtureOptions } from '@bughunters/vision';
+
+export default defineConfig<VisionFixtureOptions>({
+  testDir: './tests',
+  reporter: [
+    ['list'],
+    ['@bughunters/vision/reporter', { snapshotsDir: './bhv-snapshots', reportDir: './bhv-report' }],
+  ],
+  use: {
+    bvMode: 'ai',  // 'ai' | 'strict' | 'off'
+  },
+  projects: [
+    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
+  ],
+});
+```
+
+### 4. Write a visual test
+
+```typescript
+import { test } from '@bughunters/vision';
+
+test('homepage looks correct', async ({ page, visionCheck }) => {
+  await page.goto('https://example.com');
+  await page.waitForLoadState('networkidle');
+  await visionCheck('homepage');
+});
+```
+
+You can pass an optional AI hint as the second argument:
+
+```typescript
+await visionCheck('dashboard', 'Ignore the live timestamp in the top-right corner.');
+```
+
+### 5. Run your tests
+
+```bash
+# First run — baselines are created automatically, all tests pass
+BUGHUNTERS_VISION_TOKEN=bhv_... npx playwright test
+
+# Second run — Fast Pixel Match first; AI only called if pixels differ
+npx playwright test
+
+# Force-update all baselines after an intentional UI change
+BHV_UPDATE_BASELINE=true npx playwright test
+```
+
+### 6. View the HTML report
+
+```bash
+open bhv-report/index.html      # macOS
+start bhv-report/index.html     # Windows
+xdg-open bhv-report/index.html  # Linux
+```
+
+The report includes side-by-side Baseline / Current / Diff views with full-screen zoom, Light/Dark theme toggle, and per-test AI verdicts.
+
+---
+
+## Configuration reference
+
+All options can be set in `playwright.config.ts` under `use:`, or overridden via environment variables.
+
+| Option in `use:` | Environment variable | Default | Description |
+|---|---|---|---|
+| `bvMode` | `BHV_MODE` | `'ai'` | Comparison mode: `ai` · `strict` · `off` |
+| `bvSnapshotsDir` | `BHV_SNAPSHOTS_DIR` | `'./bhv-snapshots'` | Where to store PNG snapshots |
+| `bvUpdateBaseline` | `BHV_UPDATE_BASELINE` | `false` | Force-overwrite all baselines on this run |
+| `bvApiUrl` | `BUGHUNTERS_VISION_API_URL` | *(production)* | Override API endpoint (e.g. for self-hosted) |
+| `bvToken` | `BUGHUNTERS_VISION_TOKEN` | — | Your API token — always use env var, never commit |
+
+### Comparison modes
+
+| Mode | Behaviour |
+|---|---|
+| `ai` *(default)* | Fast Pixel Match first → AI evaluation only if pixels differ |
+| `strict` | Fail immediately on any pixel difference — no AI call |
+| `off` | Skip all visual checks — every test passes instantly |
+
+```bash
+BHV_MODE=strict npx playwright test
+BHV_MODE=off    npx playwright test
+```
+
+---
+
+## HTML Report
+
+After every run a report is generated at `bhv-report/index.html`. No upload, no cloud — everything is local.
+
+- **Summary bar** — total / passed / failed / baseline counts
+- **Baseline / Current / Diff** tab view per test — click any image for fullscreen zoom
+- **AI verdict** with human-readable explanation for every evaluated test
+- **Low Confidence FAIL** — amber tag when the AI detects a likely intentional change (A/B test, loading state) that a human should review
+- **Method badge** — `AI` · `PIXEL` · `NEW` — shows how each test was evaluated
+- **Light / Dark / System** theme toggle, persisted in `localStorage`
+
+---
+
+## Security model
+
+- **Zero cloud storage** — images live only in RAM for the duration of one API request and are never written to disk on our side.
+- **Local baselines** — all baseline PNGs stay on your machine or CI runner. We never see your UI.
+- **Token isolation** — each customer token is scoped to their own credit bucket. Our Anthropic key never leaves our infrastructure.
+- **InfoSec approved** — suitable for banking, healthcare, and enterprise environments where screenshots cannot leave the perimeter.
+
+---
+
+## Native Playwright integration
+
+BugHunters Vision results appear directly in the **native Playwright HTML report** as annotations and attachments:
+
+- `BugHunters Vision: PASS/FAIL/ERROR — <reason>` annotation on each test
+- `bhv-baseline` and `bhv-current` screenshot attachments in the Playwright report
+
+---
+
+## Links
+
+- 🌐 [bughunters.vision](https://bughunters.vision) — get your token
+- 📄 [Changelog](https://github.com/bughunters/vision/releases)
+- 🐛 [Report an issue](https://github.com/bughunters/vision/issues)

package/dist/check.d.ts

@@ -0,0 +1,16 @@
+import type { Page, TestInfo } from '@playwright/test';
+import type { VisionMode } from './types';
+export interface RunVisionCheckOptions {
+    page: Page;
+    name: string;
+    prompt?: string;
+    apiUrl: string;
+    mode: VisionMode;
+    snapshotsDir: string;
+    updateBaseline: boolean;
+    token?: string;
+    testInfo?: TestInfo;
+}
+export declare function getLastRemainingBalance(): string | null;
+export declare function runVisionCheck(opts: RunVisionCheckOptions): Promise<void>;
+//# sourceMappingURL=check.d.ts.map

package/dist/check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../src/check.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAGvD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAE1C,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,IAAI,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,UAAU,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,OAAO,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB;AAKD,wBAAgB,uBAAuB,IAAI,MAAM,GAAG,IAAI,CAEvD;AA+GD,wBAAsB,cAAc,CAAC,IAAI,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CA4I/E"}

package/dist/check.js

@@ -0,0 +1,255 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getLastRemainingBalance = getLastRemainingBalance;
+exports.runVisionCheck = runVisionCheck;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const test_1 = require("@playwright/test");
+const pixel_match_1 = require("./pixel-match");
+const results_1 = require("./results");
+// Module-level balance tracker — updated after each AI call, read by reporter.onEnd()
+let _lastRemainingBalance = null;
+function getLastRemainingBalance() {
+    return _lastRemainingBalance;
+}
+async function callVisionApi(imageBase, imageCurrent, prompt, apiUrl, token) {
+    const headers = { 'Content-Type': 'application/json' };
+    if (token) {
+        headers['Authorization'] = `Bearer ${token}`;
+    }
+    // 75-second fetch timeout — gives Claude Vision enough time to respond while
+    // still failing before the 90-second Playwright test timeout.
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), 75_000);
+    let response;
+    try {
+        response = await fetch(`${apiUrl}/api/compare`, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify({ imageBase, imageCurrent, prompt }),
+            signal: controller.signal,
+        });
+    }
+    catch (err) {
+        if (err?.name === 'AbortError') {
+            throw new Error('[BugHunters Vision] API request timed out after 75 s — the server did not respond in time.');
+        }
+        throw err;
+    }
+    finally {
+        clearTimeout(timeoutId);
+    }
+    // Graceful 402: credits exhausted — return FAIL, never throw
+    if (response.status === 402) {
+        const body = await response.json().catch(() => ({
+            reason: 'BugHunters Vision API Limit Reached. Please top up your account.',
+        }));
+        return {
+            status: 'FAIL',
+            reason: body.reason ?? 'BugHunters Vision API Limit Reached. Please top up your account.',
+        };
+    }
+    // Graceful 503: AI temporarily overloaded — return ERROR, never throw or fail the test
+    if (response.status === 503) {
+        const body = await response.json().catch(() => ({
+            error: 'Claude AI is temporarily overloaded. Please retry in a moment.',
+        }));
+        return {
+            status: 'ERROR',
+            reason: body.error ?? 'Claude AI is temporarily overloaded. Please retry in a moment.',
+        };
+    }
+    if (!response.ok) {
+        const text = await response.text();
+        throw new Error(`[BugHunters Vision] API error (${response.status}): ${text}`);
+    }
+    // Track remaining balance from response header
+    const remaining = response.headers.get('X-RateLimit-Remaining');
+    if (remaining !== null) {
+        _lastRemainingBalance = remaining;
+    }
+    return response.json();
+}
+function humanReadableApiError(raw) {
+    if (raw.includes('timed out')) {
+        return 'Request timed out — the BugHunters Vision API did not respond in time. Try again or check the service status.';
+    }
+    const match = raw.match(/API error \((\d+)\)/);
+    if (match) {
+        switch (parseInt(match[1], 10)) {
+            case 401: return 'Unauthorized — missing or invalid API token. Set the BUGHUNTERS_VISION_TOKEN environment variable.';
+            case 403: return 'Access forbidden — your token does not have permission for this operation.';
+            case 429: return 'Rate limited — too many requests. Please wait a moment before retrying.';
+            case 500: return 'Internal server error — the BugHunters Vision API encountered an unexpected error.';
+            case 502: return 'AI evaluation failed — the server could not process the request. Try again.';
+            case 503: return 'Claude AI is temporarily overloaded. Please wait a moment and try again.';
+            default: return `API returned HTTP ${match[1]} — check your configuration and token.`;
+        }
+    }
+    return raw;
+}
+async function pushToPlaywright(testInfo, status, reason, resolvedDir, baselineFile, currentFile) {
+    if (!testInfo)
+        return;
+    testInfo.annotations.push({ type: 'BugHunters Vision', description: `${status}: ${reason}` });
+    if (baselineFile) {
+        const p = path.join(resolvedDir, baselineFile);
+        if (fs.existsSync(p))
+            await testInfo.attach('bhv-baseline', { path: p, contentType: 'image/png' });
+    }
+    if (currentFile) {
+        const p = path.join(resolvedDir, currentFile);
+        if (fs.existsSync(p))
+            await testInfo.attach('bhv-current', { path: p, contentType: 'image/png' });
+    }
+}
+async function runVisionCheck(opts) {
+    const { page, name, prompt = 'Check for any visual regressions.', apiUrl, mode, snapshotsDir, updateBaseline, token, testInfo, } = opts;
+    // Mode: off → skip all visual testing immediately
+    if (mode === 'off') {
+        console.log(`\n⏭  [BugHunters Vision] "${name}" — skipped (BHV_MODE=off)\n`);
+        return;
+    }
+    const resolvedDir = path.resolve(process.cwd(), snapshotsDir);
+    fs.mkdirSync(resolvedDir, { recursive: true });
+    const baselineFile = path.join(resolvedDir, `${name}.baseline.png`);
+    const currentBuffer = await page.screenshot({ fullPage: false, type: 'png' });
+    if (!fs.existsSync(baselineFile) || updateBaseline) {
+        // First run — save as baseline
+        fs.writeFileSync(baselineFile, currentBuffer);
+        console.log(`\n📸 [BugHunters Vision] Baseline saved: ${baselineFile}`);
+        console.log('   ✅ Test PASSED (baseline created — no previous reference exists)\n');
+        (0, results_1.appendResult)(resolvedDir, {
+            testName: name,
+            status: 'BASELINE_CREATED',
+            reason: 'First run detected — screenshot saved as the new baseline.',
+            method: null,
+            baselineFile: `${name}.baseline.png`,
+            currentFile: null,
+            timestamp: new Date().toISOString(),
+        });
+        await pushToPlaywright(testInfo, 'BASELINE_CREATED', 'First run — screenshot saved as the new baseline.', resolvedDir, `${name}.baseline.png`, null);
+        return;
+    }
+    // Baseline exists — run Fast Pixel Match first to save AI credits
+    const baselineBuffer = fs.readFileSync(baselineFile);
+    const diffPixels = (0, pixel_match_1.fastPixelMatch)(baselineBuffer, currentBuffer);
+    const currentFileName = `${name}.current.png`;
+    fs.writeFileSync(path.join(resolvedDir, currentFileName), currentBuffer);
+    if (diffPixels === 0) {
+        // ✅ Pixel-perfect match — skip AI call entirely
+        console.log(`\n⚡ [BugHunters Vision] "${name}" — pixel-perfect match. Skipping AI call.`);
+        console.log('   ✅ Test PASSED (Fast Pixel Match)\n');
+        (0, results_1.appendResult)(resolvedDir, {
+            testName: name,
+            status: 'PASS',
+            reason: 'Identical (Fast Pixel Match) — pixel-perfect match, no AI evaluation needed.',
+            method: 'FAST_PIXEL_MATCH',
+            baselineFile: `${name}.baseline.png`,
+            currentFile: currentFileName,
+            timestamp: new Date().toISOString(),
+        });
+        await pushToPlaywright(testInfo, 'PASS', 'Pixel-perfect match — no AI evaluation needed.', resolvedDir, `${name}.baseline.png`, currentFileName);
+        return;
+    }
+    // Pixels differ — behaviour depends on mode
+    const diffLabel = diffPixels === -1 ? 'dimension mismatch' : `${diffPixels} pixel(s) differ`;
+    if (mode === 'strict') {
+        // strict: fail immediately without calling AI
+        console.log(`\n❌ [BugHunters Vision] "${name}" — ${diffLabel}. FAILED (strict mode — no AI call).\n`);
+        (0, results_1.appendResult)(resolvedDir, {
+            testName: name,
+            status: 'FAIL',
+            reason: `Pixel mismatch detected (${diffLabel}). Strict mode — AI evaluation disabled.`,
+            method: 'FAST_PIXEL_MATCH',
+            baselineFile: `${name}.baseline.png`,
+            currentFile: currentFileName,
+            timestamp: new Date().toISOString(),
+        });
+        await pushToPlaywright(testInfo, 'FAIL', `Pixel mismatch detected (${diffLabel}). Strict mode.`, resolvedDir, `${name}.baseline.png`, currentFileName);
+        (0, test_1.expect)(false, `[BugHunters Vision strict] Pixel mismatch: ${diffLabel}`).toBe(true);
+        return;
+    }
+    // ai mode — escalate to AI for intelligent evaluation
+    console.log(`\n🔍 [BugHunters Vision] "${name}" — ${diffLabel}. Sending to AI…`);
+    let result;
+    try {
+        result = await callVisionApi(baselineBuffer.toString('base64'), currentBuffer.toString('base64'), prompt, apiUrl, token);
+    }
+    catch (err) {
+        const reason = humanReadableApiError(err instanceof Error ? err.message : String(err));
+        console.log(`\n❌ [BugHunters Vision] ${reason}\n`);
+        (0, results_1.appendResult)(resolvedDir, {
+            testName: name,
+            status: 'FAIL',
+            reason,
+            method: 'AI',
+            baselineFile: `${name}.baseline.png`,
+            currentFile: currentFileName,
+            timestamp: new Date().toISOString(),
+        });
+        await pushToPlaywright(testInfo, 'FAIL', reason, resolvedDir, `${name}.baseline.png`, currentFileName);
+        throw err;
+    }
+    // ERROR: AI temporarily unavailable — record but do NOT fail the Playwright test
+    if (result.status === 'ERROR') {
+        console.log(`\n⚠️  [BugHunters Vision] "${name}" — AI unavailable: ${result.reason}\n`);
+        (0, results_1.appendResult)(resolvedDir, {
+            testName: name,
+            status: 'ERROR',
+            reason: result.reason,
+            method: 'AI',
+            baselineFile: `${name}.baseline.png`,
+            currentFile: currentFileName,
+            timestamp: new Date().toISOString(),
+        });
+        await pushToPlaywright(testInfo, 'ERROR', result.reason, resolvedDir, `${name}.baseline.png`, currentFileName);
+        return; // test stays green
+    }
+    const icon = result.status === 'PASS' ? '✅' : '❌';
+    console.log(`${icon} [BugHunters Vision] ${result.status}: ${result.reason}\n`);
+    (0, results_1.appendResult)(resolvedDir, {
+        testName: name,
+        status: result.status,
+        reason: result.reason,
+        method: 'AI',
+        baselineFile: `${name}.baseline.png`,
+        currentFile: currentFileName,
+        timestamp: new Date().toISOString(),
+    });
+    await pushToPlaywright(testInfo, result.status, result.reason, resolvedDir, `${name}.baseline.png`, currentFileName);
+    (0, test_1.expect)(result.status, `Visual regression detected: ${result.reason}`).toBe('PASS');
+}

package/dist/fixture.d.ts

@@ -0,0 +1,21 @@
+import { expect } from '@playwright/test';
+import type { VisionMode } from './types';
+export interface VisionFixtureOptions {
+    /** BugHunters Vision API URL (default: https://bugvision-backend.vercel.app) */
+    bvApiUrl: string;
+    /** Comparison mode: ai | strict | off (default: ai) */
+    bvMode: VisionMode;
+    /** Where to store baseline + current screenshots (default: ./bhv-snapshots) */
+    bvSnapshotsDir: string;
+    /** Force-overwrite all baselines on this run (default: false) */
+    bvUpdateBaseline: boolean;
+    /** BugHunters Vision API token (env: BUGHUNTERS_VISION_TOKEN) */
+    bvToken: string;
+}
+type VisionFixtures = {
+    /** Run a visual snapshot check for the current page state */
+    visionCheck: (name: string, prompt?: string) => Promise<void>;
+};
+export declare const test: import("@playwright/test").TestType<import("@playwright/test").PlaywrightTestArgs & import("@playwright/test").PlaywrightTestOptions & VisionFixtures & VisionFixtureOptions, import("@playwright/test").PlaywrightWorkerArgs & import("@playwright/test").PlaywrightWorkerOptions>;
+export { expect };
+//# sourceMappingURL=fixture.d.ts.map

package/dist/fixture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fixture.d.ts","sourceRoot":"","sources":["../src/fixture.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAExD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAK1C,MAAM,WAAW,oBAAoB;IACnC,gFAAgF;IAChF,QAAQ,EAAE,MAAM,CAAC;IACjB,uDAAuD;IACvD,MAAM,EAAE,UAAU,CAAC;IACnB,+EAA+E;IAC/E,cAAc,EAAE,MAAM,CAAC;IACvB,iEAAiE;IACjE,gBAAgB,EAAE,OAAO,CAAC;IAC1B,iEAAiE;IACjE,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,KAAK,cAAc,GAAG;IACpB,6DAA6D;IAC7D,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/D,CAAC;AAEF,eAAO,MAAM,IAAI,qRAoBf,CAAC;AAEH,OAAO,EAAE,MAAM,EAAE,CAAC"}

package/dist/fixture.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.expect = exports.test = void 0;
+const test_1 = require("@playwright/test");
+Object.defineProperty(exports, "expect", { enumerable: true, get: function () { return test_1.expect; } });
+const check_1 = require("./check");
+const PRODUCTION_API_URL = 'https://bugvision-backend.vercel.app';
+exports.test = test_1.test.extend({
+    bvApiUrl: [process.env.BUGHUNTERS_VISION_API_URL ?? process.env.BHV_API_URL ?? PRODUCTION_API_URL, { option: true }],
+    bvMode: [(process.env.BHV_MODE ?? 'ai'), { option: true }],
+    bvSnapshotsDir: [process.env.BHV_SNAPSHOTS_DIR ?? './bhv-snapshots', { option: true }],
+    bvUpdateBaseline: [process.env.BHV_UPDATE_BASELINE === 'true', { option: true }],
+    bvToken: [process.env.BUGHUNTERS_VISION_TOKEN ?? '', { option: true }],
+    visionCheck: async ({ page, bvApiUrl, bvMode, bvSnapshotsDir, bvUpdateBaseline, bvToken }, use, testInfo) => {
+        await use((name, prompt) => (0, check_1.runVisionCheck)({
+            page, name, prompt,
+            apiUrl: bvApiUrl,
+            mode: bvMode,
+            snapshotsDir: bvSnapshotsDir,
+            updateBaseline: bvUpdateBaseline,
+            token: bvToken || undefined,
+            testInfo,
+        }));
+    },
+});

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { test, expect } from './fixture';
+export type { VisionFixtureOptions } from './fixture';
+export type { VisionMode, TestResult, Meta } from './types';
+export { BugHuntersVisionReporter } from './reporter';
+export type { BugHuntersVisionReporterOptions } from './reporter';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACzC,YAAY,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AACtD,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAC5D,OAAO,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AACtD,YAAY,EAAE,+BAA+B,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BugHuntersVisionReporter = exports.expect = exports.test = void 0;
+var fixture_1 = require("./fixture");
+Object.defineProperty(exports, "test", { enumerable: true, get: function () { return fixture_1.test; } });
+Object.defineProperty(exports, "expect", { enumerable: true, get: function () { return fixture_1.expect; } });
+var reporter_1 = require("./reporter");
+Object.defineProperty(exports, "BugHuntersVisionReporter", { enumerable: true, get: function () { return reporter_1.BugHuntersVisionReporter; } });

package/dist/pixel-match.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Fast local pixel comparison — avoids AI API call when images are identical.
+ * Returns the number of differing pixels, or -1 if image dimensions differ.
+ */
+export declare function fastPixelMatch(baselineBuffer: Buffer, currentBuffer: Buffer): number;
+//# sourceMappingURL=pixel-match.d.ts.map

package/dist/pixel-match.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pixel-match.d.ts","sourceRoot":"","sources":["../src/pixel-match.ts"],"names":[],"mappings":"AAGA;;;GAGG;AACH,wBAAgB,cAAc,CAAC,cAAc,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM,CASpF"}

package/dist/pixel-match.js

@@ -0,0 +1,20 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fastPixelMatch = fastPixelMatch;
+const pngjs_1 = require("pngjs");
+const pixelmatch_1 = __importDefault(require("pixelmatch"));
+/**
+ * Fast local pixel comparison — avoids AI API call when images are identical.
+ * Returns the number of differing pixels, or -1 if image dimensions differ.
+ */
+function fastPixelMatch(baselineBuffer, currentBuffer) {
+    const imgA = pngjs_1.PNG.sync.read(baselineBuffer);
+    const imgB = pngjs_1.PNG.sync.read(currentBuffer);
+    if (imgA.width !== imgB.width || imgA.height !== imgB.height) {
+        return -1; // dimension mismatch — let AI handle it
+    }
+    return (0, pixelmatch_1.default)(imgA.data, imgB.data, null, imgA.width, imgA.height);
+}

package/dist/reporter.d.ts

@@ -0,0 +1,15 @@
+import type { Reporter } from '@playwright/test/reporter';
+export interface BugHuntersVisionReporterOptions {
+    snapshotsDir?: string;
+    reportDir?: string;
+}
+declare class BugHuntersVisionReporter implements Reporter {
+    private snapshotsDir;
+    private reportDir;
+    constructor(options?: BugHuntersVisionReporterOptions);
+    onBegin(): void;
+    onEnd(): void;
+}
+export default BugHuntersVisionReporter;
+export { BugHuntersVisionReporter };
+//# sourceMappingURL=reporter.d.ts.map

package/dist/reporter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reporter.d.ts","sourceRoot":"","sources":["../src/reporter.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAI1D,MAAM,WAAW,+BAA+B;IAC9C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AA87BD,cAAM,wBAAyB,YAAW,QAAQ;IAChD,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,SAAS,CAAS;gBAEd,OAAO,CAAC,EAAE,+BAA+B;IAKrD,OAAO,IAAI,IAAI;IAKf,KAAK,IAAI,IAAI;CA8Cd;AAED,eAAe,wBAAwB,CAAC;AACxC,OAAO,EAAE,wBAAwB,EAAE,CAAC"}