difflens-cli 1.0.0

package/dist/report-builder.js

@@ -0,0 +1,66 @@
+export function buildReport(diff) {
+    const { percentChanged, dimensions, regions, diffImagePath, overlayImagePath } = diff;
+    let status;
+    if (percentChanged === 0) {
+        status = 'no_changes';
+    }
+    else if (percentChanged < 1) {
+        status = 'minor';
+    }
+    else if (percentChanged < 10) {
+        status = 'significant';
+    }
+    else {
+        status = 'major';
+    }
+    // Build human-readable summary
+    const parts = [];
+    parts.push(`${status.replace('_', ' ').toUpperCase()}: ${percentChanged.toFixed(2)}% pixels changed.`);
+    if (dimensions.resized) {
+        parts.push(`Page dimensions changed from ${dimensions.before.width}x${dimensions.before.height} ` +
+            `to ${dimensions.after.width}x${dimensions.after.height}.`);
+    }
+    if (regions.length > 0) {
+        parts.push(`${regions.length} changed region(s) detected:`);
+        const topRegions = regions.slice(0, 5);
+        for (let i = 0; i < topRegions.length; i++) {
+            const r = topRegions[i];
+            parts.push(`  ${i + 1}. ${r.description} — ${r.changedPixels} pixels (${r.percentChanged.toFixed(1)}% of region)`);
+        }
+        if (regions.length > 5) {
+            parts.push(`  ... and ${regions.length - 5} more region(s)`);
+        }
+    }
+    return {
+        status,
+        summary: parts.join('\n'),
+        percentChanged,
+        dimensions,
+        regions,
+        diffImagePath,
+        overlayImagePath,
+    };
+}
+export function buildResponsiveReport(url, viewportResults) {
+    const parts = [`Responsive check for ${url} across ${viewportResults.length} viewport(s):\n`];
+    for (const { viewport, report } of viewportResults) {
+        parts.push(`--- ${viewport.width}x${viewport.height} ---`);
+        parts.push(report.summary);
+        parts.push('');
+    }
+    // Highlight cross-viewport differences
+    const statuses = viewportResults.map(v => v.report.status);
+    const uniqueStatuses = new Set(statuses);
+    if (uniqueStatuses.size > 1) {
+        parts.push('NOTE: Different viewports show different levels of change:');
+        for (const { viewport, report } of viewportResults) {
+            parts.push(`  ${viewport.width}px: ${report.status} (${report.percentChanged.toFixed(2)}%)`);
+        }
+    }
+    return {
+        url,
+        viewports: viewportResults,
+        summary: parts.join('\n'),
+    };
+}
+//# sourceMappingURL=report-builder.js.map

package/dist/report-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"report-builder.js","sourceRoot":"","sources":["../src/report-builder.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,WAAW,CAAC,IAAgB;IAC1C,MAAM,EAAE,cAAc,EAAE,UAAU,EAAE,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,GAAG,IAAI,CAAC;IAEtF,IAAI,MAA4B,CAAC;IACjC,IAAI,cAAc,KAAK,CAAC,EAAE,CAAC;QACzB,MAAM,GAAG,YAAY,CAAC;IACxB,CAAC;SAAM,IAAI,cAAc,GAAG,CAAC,EAAE,CAAC;QAC9B,MAAM,GAAG,OAAO,CAAC;IACnB,CAAC;SAAM,IAAI,cAAc,GAAG,EAAE,EAAE,CAAC;QAC/B,MAAM,GAAG,aAAa,CAAC;IACzB,CAAC;SAAM,CAAC;QACN,MAAM,GAAG,OAAO,CAAC;IACnB,CAAC;IAED,+BAA+B;IAC/B,MAAM,KAAK,GAAa,EAAE,CAAC;IAE3B,KAAK,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,WAAW,EAAE,KAAK,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC;IAEvG,IAAI,UAAU,CAAC,OAAO,EAAE,CAAC;QACvB,KAAK,CAAC,IAAI,CACR,gCAAgC,UAAU,CAAC,MAAM,CAAC,KAAK,IAAI,UAAU,CAAC,MAAM,CAAC,MAAM,GAAG;YACtF,MAAM,UAAU,CAAC,KAAK,CAAC,KAAK,IAAI,UAAU,CAAC,KAAK,CAAC,MAAM,GAAG,CAC3D,CAAC;IACJ,CAAC;IAED,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,KAAK,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,MAAM,8BAA8B,CAAC,CAAC;QAC5D,MAAM,UAAU,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QACvC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,UAAU,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YAC3C,MAAM,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC;YACxB,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,WAAW,MAAM,CAAC,CAAC,aAAa,YAAY,CAAC,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC;QACrH,CAAC;QACD,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACvB,KAAK,CAAC,IAAI,CAAC,aAAa,OAAO,CAAC,MAAM,GAAG,CAAC,iBAAiB,CAAC,CAAC;QAC/D,CAAC;IACH,CAAC;IAED,OAAO;QACL,MAAM;QACN,OAAO,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC;QACzB,cAAc;QACd,UAAU;QACV,OAAO;QACP,aAAa;QACb,gBAAgB;KACjB,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,qBAAqB,CACnC,GAAW,EACX,eAAkE;IAElE,MAAM,KAAK,GAAa,CAAC,wBAAwB,GAAG,WAAW,eAAe,CAAC,MAAM,iBAAiB,CAAC,CAAC;IAExG,KAAK,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,eAAe,EAAE,CAAC;QACnD,KAAK,CAAC,IAAI,CAAC,OAAO,QAAQ,CAAC,KAAK,IAAI,QAAQ,CAAC,MAAM,MAAM,CAAC,CAAC;QAC3D,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAC3B,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACjB,CAAC;IAED,uCAAuC;IACvC,MAAM,QAAQ,GAAG,eAAe,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC3D,MAAM,cAAc,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,CAAC;IACzC,IAAI,cAAc,CAAC,IAAI,GAAG,CAAC,EAAE,CAAC;QAC5B,KAAK,CAAC,IAAI,CAAC,4DAA4D,CAAC,CAAC;QACzE,KAAK,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,eAAe,EAAE,CAAC;YACnD,KAAK,CAAC,IAAI,CAAC,KAAK,QAAQ,CAAC,KAAK,OAAO,MAAM,CAAC,MAAM,KAAK,MAAM,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QAC/F,CAAC;IACH,CAAC;IAED,OAAO;QACL,GAAG;QACH,SAAS,EAAE,eAAe;QAC1B,OAAO,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC;KAC1B,CAAC;AACJ,CAAC"}

package/dist/screenshotter.d.ts

@@ -0,0 +1,4 @@
+import type { ScreenshotOptions, Viewport } from './types.js';
+export declare function takeScreenshot(options: ScreenshotOptions): Promise<Buffer>;
+export declare function takeElementScreenshot(url: string, selector: string, viewport?: Viewport, waitForSelector?: string, waitForTimeout?: number): Promise<Buffer>;
+export declare function closeBrowser(): Promise<void>;

package/dist/screenshotter.js

@@ -0,0 +1,142 @@
+import { chromium } from 'playwright';
+import { DiffLensError } from './types.js';
+const log = (msg) => process.stderr.write(`[difflens] ${msg}\n`);
+let browserInstance = null;
+let launchPromise = null;
+const ANTI_ANIMATION_CSS = `
+*, *::before, *::after {
+  animation-duration: 0s !important;
+  animation-delay: 0s !important;
+  transition-duration: 0s !important;
+  transition-delay: 0s !important;
+  caret-color: transparent !important;
+  scroll-behavior: auto !important;
+}
+`;
+async function ensureBrowser() {
+    if (browserInstance?.isConnected())
+        return browserInstance;
+    // Guard against duplicate launches from concurrent calls
+    if (launchPromise)
+        return launchPromise;
+    launchPromise = chromium.launch({
+        headless: true,
+        args: ['--disable-gpu', '--hide-scrollbars', '--no-sandbox'],
+    });
+    try {
+        browserInstance = await launchPromise;
+        log('Browser launched');
+        browserInstance.on('disconnected', () => {
+            browserInstance = null;
+            launchPromise = null;
+            log('Browser disconnected');
+        });
+        return browserInstance;
+    }
+    catch (err) {
+        launchPromise = null;
+        throw new DiffLensError('BROWSER_ERROR', `Failed to launch browser: ${err}`);
+    }
+}
+async function createContext(viewport) {
+    const browser = await ensureBrowser();
+    return browser.newContext({
+        viewport: { width: viewport.width, height: viewport.height },
+        locale: 'en-US',
+        timezoneId: 'UTC',
+        reducedMotion: 'reduce',
+        deviceScaleFactor: 1,
+    });
+}
+async function navigateAndPrepare(page, url, options) {
+    try {
+        await page.goto(url, { waitUntil: 'networkidle', timeout: 30_000 });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (message.includes('ECONNREFUSED') || message.includes('ERR_CONNECTION_REFUSED')) {
+            throw new DiffLensError('CONNECTION_REFUSED', `Cannot connect to ${url}. Is the dev server running?`);
+        }
+        if (message.includes('Timeout') || message.includes('timeout')) {
+            throw new DiffLensError('TIMEOUT', `Page load timed out after 30s for ${url}`);
+        }
+        throw new DiffLensError('BROWSER_ERROR', `Navigation failed: ${message}`);
+    }
+    if (options.waitForSelector) {
+        try {
+            await page.waitForSelector(options.waitForSelector, { timeout: 10_000 });
+        }
+        catch {
+            throw new DiffLensError('SELECTOR_NOT_FOUND', `Selector "${options.waitForSelector}" not found within 10s`);
+        }
+    }
+    if (options.waitForTimeout) {
+        await page.waitForTimeout(options.waitForTimeout);
+    }
+}
+export async function takeScreenshot(options) {
+    const viewport = options.viewport ?? { width: 1280, height: 720 };
+    const fullPage = options.fullPage ?? true;
+    log(`Screenshot: ${options.url} @ ${viewport.width}x${viewport.height}`);
+    const context = await createContext(viewport);
+    try {
+        const page = await context.newPage();
+        // Inject anti-animation CSS before any page JS runs
+        await page.addInitScript(`{
+      const style = document.createElement('style');
+      style.textContent = ${JSON.stringify(ANTI_ANIMATION_CSS)};
+      if (document.head) {
+        document.head.appendChild(style);
+      } else {
+        document.addEventListener('DOMContentLoaded', () => document.head.appendChild(style));
+      }
+    }`);
+        await navigateAndPrepare(page, options.url, options);
+        const buffer = await page.screenshot({
+            fullPage,
+            type: 'png',
+            animations: 'disabled',
+        });
+        return Buffer.from(buffer);
+    }
+    finally {
+        await context.close();
+    }
+}
+export async function takeElementScreenshot(url, selector, viewport, waitForSelector, waitForTimeout) {
+    const vp = viewport ?? { width: 1280, height: 720 };
+    log(`Element screenshot: ${selector} @ ${url}`);
+    const context = await createContext(vp);
+    try {
+        const page = await context.newPage();
+        await page.addInitScript(`{
+      const style = document.createElement('style');
+      style.textContent = ${JSON.stringify(ANTI_ANIMATION_CSS)};
+      if (document.head) {
+        document.head.appendChild(style);
+      } else {
+        document.addEventListener('DOMContentLoaded', () => document.head.appendChild(style));
+      }
+    }`);
+        await navigateAndPrepare(page, url, { waitForSelector, waitForTimeout });
+        const locator = page.locator(selector);
+        const count = await locator.count();
+        if (count === 0) {
+            throw new DiffLensError('SELECTOR_NOT_FOUND', `Element "${selector}" not found on page`);
+        }
+        const buffer = await locator.first().screenshot({ type: 'png', animations: 'disabled' });
+        return Buffer.from(buffer);
+    }
+    finally {
+        await context.close();
+    }
+}
+export async function closeBrowser() {
+    if (browserInstance?.isConnected()) {
+        await browserInstance.close();
+        log('Browser closed');
+    }
+    browserInstance = null;
+    launchPromise = null;
+}
+//# sourceMappingURL=screenshotter.js.map

package/dist/screenshotter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"screenshotter.js","sourceRoot":"","sources":["../src/screenshotter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAgD,MAAM,YAAY,CAAC;AAEpF,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE3C,MAAM,GAAG,GAAG,CAAC,GAAW,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;AAEzE,IAAI,eAAe,GAAmB,IAAI,CAAC;AAC3C,IAAI,aAAa,GAA4B,IAAI,CAAC;AAElD,MAAM,kBAAkB,GAAG;;;;;;;;;CAS1B,CAAC;AAEF,KAAK,UAAU,aAAa;IAC1B,IAAI,eAAe,EAAE,WAAW,EAAE;QAAE,OAAO,eAAe,CAAC;IAE3D,yDAAyD;IACzD,IAAI,aAAa;QAAE,OAAO,aAAa,CAAC;IAExC,aAAa,GAAG,QAAQ,CAAC,MAAM,CAAC;QAC9B,QAAQ,EAAE,IAAI;QACd,IAAI,EAAE,CAAC,eAAe,EAAE,mBAAmB,EAAE,cAAc,CAAC;KAC7D,CAAC,CAAC;IAEH,IAAI,CAAC;QACH,eAAe,GAAG,MAAM,aAAa,CAAC;QACtC,GAAG,CAAC,kBAAkB,CAAC,CAAC;QAExB,eAAe,CAAC,EAAE,CAAC,cAAc,EAAE,GAAG,EAAE;YACtC,eAAe,GAAG,IAAI,CAAC;YACvB,aAAa,GAAG,IAAI,CAAC;YACrB,GAAG,CAAC,sBAAsB,CAAC,CAAC;QAC9B,CAAC,CAAC,CAAC;QAEH,OAAO,eAAe,CAAC;IACzB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,aAAa,GAAG,IAAI,CAAC;QACrB,MAAM,IAAI,aAAa,CAAC,eAAe,EAAE,6BAA6B,GAAG,EAAE,CAAC,CAAC;IAC/E,CAAC;AACH,CAAC;AAED,KAAK,UAAU,aAAa,CAAC,QAAkB;IAC7C,MAAM,OAAO,GAAG,MAAM,aAAa,EAAE,CAAC;IACtC,OAAO,OAAO,CAAC,UAAU,CAAC;QACxB,QAAQ,EAAE,EAAE,KAAK,EAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE;QAC5D,MAAM,EAAE,OAAO;QACf,UAAU,EAAE,KAAK;QACjB,aAAa,EAAE,QAAQ;QACvB,iBAAiB,EAAE,CAAC;KACrB,CAAC,CAAC;AACL,CAAC;AAED,KAAK,UAAU,kBAAkB,CAC/B,IAAU,EACV,GAAW,EACX,OAAsE;IAEtE,IAAI,CAAC;QACH,MAAM,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;IACtE,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACtB,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACjE,IAAI,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC,IAAI,OAAO,CAAC,QAAQ,CAAC,wBAAwB,CAAC,EAAE,CAAC;YACnF,MAAM,IAAI,aAAa,CACrB,oBAAoB,EACpB,qBAAqB,GAAG,8BAA8B,CACvD,CAAC;QACJ,CAAC;QACD,IAAI,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;YAC/D,MAAM,IAAI,aAAa,CAAC,SAAS,EAAE,qCAAqC,GAAG,EAAE,CAAC,CAAC;QACjF,CAAC;QACD,MAAM,IAAI,aAAa,CAAC,eAAe,EAAE,sBAAsB,OAAO,EAAE,CAAC,CAAC;IAC5E,CAAC;IAED,IAAI,OAAO,CAAC,eAAe,EAAE,CAAC;QAC5B,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,eAAe,CAAC,OAAO,CAAC,eAAe,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;QAC3E,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,IAAI,aAAa,CACrB,oBAAoB,EACpB,aAAa,OAAO,CAAC,eAAe,wBAAwB,CAC7D,CAAC;QACJ,CAAC;IACH,CAAC;IAED,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC;QAC3B,MAAM,IAAI,CAAC,cAAc,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC;IACpD,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,OAA0B;IAC7D,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC;IAClE,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,IAAI,CAAC;IAE1C,GAAG,CAAC,eAAe,OAAO,CAAC,GAAG,MAAM,QAAQ,CAAC,KAAK,IAAI,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;IAEzE,MAAM,OAAO,GAAG,MAAM,aAAa,CAAC,QAAQ,CAAC,CAAC;IAC9C,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,OAAO,EAAE,CAAC;QAErC,oDAAoD;QACpD,MAAM,IAAI,CAAC,aAAa,CAAC;;4BAED,IAAI,CAAC,SAAS,CAAC,kBAAkB,CAAC;;;;;;MAMxD,CAAC,CAAC;QAEJ,MAAM,kBAAkB,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QAErD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC;YACnC,QAAQ;YACR,IAAI,EAAE,KAAK;YACX,UAAU,EAAE,UAAU;SACvB,CAAC,CAAC;QAEH,OAAO,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC7B,CAAC;YAAS,CAAC;QACT,MAAM,OAAO,CAAC,KAAK,EAAE,CAAC;IACxB,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,GAAW,EACX,QAAgB,EAChB,QAAmB,EACnB,eAAwB,EACxB,cAAuB;IAEvB,MAAM,EAAE,GAAG,QAAQ,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC;IAEpD,GAAG,CAAC,uBAAuB,QAAQ,MAAM,GAAG,EAAE,CAAC,CAAC;IAEhD,MAAM,OAAO,GAAG,MAAM,aAAa,CAAC,EAAE,CAAC,CAAC;IACxC,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,OAAO,EAAE,CAAC;QAErC,MAAM,IAAI,CAAC,aAAa,CAAC;;4BAED,IAAI,CAAC,SAAS,CAAC,kBAAkB,CAAC;;;;;;MAMxD,CAAC,CAAC;QAEJ,MAAM,kBAAkB,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE,eAAe,EAAE,cAAc,EAAE,CAAC,CAAC;QAEzE,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QACvC,MAAM,KAAK,GAAG,MAAM,OAAO,CAAC,KAAK,EAAE,CAAC;QACpC,IAAI,KAAK,KAAK,CAAC,EAAE,CAAC;YAChB,MAAM,IAAI,aAAa,CACrB,oBAAoB,EACpB,YAAY,QAAQ,qBAAqB,CAC1C,CAAC;QACJ,CAAC;QAED,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,KAAK,EAAE,CAAC,UAAU,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,CAAC,CAAC;QACzF,OAAO,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC7B,CAAC;YAAS,CAAC;QACT,MAAM,OAAO,CAAC,KAAK,EAAE,CAAC;IACxB,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,YAAY;IAChC,IAAI,eAAe,EAAE,WAAW,EAAE,EAAE,CAAC;QACnC,MAAM,eAAe,CAAC,KAAK,EAAE,CAAC;QAC9B,GAAG,CAAC,gBAAgB,CAAC,CAAC;IACxB,CAAC;IACD,eAAe,GAAG,IAAI,CAAC;IACvB,aAAa,GAAG,IAAI,CAAC;AACvB,CAAC"}

package/dist/storage.d.ts

@@ -0,0 +1,11 @@
+import type { SnapshotMetadata, ListSnapshotsOptions, CleanupOptions, CleanupResult } from './types.js';
+export declare function ensureStorageDirs(): Promise<void>;
+export declare function getSnapshotsDir(): string;
+export declare function getDiffsDir(): string;
+export declare function generateSnapshotId(): string;
+export declare function saveSnapshot(id: string, imageBuffer: Buffer, metadata: Omit<SnapshotMetadata, 'imagePath'>): Promise<SnapshotMetadata>;
+export declare function loadSnapshotMetadata(id: string): Promise<SnapshotMetadata>;
+export declare function loadSnapshotImage(id: string): Promise<Buffer>;
+export declare function findLatestSnapshot(url: string): Promise<SnapshotMetadata | null>;
+export declare function listSnapshots(options?: ListSnapshotsOptions): Promise<SnapshotMetadata[]>;
+export declare function cleanupSnapshots(options?: CleanupOptions): Promise<CleanupResult>;

package/dist/storage.js

@@ -0,0 +1,142 @@
+import { readdir, readFile, writeFile, rename, unlink, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { DiffLensError } from './types.js';
+const STORAGE_ROOT = '.difflens';
+const SNAPSHOTS_DIR = join(STORAGE_ROOT, 'snapshots');
+const DIFFS_DIR = join(STORAGE_ROOT, 'diffs');
+// Sequential write queue for concurrent safety
+let writeQueue = Promise.resolve();
+function enqueueWrite(fn) {
+    const result = writeQueue.then(fn);
+    writeQueue = result.then(() => { }, () => { });
+    return result;
+}
+export async function ensureStorageDirs() {
+    await mkdir(SNAPSHOTS_DIR, { recursive: true });
+    await mkdir(DIFFS_DIR, { recursive: true });
+}
+export function getSnapshotsDir() {
+    return SNAPSHOTS_DIR;
+}
+export function getDiffsDir() {
+    return DIFFS_DIR;
+}
+export function generateSnapshotId() {
+    const timestamp = Date.now();
+    const hex = randomBytes(4).toString('hex');
+    return `${timestamp}-${hex}`;
+}
+export async function saveSnapshot(id, imageBuffer, metadata) {
+    return enqueueWrite(async () => {
+        const imagePath = join(SNAPSHOTS_DIR, `${id}.png`);
+        const metadataPath = join(SNAPSHOTS_DIR, `${id}.json`);
+        const tmpImagePath = `${imagePath}.tmp`;
+        const tmpMetadataPath = `${metadataPath}.tmp`;
+        const fullMetadata = { ...metadata, imagePath };
+        // Atomic writes: write to .tmp then rename
+        await writeFile(tmpImagePath, imageBuffer);
+        await rename(tmpImagePath, imagePath);
+        await writeFile(tmpMetadataPath, JSON.stringify(fullMetadata, null, 2));
+        await rename(tmpMetadataPath, metadataPath);
+        return fullMetadata;
+    });
+}
+export async function loadSnapshotMetadata(id) {
+    const metadataPath = join(SNAPSHOTS_DIR, `${id}.json`);
+    try {
+        const data = await readFile(metadataPath, 'utf-8');
+        return JSON.parse(data);
+    }
+    catch {
+        throw new DiffLensError('SNAPSHOT_NOT_FOUND', `Snapshot "${id}" not found`);
+    }
+}
+export async function loadSnapshotImage(id) {
+    const imagePath = join(SNAPSHOTS_DIR, `${id}.png`);
+    try {
+        return await readFile(imagePath);
+    }
+    catch {
+        throw new DiffLensError('SNAPSHOT_NOT_FOUND', `Snapshot image "${id}" not found`);
+    }
+}
+export async function findLatestSnapshot(url) {
+    const snapshots = await listSnapshots({ url });
+    if (snapshots.length === 0)
+        return null;
+    // Already sorted by timestamp descending
+    return snapshots[0];
+}
+export async function listSnapshots(options = {}) {
+    try {
+        const files = await readdir(SNAPSHOTS_DIR);
+        const metadataFiles = files.filter(f => f.endsWith('.json'));
+        const snapshots = [];
+        for (const file of metadataFiles) {
+            try {
+                const data = await readFile(join(SNAPSHOTS_DIR, file), 'utf-8');
+                const metadata = JSON.parse(data);
+                if (options.url && metadata.url !== options.url)
+                    continue;
+                snapshots.push(metadata);
+            }
+            catch {
+                // Skip corrupted metadata files
+            }
+        }
+        // Sort by timestamp descending (newest first)
+        snapshots.sort((a, b) => b.timestamp - a.timestamp);
+        if (options.limit && options.limit > 0) {
+            return snapshots.slice(0, options.limit);
+        }
+        return snapshots;
+    }
+    catch {
+        return [];
+    }
+}
+export async function cleanupSnapshots(options = {}) {
+    const { maxAge, maxCount, dryRun = false } = options;
+    const now = Date.now();
+    const allSnapshots = await listSnapshots();
+    const toDelete = [];
+    const toKeep = [];
+    for (const snapshot of allSnapshots) {
+        let shouldDelete = false;
+        if (maxAge !== undefined && (now - snapshot.timestamp) > maxAge) {
+            shouldDelete = true;
+        }
+        if (shouldDelete) {
+            toDelete.push(snapshot.id);
+        }
+        else {
+            toKeep.push(snapshot);
+        }
+    }
+    // If maxCount is specified, mark excess snapshots for deletion (oldest first)
+    if (maxCount !== undefined && toKeep.length > maxCount) {
+        const excess = toKeep.splice(maxCount);
+        for (const snapshot of excess) {
+            toDelete.push(snapshot.id);
+        }
+    }
+    if (!dryRun) {
+        for (const id of toDelete) {
+            try {
+                await unlink(join(SNAPSHOTS_DIR, `${id}.png`));
+            }
+            catch { /* ignore */ }
+            try {
+                await unlink(join(SNAPSHOTS_DIR, `${id}.json`));
+            }
+            catch { /* ignore */ }
+        }
+    }
+    return {
+        deleted: toDelete,
+        kept: toKeep.length,
+        dryRun,
+    };
+}
+//# sourceMappingURL=storage.js.map

package/dist/storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.js","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,98 @@
+export interface Viewport {
+    width: number;
+    height: number;
+}
+export interface ScreenshotOptions {
+    url: string;
+    viewport?: Viewport;
+    fullPage?: boolean;
+    selector?: string;
+    waitForSelector?: string;
+    waitForTimeout?: number;
+}
+export interface SnapshotMetadata {
+    id: string;
+    url: string;
+    viewport: Viewport;
+    fullPage: boolean;
+    selector?: string;
+    timestamp: number;
+    imagePath: string;
+}
+export interface DiffRegion {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    changedPixels: number;
+    percentChanged: number;
+    description: string;
+}
+export interface DiffResult {
+    totalPixels: number;
+    changedPixels: number;
+    percentChanged: number;
+    dimensions: {
+        before: Viewport;
+        after: Viewport;
+        resized: boolean;
+    };
+    regions: DiffRegion[];
+    diffImagePath: string;
+    overlayImagePath: string;
+}
+export interface DiffReport {
+    status: 'no_changes' | 'minor' | 'significant' | 'major';
+    summary: string;
+    percentChanged: number;
+    dimensions: DiffResult['dimensions'];
+    regions: DiffRegion[];
+    diffImagePath: string;
+    overlayImagePath: string;
+}
+export interface ResponsiveCheckResult {
+    url: string;
+    viewports: Array<{
+        viewport: Viewport;
+        report: DiffReport;
+    }>;
+    summary: string;
+}
+export interface ListSnapshotsOptions {
+    url?: string;
+    limit?: number;
+}
+export interface CleanupOptions {
+    maxAge?: number;
+    maxCount?: number;
+    dryRun?: boolean;
+}
+export interface CleanupResult {
+    deleted: string[];
+    kept: number;
+    dryRun: boolean;
+}
+export interface LayoutElement {
+    selector: string;
+    tagName: string;
+    id?: string;
+    boundingBox: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    styles: Record<string, string>;
+}
+export interface LayoutChange {
+    selector: string;
+    type: 'moved' | 'resized' | 'style_changed' | 'added' | 'removed';
+    description: string;
+    before?: Partial<LayoutElement>;
+    after?: Partial<LayoutElement>;
+}
+export type DiffLensErrorCode = 'CONNECTION_REFUSED' | 'TIMEOUT' | 'SELECTOR_NOT_FOUND' | 'SNAPSHOT_NOT_FOUND' | 'NO_BASELINE' | 'STORAGE_ERROR' | 'BROWSER_ERROR' | 'INVALID_INPUT';
+export declare class DiffLensError extends Error {
+    code: DiffLensErrorCode;
+    constructor(code: DiffLensErrorCode, message: string);
+}

package/dist/types.js

@@ -0,0 +1,9 @@
+export class DiffLensError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'DiffLensError';
+        this.code = code;
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AA8GA,MAAM,OAAO,aAAc,SAAQ,KAAK;IACtC,IAAI,CAAoB;IAExB,YAAY,IAAuB,EAAE,OAAe;QAClD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;QAC5B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF"}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "difflens-cli",
+  "version": "1.0.0",
+  "description": "MCP server that gives AI coding agents visual diff capabilities for UI work",
+  "type": "module",
+  "bin": {
+    "difflens": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "postinstall": "npx playwright install chromium",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "claude",
+    "visual-diff",
+    "screenshot",
+    "ui-testing",
+    "visual-regression",
+    "playwright"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/byzkhan/difflens.git"
+  },
+  "homepage": "https://github.com/byzkhan/difflens",
+  "bugs": {
+    "url": "https://github.com/byzkhan/difflens/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "chokidar": "^5.0.0",
+    "pixelmatch": "^7.1.0",
+    "playwright": "^1.58.2",
+    "pngjs": "^7.0.0",
+    "sharp": "^0.34.5",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.2",
+    "@types/pngjs": "^6.0.5",
+    "typescript": "^5.9.3"
+  }
+}