laxy-verify 1.2.2 → 1.3.0

package/dist/visual-diff.js

@@ -1,178 +1,223 @@
-"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;
-    };
-})();
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.formatVisualDiffSummary = formatVisualDiffSummary;
-exports.runVisualDiff = runVisualDiff;
-const fs = __importStar(require("node:fs"));
-const path = __importStar(require("node:path"));
-const puppeteer_1 = __importDefault(require("puppeteer"));
-const pngjs_1 = require("pngjs");
-const VISUAL_DIFF_VIEWPORTS = [
-    { viewport: "desktop", width: 1280, height: 720 },
-    { viewport: "tablet", width: 768, height: 1024 },
-    { viewport: "mobile", width: 375, height: 812, isMobile: true, deviceScaleFactor: 2 },
-];
-function formatViewportResult(viewport) {
-    return viewport.hasBaseline
-        ? `${viewport.viewport} ${viewport.diffPercentage}% (${viewport.verdict})`
-        : `${viewport.viewport} baseline seeded`;
-}
-function formatVisualDiffSummary(result) {
-    return result.viewports.map(formatViewportResult).join(", ");
-}
-function ensureDir(dir) {
-    fs.mkdirSync(dir, { recursive: true });
-}
-async function captureScreenshot(url, outputPath, viewport) {
-    const browser = await puppeteer_1.default.launch({ headless: true, args: ["--no-sandbox", "--disable-setuid-sandbox"] });
-    try {
-        const page = await browser.newPage();
-        await page.setViewport({
-            width: viewport.width,
-            height: viewport.height,
-            isMobile: viewport.isMobile ?? false,
-            deviceScaleFactor: viewport.deviceScaleFactor ?? 1,
-        });
-        await page.goto(url, { waitUntil: "networkidle2", timeout: 20000 });
-        await page.waitForSelector("body", { timeout: 5000 });
-        await page.screenshot({ path: outputPath, fullPage: true, type: "png" });
-    }
-    finally {
-        await browser.close();
-    }
-}
-async function loadPixelmatch() {
-    const dynamicImport = new Function("specifier", "return import(specifier)");
-    const mod = await dynamicImport("pixelmatch");
-    return mod.default;
-}
-async function compareImages(baselinePath, currentPath, diffOutputPath) {
-    const baselinePng = pngjs_1.PNG.sync.read(fs.readFileSync(baselinePath));
-    const currentPng = pngjs_1.PNG.sync.read(fs.readFileSync(currentPath));
-    const width = Math.min(baselinePng.width, currentPng.width);
-    const height = Math.min(baselinePng.height, currentPng.height);
-    const cropData = (png, w, h) => {
-        if (png.width === w && png.height === h)
-            return png.data;
-        const cropped = Buffer.alloc(w * h * 4);
-        for (let y = 0; y < h; y++) {
-            png.data.copy(cropped, y * w * 4, y * png.width * 4, y * png.width * 4 + w * 4);
-        }
-        return cropped;
-    };
-    const baseData = cropData(baselinePng, width, height);
-    const currData = cropData(currentPng, width, height);
-    const diff = new pngjs_1.PNG({ width, height });
-    const pixelmatch = await loadPixelmatch();
-    const diffPixels = pixelmatch(baseData, currData, diff.data, width, height, { threshold: 0.1 });
-    ensureDir(path.dirname(diffOutputPath));
-    fs.writeFileSync(diffOutputPath, pngjs_1.PNG.sync.write(diff));
-    const totalPixels = width * height;
-    const diffPercentage = Math.round((diffPixels / totalPixels) * 10000) / 100;
-    return { diffPixels, totalPixels, diffPercentage };
-}
-async function runVisualDiff(projectDir, url, label = "current") {
-    const dir = path.join(projectDir, ".laxy-verify", "visual");
-    ensureDir(dir);
-    const viewportResults = [];
-    for (const viewport of VISUAL_DIFF_VIEWPORTS) {
-        const baselinePath = path.join(dir, `${viewport.viewport}.baseline.png`);
-        const currentPath = path.join(dir, `${label}.${viewport.viewport}.png`);
-        const diffPath = path.join(dir, `${label}.${viewport.viewport}.diff.png`);
-        await captureScreenshot(url, currentPath, viewport);
-        if (!fs.existsSync(baselinePath)) {
-            fs.copyFileSync(currentPath, baselinePath);
-            viewportResults.push({
-                viewport: viewport.viewport,
-                hasBaseline: false,
-                diffPercentage: 0,
-                verdict: "pass",
-                diffPixels: 0,
-                totalPixels: 0,
-                baselinePath,
-                currentPath,
-                diffPath: "",
-            });
-            continue;
-        }
-        const comparison = await compareImages(baselinePath, currentPath, diffPath);
-        let verdict = "pass";
-        if (comparison.diffPercentage >= 60) {
-            verdict = "rollback";
-        }
-        else if (comparison.diffPercentage >= 30) {
-            verdict = "warn";
-        }
-        if (verdict === "pass") {
-            fs.copyFileSync(currentPath, baselinePath);
-        }
-        viewportResults.push({
-            viewport: viewport.viewport,
-            hasBaseline: true,
-            diffPercentage: comparison.diffPercentage,
-            verdict,
-            diffPixels: comparison.diffPixels,
-            totalPixels: comparison.totalPixels,
-            baselinePath,
-            currentPath,
-            diffPath,
-        });
-    }
-    const comparableResults = viewportResults.filter((viewport) => viewport.hasBaseline);
-    const summary = viewportResults.map(formatViewportResult).join(", ");
-    const worstVerdict = comparableResults.some((viewport) => viewport.verdict === "rollback")
-        ? "rollback"
-        : comparableResults.some((viewport) => viewport.verdict === "warn")
-            ? "warn"
-            : "pass";
-    const maxDiffPercentage = comparableResults.reduce((max, viewport) => Math.max(max, viewport.diffPercentage), 0);
-    const totalDiffPixels = comparableResults.reduce((sum, viewport) => sum + viewport.diffPixels, 0);
-    const totalPixels = comparableResults.reduce((sum, viewport) => sum + viewport.totalPixels, 0);
-    return {
-        hasBaseline: comparableResults.length === viewportResults.length,
-        diffPercentage: Math.round(maxDiffPercentage * 100) / 100,
-        verdict: worstVerdict,
-        diffPixels: totalDiffPixels,
-        totalPixels,
-        baselinePath: viewportResults[0]?.baselinePath ?? "",
-        currentPath: viewportResults[0]?.currentPath ?? "",
-        diffPath: viewportResults[0]?.diffPath ?? "",
-        viewports: viewportResults,
-        summary,
-    };
-}
+"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;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatVisualDiffSummary = formatVisualDiffSummary;
+exports.runVisualDiff = runVisualDiff;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const puppeteer_1 = __importDefault(require("puppeteer"));
+const pngjs_1 = require("pngjs");
+const VISUAL_DIFF_VIEWPORTS = [
+    { viewport: "desktop", width: 1280, height: 720 },
+    { viewport: "tablet", width: 768, height: 1024 },
+    { viewport: "mobile", width: 375, height: 812, isMobile: true, deviceScaleFactor: 2 },
+];
+function formatViewportResult(viewport) {
+    return viewport.hasBaseline
+        ? `${viewport.viewport} ${viewport.diffPercentage}% (${viewport.verdict})`
+        : `${viewport.viewport} baseline seeded`;
+}
+function formatVisualDiffSummary(result) {
+    return result.viewports.map(formatViewportResult).join(", ");
+}
+function ensureDir(dir) {
+    fs.mkdirSync(dir, { recursive: true });
+}
+async function captureScreenshot(url, outputPath, viewport, options) {
+    const browser = await puppeteer_1.default.launch({ headless: true, args: ["--no-sandbox", "--disable-setuid-sandbox"] });
+    try {
+        const page = await browser.newPage();
+        await page.setViewport({
+            width: viewport.width,
+            height: viewport.height,
+            isMobile: viewport.isMobile ?? false,
+            deviceScaleFactor: viewport.deviceScaleFactor ?? 1,
+        });
+        await page.goto(url, { waitUntil: "networkidle2", timeout: 20000 });
+        await page.waitForSelector("body", { timeout: 5000 });
+        await page.evaluate(({ disableAnimations, ignoreSelectors }) => {
+            if (disableAnimations) {
+                for (const node of Array.from(document.querySelectorAll("[data-animate]"))) {
+                    const el = node;
+                    el.style.setProperty("animation", "none", "important");
+                    el.style.setProperty("transition", "none", "important");
+                    el.getAnimations?.().forEach((animation) => animation.cancel());
+                }
+            }
+            for (const selector of ignoreSelectors) {
+                for (const node of Array.from(document.querySelectorAll(selector))) {
+                    const el = node;
+                    el.setAttribute("data-laxy-visual-ignore", "true");
+                }
+            }
+            if (!document.getElementById("laxy-visual-diff-style")) {
+                const style = document.createElement("style");
+                style.id = "laxy-visual-diff-style";
+                style.textContent = `
+            [data-animate] {
+              animation: none !important;
+              transition: none !important;
+            }
+            [data-laxy-visual-ignore="true"] {
+              visibility: hidden !important;
+              animation: none !important;
+              transition: none !important;
+            }
+          `;
+                document.head.appendChild(style);
+            }
+        }, {
+            disableAnimations: options.disableAnimations,
+            ignoreSelectors: options.ignoreSelectors,
+        });
+        await new Promise((resolve) => setTimeout(resolve, 150));
+        await page.screenshot({ path: outputPath, fullPage: true, type: "png" });
+    }
+    finally {
+        await browser.close();
+    }
+}
+async function loadPixelmatch() {
+    const dynamicImport = new Function("specifier", "return import(specifier)");
+    const mod = await dynamicImport("pixelmatch");
+    return mod.default;
+}
+async function compareImages(baselinePath, currentPath, diffOutputPath, options) {
+    const baselinePng = pngjs_1.PNG.sync.read(fs.readFileSync(baselinePath));
+    const currentPng = pngjs_1.PNG.sync.read(fs.readFileSync(currentPath));
+    const width = Math.min(baselinePng.width, currentPng.width);
+    const height = Math.min(baselinePng.height, currentPng.height);
+    const cropData = (png, w, h) => {
+        if (png.width === w && png.height === h)
+            return png.data;
+        const cropped = Buffer.alloc(w * h * 4);
+        for (let y = 0; y < h; y++) {
+            png.data.copy(cropped, y * w * 4, y * png.width * 4, y * png.width * 4 + w * 4);
+        }
+        return cropped;
+    };
+    const baseData = cropData(baselinePng, width, height);
+    const currData = cropData(currentPng, width, height);
+    const diff = new pngjs_1.PNG({ width, height });
+    const pixelmatch = await loadPixelmatch();
+    const diffPixels = pixelmatch(baseData, currData, diff.data, width, height, {
+        threshold: options.pixelmatchThreshold,
+    });
+    ensureDir(path.dirname(diffOutputPath));
+    fs.writeFileSync(diffOutputPath, pngjs_1.PNG.sync.write(diff));
+    const totalPixels = width * height;
+    const diffPercentage = Math.round((diffPixels / totalPixels) * 10000) / 100;
+    return { diffPixels, totalPixels, diffPercentage };
+}
+async function runVisualDiff(projectDir, url, label = "current", options = {}) {
+    const dir = path.join(projectDir, ".laxy-verify", "visual");
+    ensureDir(dir);
+    const normalizedOptions = {
+        pixelmatchThreshold: options.pixelmatchThreshold ?? 0.1,
+        warnThreshold: options.warnThreshold ?? 30,
+        rollbackThreshold: options.rollbackThreshold ?? 60,
+        ignoreSelectors: options.ignoreSelectors ?? [],
+        disableAnimations: options.disableAnimations ?? true,
+    };
+    const viewportResults = [];
+    for (const viewport of VISUAL_DIFF_VIEWPORTS) {
+        const baselinePath = path.join(dir, `${viewport.viewport}.baseline.png`);
+        const currentPath = path.join(dir, `${label}.${viewport.viewport}.png`);
+        const diffPath = path.join(dir, `${label}.${viewport.viewport}.diff.png`);
+        await captureScreenshot(url, currentPath, viewport, normalizedOptions);
+        if (!fs.existsSync(baselinePath)) {
+            fs.copyFileSync(currentPath, baselinePath);
+            viewportResults.push({
+                viewport: viewport.viewport,
+                hasBaseline: false,
+                diffPercentage: 0,
+                verdict: "pass",
+                diffPixels: 0,
+                totalPixels: 0,
+                baselinePath,
+                currentPath,
+                diffPath: "",
+            });
+            continue;
+        }
+        const comparison = await compareImages(baselinePath, currentPath, diffPath, normalizedOptions);
+        let verdict = "pass";
+        if (comparison.diffPercentage >= normalizedOptions.rollbackThreshold) {
+            verdict = "rollback";
+        }
+        else if (comparison.diffPercentage >= normalizedOptions.warnThreshold) {
+            verdict = "warn";
+        }
+        if (verdict === "pass") {
+            fs.copyFileSync(currentPath, baselinePath);
+        }
+        viewportResults.push({
+            viewport: viewport.viewport,
+            hasBaseline: true,
+            diffPercentage: comparison.diffPercentage,
+            verdict,
+            diffPixels: comparison.diffPixels,
+            totalPixels: comparison.totalPixels,
+            baselinePath,
+            currentPath,
+            diffPath,
+        });
+    }
+    const comparableResults = viewportResults.filter((viewport) => viewport.hasBaseline);
+    const summary = viewportResults.map(formatViewportResult).join(", ");
+    const worstVerdict = comparableResults.some((viewport) => viewport.verdict === "rollback")
+        ? "rollback"
+        : comparableResults.some((viewport) => viewport.verdict === "warn")
+            ? "warn"
+            : "pass";
+    const maxDiffPercentage = comparableResults.reduce((max, viewport) => Math.max(max, viewport.diffPercentage), 0);
+    const totalDiffPixels = comparableResults.reduce((sum, viewport) => sum + viewport.diffPixels, 0);
+    const totalPixels = comparableResults.reduce((sum, viewport) => sum + viewport.totalPixels, 0);
+    return {
+        hasBaseline: comparableResults.length === viewportResults.length,
+        diffPercentage: Math.round(maxDiffPercentage * 100) / 100,
+        verdict: worstVerdict,
+        diffPixels: totalDiffPixels,
+        totalPixels,
+        baselinePath: viewportResults[0]?.baselinePath ?? "",
+        currentPath: viewportResults[0]?.currentPath ?? "",
+        diffPath: viewportResults[0]?.diffPath ?? "",
+        viewports: viewportResults,
+        summary,
+    };
+}

package/dist/vitals-budget.d.ts

@@ -0,0 +1,23 @@
+export interface VitalsBudgetConfig {
+    lcp: number;
+    cls: number;
+    inp: number;
+}
+export interface VitalsMetric {
+    name: string;
+    value: number;
+    unit: string;
+    budget: number;
+    passed: boolean;
+}
+export interface VitalsBudgetResult {
+    passed: boolean;
+    metrics: VitalsMetric[];
+    lcp: number | null;
+    cls: number | null;
+    inp: number | null;
+    url: string;
+    skipped: boolean;
+    summary: string;
+}
+export declare function runVitalsBudget(url: string, budget?: Partial<VitalsBudgetConfig>): Promise<VitalsBudgetResult>;

package/dist/vitals-budget.js

@@ -0,0 +1,168 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runVitalsBudget = runVitalsBudget;
+/**
+ * Core Web Vitals budget check.
+ *
+ * Uses Puppeteer to measure LCP, CLS, and INP against configurable
+ * budgets. Does NOT claim FID — INP is the modern replacement.
+ * Blocker-capable: budget violations surface as warnings.
+ */
+let puppeteerModule = null;
+try {
+    puppeteerModule = require("puppeteer");
+}
+catch {
+    // Puppeteer not available — vitals budget will be skipped
+}
+const DEFAULT_BUDGET = {
+    lcp: 2500,
+    cls: 0.1,
+    inp: 200,
+};
+async function runVitalsBudget(url, budget) {
+    if (!puppeteerModule) {
+        return {
+            passed: true,
+            metrics: [],
+            lcp: null,
+            cls: null,
+            inp: null,
+            url,
+            skipped: true,
+            summary: "Skipped (puppeteer not available)",
+        };
+    }
+    const effectiveBudget = { ...DEFAULT_BUDGET, ...budget };
+    console.log("  Running Core Web Vitals budget check...");
+    const puppeteer = puppeteerModule.default || puppeteerModule;
+    let browser;
+    try {
+        browser = await puppeteer.launch({
+            headless: true,
+            args: [
+                "--no-sandbox",
+                "--disable-setuid-sandbox",
+                "--disable-extensions",
+                "--disable-component-update",
+            ],
+        });
+        const page = await browser.newPage();
+        await page.setViewport({ width: 1350, height: 940 });
+        // Inject web-vitals measurement script before navigation
+        await page.evaluateOnNewDocument(() => {
+            window.__laxyVitals = {};
+            // LCP
+            try {
+                new PerformanceObserver((list) => {
+                    const entries = list.getEntries();
+                    const last = entries[entries.length - 1];
+                    if (last) {
+                        window.__laxyVitals.lcp = last.startTime;
+                    }
+                }).observe({ type: "largest-contentful-paint", buffered: true });
+            }
+            catch { }
+            // CLS
+            try {
+                let clsValue = 0;
+                new PerformanceObserver((list) => {
+                    for (const entry of list.getEntries()) {
+                        if (!entry.hadRecentInput) {
+                            clsValue += entry.value;
+                        }
+                    }
+                    window.__laxyVitals.cls = clsValue;
+                }).observe({ type: "layout-shift", buffered: true });
+            }
+            catch { }
+            // INP (Event Timing)
+            try {
+                let worstInp = 0;
+                new PerformanceObserver((list) => {
+                    for (const entry of list.getEntries()) {
+                        const duration = entry.duration;
+                        if (duration > worstInp) {
+                            worstInp = duration;
+                        }
+                    }
+                    window.__laxyVitals.inp = worstInp;
+                }).observe({ type: "event", buffered: true });
+            }
+            catch { }
+        });
+        await page.goto(url, { waitUntil: "networkidle2", timeout: 30000 });
+        // Wait for LCP to stabilize
+        await new Promise((resolve) => setTimeout(resolve, 3000));
+        // Simulate some interactions to get INP
+        try {
+            await page.mouse.click(100, 100);
+            await new Promise((resolve) => setTimeout(resolve, 500));
+            await page.keyboard.press("Tab");
+            await new Promise((resolve) => setTimeout(resolve, 500));
+        }
+        catch {
+            // interaction may fail on minimal pages
+        }
+        // Wait a bit more for metrics to settle
+        await new Promise((resolve) => setTimeout(resolve, 2000));
+        const vitals = await page.evaluate(() => {
+            const v = window.__laxyVitals;
+            return {
+                lcp: v.lcp ?? 0,
+                cls: v.cls ?? 0,
+                inp: v.inp ?? 0,
+            };
+        });
+        const metrics = [
+            {
+                name: "LCP",
+                value: Math.round(vitals.lcp),
+                unit: "ms",
+                budget: effectiveBudget.lcp,
+                passed: vitals.lcp <= effectiveBudget.lcp,
+            },
+            {
+                name: "CLS",
+                value: Math.round(vitals.cls * 1000) / 1000,
+                unit: "score",
+                budget: effectiveBudget.cls,
+                passed: vitals.cls <= effectiveBudget.cls,
+            },
+            {
+                name: "INP",
+                value: Math.round(vitals.inp),
+                unit: "ms",
+                budget: effectiveBudget.inp,
+                passed: vitals.inp <= effectiveBudget.inp,
+            },
+        ];
+        const passed = metrics.every((m) => m.passed);
+        const failedMetrics = metrics.filter((m) => !m.passed);
+        const summary = passed
+            ? `LCP ${Math.round(vitals.lcp)}ms, CLS ${(vitals.cls).toFixed(3)}, INP ${Math.round(vitals.inp)}ms — within budget`
+            : failedMetrics.map((m) => `${m.name} ${m.value}${m.unit} > ${m.budget}${m.unit}`).join("; ");
+        console.log(`  Vitals budget: ${summary}`);
+        for (const m of metrics) {
+            const status = m.passed ? "OK" : "OVER";
+            console.log(`    ${m.name}: ${m.value}${m.unit} / ${m.budget}${m.unit} ${status}`);
+        }
+        return { passed, metrics, lcp: Math.round(vitals.lcp), cls: Math.round(vitals.cls * 1000) / 1000, inp: Math.round(vitals.inp), url, skipped: false, summary };
+    }
+    catch (err) {
+        console.error(`  Vitals budget error: ${err instanceof Error ? err.message : String(err)}`);
+        return {
+            passed: true,
+            metrics: [],
+            lcp: null,
+            cls: null,
+            inp: null,
+            url,
+            skipped: true,
+            summary: `Error: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+    finally {
+        await browser?.close();
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "laxy-verify",
-  "version": "1.2.2",
+  "version": "1.3.0",
   "description": "Frontend verification CLI for build checks, Lighthouse, E2E, and release readiness",
   "license": "MIT",
   "type": "commonjs",