@pixeyedev/playwright 0.4.0

package/dist/browser.iife.js

@@ -0,0 +1,20 @@
+"use strict";var __pixeye=(()=>{var c=Object.defineProperty;var p=Object.getOwnPropertyDescriptor;var h=Object.getOwnPropertyNames;var f=Object.prototype.hasOwnProperty;var g=(e,t)=>{for(var o in t)c(e,o,{get:t[o],enumerable:!0})},b=(e,t,o,n)=>{if(t&&typeof t=="object"||typeof t=="function")for(let i of h(t))!f.call(e,i)&&i!==o&&c(e,i,{get:()=>t[i],enumerable:!(n=p(t,i))||n.enumerable});return e};var x=e=>b(c({},"__esModule",{value:!0}),e);var A={};g(A,{scanRegions:()=>l,stabilize:()=>m,waitForReady:()=>u});var S=[{selector:"[data-pixeye-mask]",type:"mask"},{selector:"[data-pixeye-ignore]",type:"ignore"},{selector:"[data-pixeye-dynamic]",type:"dynamic"},{selector:'[data-visual-test="blackout"]',type:"mask"},{selector:'[data-visual-test="removed"]',type:"ignore"},{selector:'[data-visual-test="transparent"]',type:"mask"},{selector:"[data-percy-ignore]",type:"ignore"},{selector:"[data-percy-mask]",type:"mask"},{selector:'[data-chromatic="ignore"]',type:"ignore"}],l=()=>{let e=[],t=new Set;for(let{selector:o,type:n}of S){let i=document.querySelectorAll(o);for(let a of i){if(t.has(a))continue;t.add(a);let r=a.getBoundingClientRect();r.width===0||r.height===0||e.push({type:n,selector:o,bounds:{x:Math.max(0,Math.round(r.x)),y:Math.max(0,Math.round(r.y)),width:Math.round(r.width),height:Math.round(r.height)}})}}return e};var d="__pixeye_stabilize",s=e=>{let t=document.getElementById(d);t||(t=document.createElement("style"),t.id=d,document.head.appendChild(t)),t.textContent+=e+`
+`},w=()=>{s(`
+    * {
+      -webkit-font-smoothing: antialiased !important;
+      -moz-osx-font-smoothing: grayscale !important;
+    }
+  `)},E=()=>{s(`
+    *, *::before, *::after {
+      animation-duration: 0s !important;
+      animation-delay: 0s !important;
+      transition-duration: 0s !important;
+      transition-delay: 0s !important;
+      scroll-behavior: auto !important;
+    }
+  `)},R=()=>{s(`
+    * { caret-color: transparent !important; }
+    ::-webkit-scrollbar { display: none !important; }
+    * { scrollbar-width: none !important; }
+  `),document.querySelectorAll("[contenteditable], textarea, input").forEach(e=>{e.setAttribute("spellcheck","false")})},v=()=>{document.querySelectorAll("img").forEach(e=>{let t=e.getBoundingClientRect(),o=Math.round(t.width),n=Math.round(t.height);(o!==t.width||n!==t.height)&&(e.style.width=`${o}px`,e.style.height=`${n}px`)})},T=()=>{document.querySelectorAll("*").forEach(e=>{let t=getComputedStyle(e);(t.position==="sticky"||t.position==="fixed")&&(e.style.position="absolute")})},m=(e={})=>{e.colorScheme&&(document.documentElement.style.colorScheme=e.colorScheme),e.fontAntialiasing!==!1&&w(),e.disableAnimations!==!1&&E(),e.hideNonDeterministic!==!1&&R(),e.roundImageSizes!==!1&&v(),e.stabilizeStickyFixed!==!1&&T(),e.css&&s(e.css)};var y=async(e,t,o)=>{let n=Date.now();for(;!e();){if(Date.now()-n>o)throw new Error(`[pixeye] waitForReady timed out waiting for: ${t}`);await new Promise(i=>setTimeout(i,100))}},u=async(e={})=>{let t=e.timeout??1e4,o=async()=>{await document.fonts.ready;let i=Array.from(document.querySelectorAll("img"));await Promise.all(i.filter(a=>!a.complete).map(a=>new Promise(r=>{a.addEventListener("load",()=>r(),{once:!0}),a.addEventListener("error",()=>r(),{once:!0})}))),await y(()=>!document.querySelector('[aria-busy="true"]'),'aria-busy="true" elements to clear',t),await y(()=>!document.querySelector("[data-pixeye-loading]"),"data-pixeye-loading elements to disappear",t)},n=new Promise((i,a)=>{setTimeout(()=>a(new Error(`[pixeye] waitForReady timed out after ${t}ms`)),t)});await Promise.race([o(),n])};return x(A);})();
+if(typeof window!=="undefined")window.__pixeye=__pixeye;

package/dist/codemods/from-argos.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Transform Argos CI code to Pixeye.
+ * Usage: import and call transformArgos(sourceCode) -> transformed code
+ *
+ * Handles:
+ * - import { argosScreenshot } from '@argos-ci/playwright' -> import { pixeye } from '@pixeyedev/playwright'
+ * - argosScreenshot(page, name, opts) -> pixeye.screenshot(page, name, opts)
+ * - { argosCSS: '...' } -> { css: '...' }
+ */
+export declare const transformArgos: (source: string) => string;

package/dist/codemods/from-argos.js

@@ -0,0 +1,19 @@
+/**
+ * Transform Argos CI code to Pixeye.
+ * Usage: import and call transformArgos(sourceCode) -> transformed code
+ *
+ * Handles:
+ * - import { argosScreenshot } from '@argos-ci/playwright' -> import { pixeye } from '@pixeyedev/playwright'
+ * - argosScreenshot(page, name, opts) -> pixeye.screenshot(page, name, opts)
+ * - { argosCSS: '...' } -> { css: '...' }
+ */
+export const transformArgos = (source) => {
+    let result = source;
+    // 1. Transform import
+    result = result.replace(/import\s*\{\s*argosScreenshot\s*\}\s*from\s*['"]@argos-ci\/playwright['"]/g, "import { pixeye } from '@pixeyedev/playwright'");
+    // 2. Transform function calls
+    result = result.replace(/argosScreenshot\s*\(/g, 'pixeye.screenshot(');
+    // 3. Transform option names
+    result = result.replace(/argosCSS\s*:/g, 'css:');
+    return result;
+};

package/dist/codemods/from-percy.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Transform Percy code to Pixeye.
+ * Usage: import and call transformPercy(sourceCode) -> transformed code
+ *
+ * Handles:
+ * - import percySnapshot from '@percy/playwright' -> import { pixeye } from '@pixeyedev/playwright'
+ * - percySnapshot(page, name, opts) -> pixeye.screenshot(page, name, opts)
+ * - { percyCSS: '...' } -> { css: '...' }
+ */
+export declare const transformPercy: (source: string) => string;

package/dist/codemods/from-percy.js

@@ -0,0 +1,19 @@
+/**
+ * Transform Percy code to Pixeye.
+ * Usage: import and call transformPercy(sourceCode) -> transformed code
+ *
+ * Handles:
+ * - import percySnapshot from '@percy/playwright' -> import { pixeye } from '@pixeyedev/playwright'
+ * - percySnapshot(page, name, opts) -> pixeye.screenshot(page, name, opts)
+ * - { percyCSS: '...' } -> { css: '...' }
+ */
+export const transformPercy = (source) => {
+    let result = source;
+    // 1. Transform import (default import)
+    result = result.replace(/import\s+percySnapshot\s+from\s*['"]@percy\/playwright['"]/g, "import { pixeye } from '@pixeyedev/playwright'");
+    // 2. Transform function calls
+    result = result.replace(/percySnapshot\s*\(/g, 'pixeye.screenshot(');
+    // 3. Transform option names
+    result = result.replace(/percyCSS\s*:/g, 'css:');
+    return result;
+};

package/dist/codemods/index.d.ts

@@ -0,0 +1,2 @@
+export { transformArgos } from './from-argos.js';
+export { transformPercy } from './from-percy.js';

package/dist/codemods/index.js

@@ -0,0 +1,2 @@
+export { transformArgos } from './from-argos.js';
+export { transformPercy } from './from-percy.js';

package/dist/fixture.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Playwright test fixture that provides `pixeye` in every test.
+ *
+ * Usage:
+ *   import { test, expect } from '@pixeyedev/playwright';
+ *
+ *   test('login page', async ({ page, pixeye }) => {
+ *     await page.goto('/login');
+ *     await pixeye.screenshot(page, 'login-page');
+ *   });
+ *
+ * The fixture automatically populates testFile and testName from
+ * Playwright's testInfo, so metadata is always accurate.
+ */
+import { expect } from '@playwright/test';
+import { screenshot, type ScreenshotOptions } from './screenshot.js';
+export interface PixeyeFixture {
+    screenshot: (target: Parameters<typeof screenshot>[0], name: string, options?: ScreenshotOptions) => Promise<string>;
+}
+export declare const test: import("playwright/test").TestType<import("playwright/test").PlaywrightTestArgs & import("playwright/test").PlaywrightTestOptions & {
+    pixeye: PixeyeFixture;
+}, import("playwright/test").PlaywrightWorkerArgs & import("playwright/test").PlaywrightWorkerOptions>;
+export { expect };

package/dist/fixture.js

@@ -0,0 +1,34 @@
+/**
+ * Playwright test fixture that provides `pixeye` in every test.
+ *
+ * Usage:
+ *   import { test, expect } from '@pixeyedev/playwright';
+ *
+ *   test('login page', async ({ page, pixeye }) => {
+ *     await page.goto('/login');
+ *     await pixeye.screenshot(page, 'login-page');
+ *   });
+ *
+ * The fixture automatically populates testFile and testName from
+ * Playwright's testInfo, so metadata is always accurate.
+ */
+import { join } from 'node:path';
+import { expect, test as base } from '@playwright/test';
+import { screenshot, setContext } from './screenshot.js';
+export const test = base.extend({
+    // eslint-disable-next-line no-empty-pattern
+    pixeye: async ({}, use, testInfo) => {
+        const outputDir = join(process.cwd(), '.pixeye', 'screenshots');
+        const testFile = testInfo.file ? testInfo.file.replace(process.cwd() + '/', '') : 'unknown';
+        setContext({
+            outputDir,
+            testFile,
+            testName: testInfo.title
+        });
+        const pixeyeApi = {
+            screenshot: (target, name, options) => screenshot(target, name, options)
+        };
+        await use(pixeyeApi);
+    }
+});
+export { expect };

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export type { PixeyeFixture } from './fixture.js';
+export { expect, test } from './fixture.js';
+export type { ScreenshotContext, ScreenshotOptions } from './screenshot.js';
+export { getContext, PIXEYE_BROWSER_ARGS, screenshot, setContext } from './screenshot.js';
+export declare const pixeye: {
+    screenshot: (target: import("playwright-core").Page | import("playwright-core").Locator, name: string, options?: import("./screenshot.js").ScreenshotOptions) => Promise<string>;
+};

package/dist/index.js

@@ -0,0 +1,5 @@
+export { expect, test } from './fixture.js';
+export { getContext, PIXEYE_BROWSER_ARGS, screenshot, setContext } from './screenshot.js';
+// ── Convenience namespace (backwards compat with design docs) ───────────────
+import { screenshot as screenshotFn } from './screenshot.js';
+export const pixeye = { screenshot: screenshotFn };

package/dist/reporter.d.ts

@@ -0,0 +1,22 @@
+import type { FullConfig, FullResult, Reporter, Suite, TestCase, TestResult } from '@playwright/test/reporter';
+interface ReporterOptions {
+    token?: string;
+    server?: string;
+    uploadConcurrency?: number;
+}
+declare const detectShard: (config: FullConfig) => {
+    index: number;
+    total: number;
+};
+declare class PixeyeReporter implements Reporter {
+    private options;
+    private shard;
+    private skipUpload;
+    constructor(options?: ReporterOptions);
+    onBegin(config: FullConfig, _suite: Suite): void;
+    onTestEnd(_test: TestCase, _result: TestResult): void;
+    onEnd(_result: FullResult): Promise<void>;
+}
+export default PixeyeReporter;
+export { detectShard };
+export type { ReporterOptions };

package/dist/reporter.js

@@ -0,0 +1,164 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { detectCIEnvironment, discoverScreenshots, PixeyeClient, PixeyeError, runParallel } from '@pixeyedev/core';
+import { getContext } from './screenshot.js';
+const DEFAULT_UPLOAD_CONCURRENCY = 32;
+const detectShard = (config) => {
+    // 1. Playwright config (1-indexed → 0-indexed)
+    if (config.shard) {
+        return { index: config.shard.current - 1, total: config.shard.total };
+    }
+    // 2. Environment variables (0-indexed)
+    const envIndex = process.env.PIXEYE_SHARD_INDEX;
+    const envTotal = process.env.PIXEYE_SHARD_TOTAL;
+    if (envIndex !== undefined) {
+        return {
+            index: parseInt(envIndex, 10),
+            total: envTotal ? parseInt(envTotal, 10) : 1
+        };
+    }
+    // 3. Default: no sharding
+    return { index: 0, total: 1 };
+};
+const detectRunner = () => {
+    return 'playwright';
+};
+class PixeyeReporter {
+    options;
+    shard = { index: 0, total: 1 };
+    skipUpload = false;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    onBegin(config, _suite) {
+        const token = this.options.token ?? process.env.PIXEYE_TOKEN;
+        if (!token) {
+            console.warn('[pixeye] No PIXEYE_TOKEN found. Skipping upload. Screenshots will still be captured.');
+            this.skipUpload = true;
+            return;
+        }
+        this.shard = detectShard(config);
+    }
+    onTestEnd(_test, _result) {
+        // Screenshots are already saved to disk by pixeye.screenshot().
+        // Nothing to do per-test.
+    }
+    async onEnd(_result) {
+        if (this.skipUpload) {
+            return;
+        }
+        const token = this.options.token ?? process.env.PIXEYE_TOKEN;
+        const server = this.options.server ?? process.env.PIXEYE_SERVER ?? 'https://pixeye.dev';
+        if (!token) {
+            return;
+        }
+        // Discover screenshots saved by pixeye.screenshot()
+        const ctx = getContext();
+        const outputDir = ctx?.outputDir ?? join(process.cwd(), '.pixeye', 'screenshots');
+        let files;
+        try {
+            files = await discoverScreenshots(outputDir);
+        }
+        catch {
+            console.log('[pixeye] No screenshots found. Nothing to upload.');
+            return;
+        }
+        if (files.length === 0) {
+            console.log('[pixeye] No screenshots captured. Nothing to upload.');
+            return;
+        }
+        const ci = detectCIEnvironment();
+        const commitSha = process.env.PIXEYE_COMMIT ?? ci?.commit;
+        const branch = process.env.PIXEYE_BRANCH ?? ci?.branch;
+        if (!commitSha || !branch) {
+            console.warn('[pixeye] Could not detect commit SHA or branch. Skipping upload.');
+            console.warn('[pixeye] Set PIXEYE_COMMIT and PIXEYE_BRANCH, or run in CI (GitHub Actions / GitLab CI).');
+            return;
+        }
+        const runner = detectRunner();
+        const concurrency = this.options.uploadConcurrency ?? DEFAULT_UPLOAD_CONCURRENCY;
+        try {
+            const client = new PixeyeClient({ serverUrl: server, token });
+            // 1. Create build
+            const prNumber = process.env.PIXEYE_PR ? parseInt(process.env.PIXEYE_PR, 10) : ci?.prNumber;
+            const buildResponse = await client.createBuild({
+                projectToken: token,
+                commitSha,
+                branch,
+                prNumber: prNumber && !isNaN(prNumber) ? prNumber : undefined,
+                shardCount: this.shard.total,
+                runner,
+                baseBranch: ci?.baseBranch
+            });
+            const buildId = buildResponse.build.id;
+            // 2. Presign upload URLs
+            const hashes = files.map(f => f.fileHash);
+            const formats = Object.fromEntries(files.filter(f => f.format === 'webp').map(f => [f.fileHash, 'webp']));
+            const presign = await client.presignUpload({
+                buildId,
+                hashes,
+                ...(Object.keys(formats).length > 0 ? { formats } : {})
+            });
+            if (presign.warnings.length > 0) {
+                for (const w of presign.warnings) {
+                    console.warn(`[pixeye] ${w}`);
+                }
+            }
+            // 3. Upload new files
+            const hashUrlPairs = Object.entries(presign.urls);
+            const hashToFile = new Map(files.map(f => [f.fileHash, f]));
+            let uploaded = 0;
+            if (hashUrlPairs.length > 0) {
+                await runParallel(hashUrlPairs, concurrency, async ([hash, url]) => {
+                    const file = hashToFile.get(hash);
+                    if (!file) {
+                        return;
+                    }
+                    const buffer = await readFile(file.filePath);
+                    const contentType = file.format === 'webp' ? 'image/webp' : 'image/png';
+                    await client.uploadFile(url, buffer, contentType);
+                    uploaded++;
+                });
+            }
+            // 4. Read metadata sidecars and build manifest
+            const manifest = await Promise.all(files.map(async (f) => {
+                // Try to read companion .meta.json
+                const metaPath = f.filePath.replace(/\.(png|webp)$/, '.meta.json');
+                let metadata;
+                try {
+                    const metaContent = await readFile(metaPath, 'utf-8');
+                    metadata = JSON.parse(metaContent);
+                }
+                catch {
+                    // No sidecar — that's fine
+                }
+                return {
+                    name: f.name,
+                    fileHash: f.fileHash,
+                    format: f.format,
+                    width: f.width,
+                    height: f.height,
+                    metadata
+                };
+            }));
+            // 5. Submit shard
+            await client.submitShard({
+                buildId,
+                shardIndex: this.shard.index,
+                screenshots: manifest
+            });
+            console.log(`[pixeye] ${files.length} screenshots (${uploaded} new, ${presign.existing.length} cached) — ${server}/builds/${buildId}`);
+        }
+        catch (err) {
+            // Upload failure should NOT fail the test run
+            if (err instanceof PixeyeError) {
+                console.warn(`[pixeye] Upload failed (${err.status}): ${err.message}`);
+            }
+            else {
+                console.warn(`[pixeye] Upload failed: ${err.message}`);
+            }
+        }
+    }
+}
+export default PixeyeReporter;
+export { detectShard };

package/dist/screenshot.d.ts

@@ -0,0 +1,33 @@
+import type { Locator, Page } from '@playwright/test';
+/** Browser args recommended for deterministic screenshots. */
+export declare const PIXEYE_BROWSER_ARGS: string[];
+export interface ScreenshotOptions {
+    fullPage?: boolean;
+    clip?: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+    mask?: (string | Locator)[];
+    ignore?: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    }[];
+    css?: string;
+    waitFor?: string;
+    waitForTimeout?: number;
+    retries?: number;
+    threshold?: number;
+    colorScheme?: 'light' | 'dark';
+}
+export interface ScreenshotContext {
+    outputDir: string;
+    testFile: string;
+    testName: string;
+}
+export declare const setContext: (ctx: ScreenshotContext) => void;
+export declare const getContext: () => ScreenshotContext | null;
+export declare const screenshot: (target: Page | Locator, name: string, options?: ScreenshotOptions) => Promise<string>;

package/dist/screenshot.js

@@ -0,0 +1,211 @@
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** Browser args recommended for deterministic screenshots. */
+export const PIXEYE_BROWSER_ARGS = [
+    '--force-device-scale-factor=1',
+    '--font-render-hinting=none',
+    '--disable-lcd-text'
+];
+// Shared context set by the reporter or test setup
+let _context = null;
+export const setContext = (ctx) => {
+    _context = ctx;
+};
+export const getContext = () => _context;
+// ── IIFE loader ──────────────────────────────────────────────────────────────
+// The browser IIFE is copied into dist/ at build time (see package.json build script).
+// This avoids a runtime dependency on @pixeyedev/browser, which is private/internal.
+const THIS_DIR = dirname(fileURLToPath(import.meta.url));
+let _iifeCache = null;
+const loadIIFE = async () => {
+    if (_iifeCache) {
+        return _iifeCache;
+    }
+    _iifeCache = await readFile(join(THIS_DIR, 'browser.iife.js'), 'utf-8');
+    return _iifeCache;
+};
+// ── Helpers ──────────────────────────────────────────────────────────────────
+const injectBrowserScripts = async (page) => {
+    const iife = await loadIIFE();
+    // Check if already injected to avoid double-injection
+    const alreadyInjected = await page.evaluate(
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    () => typeof window.__pixeye !== 'undefined');
+    if (!alreadyInjected) {
+        await page.evaluate(iife);
+    }
+};
+const getPage = (target) => {
+    if ('page' in target && typeof target.page === 'function') {
+        return target.page();
+    }
+    return target;
+};
+const isLocator = (target) => {
+    return 'page' in target && typeof target.page === 'function';
+};
+const sanitizePath = (str) => {
+    return str.replace(/[^a-zA-Z0-9._/-]/g, '_');
+};
+// ── Mask resolution ──────────────────────────────────────────────────────────
+const resolveMaskRegions = async (page, masks) => {
+    const regions = [];
+    for (const selectorOrLocator of masks) {
+        if (typeof selectorOrLocator === 'string') {
+            const bounds = await page.evaluate((sel) => {
+                const el = document.querySelector(sel);
+                if (!el) {
+                    return null;
+                }
+                const rect = el.getBoundingClientRect();
+                return {
+                    x: Math.max(0, Math.round(rect.x)),
+                    y: Math.max(0, Math.round(rect.y)),
+                    width: Math.round(rect.width),
+                    height: Math.round(rect.height)
+                };
+            }, selectorOrLocator);
+            if (bounds && bounds.width > 0 && bounds.height > 0) {
+                regions.push({ type: 'mask', selector: selectorOrLocator, bounds });
+            }
+        }
+        else {
+            // Locator
+            const box = await selectorOrLocator.boundingBox();
+            if (box) {
+                regions.push({
+                    type: 'mask',
+                    selector: String(selectorOrLocator),
+                    bounds: {
+                        x: Math.max(0, Math.round(box.x)),
+                        y: Math.max(0, Math.round(box.y)),
+                        width: Math.round(box.width),
+                        height: Math.round(box.height)
+                    }
+                });
+            }
+        }
+    }
+    return regions;
+};
+// ── Capture with retry ───────────────────────────────────────────────────────
+const RETRY_DELAY_MS = 100;
+const captureOnce = async (target, options) => {
+    const screenshotOpts = {};
+    if (options.fullPage) {
+        screenshotOpts.fullPage = true;
+    }
+    if (options.clip) {
+        screenshotOpts.clip = {
+            x: options.clip.x,
+            y: options.clip.y,
+            width: options.clip.w,
+            height: options.clip.h
+        };
+    }
+    if (isLocator(target)) {
+        return (await target.screenshot(screenshotOpts));
+    }
+    return (await target.screenshot(screenshotOpts));
+};
+const captureStable = async (target, options) => {
+    const retries = options.retries ?? 0;
+    if (retries <= 0) {
+        return captureOnce(target, options);
+    }
+    // Capture retries+1 times, find first consecutive duplicate (stable frame)
+    const captures = [];
+    const page = getPage(target);
+    for (let i = 0; i <= retries; i++) {
+        captures.push(await captureOnce(target, options));
+        if (i < retries) {
+            await page.waitForTimeout(RETRY_DELAY_MS);
+        }
+    }
+    const hashes = captures.map(b => createHash('sha256').update(b).digest('hex'));
+    for (let i = 1; i < hashes.length; i++) {
+        if (hashes[i] === hashes[i - 1]) {
+            return captures[i];
+        }
+    }
+    // No stable frame found — return the last capture
+    return captures[captures.length - 1];
+};
+// ── Main screenshot function ─────────────────────────────────────────────────
+export const screenshot = async (target, name, options = {}) => {
+    const page = getPage(target);
+    // Determine output directory
+    const outputDir = _context?.outputDir ?? join(process.cwd(), '.pixeye', 'screenshots');
+    const testFile = _context?.testFile ?? 'unknown';
+    const testName = _context?.testName ?? '';
+    const sanitizedTestFile = sanitizePath(testFile);
+    const dir = join(outputDir, sanitizedTestFile);
+    await mkdir(dir, { recursive: true });
+    const pngPath = join(dir, `${name}.png`);
+    const metaPath = join(dir, `${name}.meta.json`);
+    // 1. Inject browser scripts
+    await injectBrowserScripts(page);
+    // 2. Stabilize the page
+    await page.evaluate((opts) => {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        window.__pixeye.stabilize({
+            css: opts.css,
+            colorScheme: opts.colorScheme
+        });
+    }, { css: options.css, colorScheme: options.colorScheme });
+    // 3. Wait for page to be ready
+    await page.evaluate((timeout) => {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        return window.__pixeye.waitForReady({ timeout });
+    }, options.waitForTimeout ?? 10_000);
+    // 4. Custom waitFor selector
+    if (options.waitFor) {
+        await page.waitForSelector(options.waitFor, {
+            timeout: options.waitForTimeout ?? 10_000
+        });
+    }
+    // 5. Scan DOM for region attributes
+    const scannedRegions = await page.evaluate(() => {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        return window.__pixeye.scanRegions();
+    });
+    // 6. Resolve mask selectors/locators to region bounds
+    const maskRegions = options.mask ? await resolveMaskRegions(page, options.mask) : [];
+    const allRegions = [...scannedRegions, ...maskRegions];
+    // 7. Capture screenshot (with optional retry for stability)
+    const buffer = await captureStable(target, options);
+    // 8. Get component bounds for element-level screenshots
+    let componentBounds = null;
+    if (isLocator(target)) {
+        const box = await target.boundingBox();
+        if (box) {
+            componentBounds = {
+                x: Math.round(box.x),
+                y: Math.round(box.y),
+                width: Math.round(box.width),
+                height: Math.round(box.height)
+            };
+        }
+    }
+    // 9. Gather viewport + browser info
+    const viewportSize = page.viewportSize();
+    const browserName = page.context().browser()?.browserType().name() ?? 'unknown';
+    // 10. Build metadata sidecar
+    const metadata = {
+        version: 1,
+        viewport: viewportSize ? { width: viewportSize.width, height: viewportSize.height } : undefined,
+        browser: browserName,
+        colorScheme: options.colorScheme,
+        testFile,
+        testName,
+        threshold: options.threshold,
+        regions: allRegions.length > 0 ? allRegions : undefined,
+        componentBounds
+    };
+    // 11. Write .png and .meta.json
+    await writeFile(pngPath, buffer);
+    await writeFile(metaPath, JSON.stringify(metadata, null, 2) + '\n');
+    return pngPath;
+};

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@pixeyedev/playwright",
+  "version": "0.4.0",
+  "private": false,
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./dist/index.js"
+    },
+    "./reporter": {
+      "types": "./src/reporter.ts",
+      "import": "./dist/reporter.js"
+    },
+    "./codemods": {
+      "types": "./src/codemods/index.ts",
+      "import": "./dist/codemods/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc && cp ../browser/dist/browser.iife.js dist/browser.iife.js",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "lint": "echo 'ok'",
+    "ai-check": "exit 0"
+  },
+  "dependencies": {
+    "@pixeyedev/core": "^0.4.0",
+    "@pixeyedev/shared": "^0.4.0"
+  },
+  "peerDependencies": {
+    "@playwright/test": ">=1.40.0"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.58.2",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  }
+}