laxy-verify 1.2.2 → 1.2.3

package/dist/visual-diff.js

@@ -58,7 +58,7 @@ function formatVisualDiffSummary(result) {
 function ensureDir(dir) {
     fs.mkdirSync(dir, { recursive: true });
 }
-async function captureScreenshot(url, outputPath, viewport) {
+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();
@@ -70,6 +70,42 @@ async function captureScreenshot(url, outputPath, viewport) {
         });
         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 {
@@ -81,7 +117,7 @@ async function loadPixelmatch() {
     const mod = await dynamicImport("pixelmatch");
     return mod.default;
 }
-async function compareImages(baselinePath, currentPath, diffOutputPath) {
+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);
@@ -99,22 +135,31 @@ async function compareImages(baselinePath, currentPath, diffOutputPath) {
     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 });
+    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") {
+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);
+        await captureScreenshot(url, currentPath, viewport, normalizedOptions);
         if (!fs.existsSync(baselinePath)) {
             fs.copyFileSync(currentPath, baselinePath);
             viewportResults.push({
@@ -130,12 +175,12 @@ async function runVisualDiff(projectDir, url, label = "current") {
             });
             continue;
         }
-        const comparison = await compareImages(baselinePath, currentPath, diffPath);
+        const comparison = await compareImages(baselinePath, currentPath, diffPath, normalizedOptions);
         let verdict = "pass";
-        if (comparison.diffPercentage >= 60) {
+        if (comparison.diffPercentage >= normalizedOptions.rollbackThreshold) {
             verdict = "rollback";
         }
-        else if (comparison.diffPercentage >= 30) {
+        else if (comparison.diffPercentage >= normalizedOptions.warnThreshold) {
             verdict = "warn";
         }
         if (verdict === "pass") {

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.2.3",
   "description": "Frontend verification CLI for build checks, Lighthouse, E2E, and release readiness",
   "license": "MIT",
   "type": "commonjs",