@logicsync/pixelprobe 0.1.0

package/dist/comparator/StyleComparator.js

@@ -0,0 +1,119 @@
+import { STYLE_CATEGORIES } from "../types/config.js";
+// Properties that have high visual impact when different
+const CRITICAL_PROPERTIES = new Set([
+    "display",
+    "position",
+    "width",
+    "height",
+    "flex-direction",
+    "grid-template-columns",
+    "grid-template-rows",
+    "font-size",
+    "visibility",
+    "overflow",
+]);
+// Properties with moderate visual impact
+const WARNING_PROPERTIES = new Set([
+    "margin",
+    "margin-top",
+    "margin-right",
+    "margin-bottom",
+    "margin-left",
+    "padding",
+    "padding-top",
+    "padding-right",
+    "padding-bottom",
+    "padding-left",
+    "font-family",
+    "font-weight",
+    "line-height",
+    "text-align",
+    "color",
+    "background-color",
+    "border",
+    "border-radius",
+    "gap",
+    "justify-content",
+    "align-items",
+    "flex-wrap",
+    "max-width",
+    "max-height",
+    "min-width",
+    "min-height",
+]);
+export class StyleComparator {
+    /**
+     * Compare computed styles from source and target elements.
+     */
+    static compare(sourceStyles, targetStyles) {
+        const differences = [];
+        // Build a reverse map: property → category
+        const propertyCategory = new Map();
+        for (const [cat, props] of Object.entries(STYLE_CATEGORIES)) {
+            for (const prop of props) {
+                propertyCategory.set(prop, cat);
+            }
+        }
+        // Union of all properties from both
+        const allProperties = new Set([
+            ...Object.keys(sourceStyles),
+            ...Object.keys(targetStyles),
+        ]);
+        for (const prop of allProperties) {
+            const sourceVal = normalizeValue(sourceStyles[prop] ?? "");
+            const targetVal = normalizeValue(targetStyles[prop] ?? "");
+            if (sourceVal !== targetVal) {
+                differences.push({
+                    property: prop,
+                    category: propertyCategory.get(prop) ?? "other",
+                    sourceValue: sourceStyles[prop] ?? "(not set)",
+                    targetValue: targetStyles[prop] ?? "(not set)",
+                    severity: classifySeverity(prop),
+                });
+            }
+        }
+        // Sort by severity (critical first), then by property name
+        const severityOrder = {
+            critical: 0,
+            warning: 1,
+            info: 2,
+        };
+        differences.sort((a, b) => severityOrder[a.severity] - severityOrder[b.severity] ||
+            a.property.localeCompare(b.property));
+        return {
+            differences,
+            summary: {
+                total: differences.length,
+                critical: differences.filter((d) => d.severity === "critical").length,
+                warning: differences.filter((d) => d.severity === "warning").length,
+                info: differences.filter((d) => d.severity === "info").length,
+            },
+            sourceStyleCount: Object.keys(sourceStyles).length,
+            targetStyleCount: Object.keys(targetStyles).length,
+        };
+    }
+}
+// ── Helpers ───────────────────────────────────────────────────────────
+function classifySeverity(property) {
+    if (CRITICAL_PROPERTIES.has(property))
+        return "critical";
+    if (WARNING_PROPERTIES.has(property))
+        return "warning";
+    return "info";
+}
+/**
+ * Normalize CSS values for comparison.
+ * E.g., "rgb(255, 0, 0)" vs "rgb(255,0,0)" should match.
+ */
+function normalizeValue(value) {
+    return value
+        .trim()
+        .toLowerCase()
+        .replace(/\s+/g, " ") // collapse whitespace
+        .replace(/,\s*/g, ", ") // normalize comma spacing
+        .replace(/\s*\/\s*/g, " / ") // normalize slash spacing
+        .replace(/0px/g, "0") // 0px → 0
+        .replace(/\.0+(?=\s|,|$|\))/g, "") // remove trailing .0
+        .replace(/rgba?\((\d+),\s*(\d+),\s*(\d+),\s*1\)/g, "rgb($1, $2, $3)"); // rgba(x,y,z,1) → rgb(x,y,z)
+}
+//# sourceMappingURL=StyleComparator.js.map

package/dist/comparator/StyleComparator.js.map

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

package/dist/core.d.ts

@@ -0,0 +1,23 @@
+import type { ComparisonConfig, Breakpoint } from "./types/config.js";
+import type { ComparisonResult, ProgressCallback, ElementInfo } from "./types/comparison.js";
+export declare class WebSectionComparator {
+    private browserManager;
+    constructor(options?: {
+        headless?: boolean;
+        timeout?: number;
+    });
+    /**
+     * Run a full comparison across all breakpoints.
+     */
+    compare(config: ComparisonConfig, onProgress?: ProgressCallback): Promise<ComparisonResult>;
+    /**
+     * Enumerate matching elements for a selector on a URL.
+     * Useful for disambiguation before comparing.
+     */
+    enumerate(url: string, selector: string, breakpoint?: string): Promise<ElementInfo[]>;
+    /**
+     * List available breakpoint presets.
+     */
+    listBreakpoints(): Breakpoint[];
+}
+//# sourceMappingURL=core.d.ts.map

package/dist/core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../src/core.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,gBAAgB,EAEhB,UAAU,EAEX,MAAM,mBAAmB,CAAC;AAE3B,OAAO,KAAK,EACV,gBAAgB,EAGhB,gBAAgB,EAChB,WAAW,EACZ,MAAM,uBAAuB,CAAC;AAM/B,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,cAAc,CAAiB;gBAE3B,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE;IAI9D;;OAEG;IACG,OAAO,CACX,MAAM,EAAE,gBAAgB,EACxB,UAAU,CAAC,EAAE,gBAAgB,GAC5B,OAAO,CAAC,gBAAgB,CAAC;IAkI5B;;;OAGG;IACG,SAAS,CACb,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,EAChB,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,WAAW,EAAE,CAAC;IAqBzB;;OAEG;IACH,eAAe;CAGhB"}

package/dist/core.js

@@ -0,0 +1,211 @@
+import { randomUUID } from "node:crypto";
+import { ComparisonConfigSchema } from "./types/config.js";
+import { BrowserManager } from "./browser/BrowserManager.js";
+import { ViewportManager } from "./browser/ViewportManager.js";
+import { SectionExtractor } from "./extractor/SectionExtractor.js";
+import { DiffAggregator } from "./comparator/DiffAggregator.js";
+export class WebSectionComparator {
+    browserManager;
+    constructor(options) {
+        this.browserManager = new BrowserManager(options);
+    }
+    /**
+     * Run a full comparison across all breakpoints.
+     */
+    async compare(config, onProgress) {
+        const start = Date.now();
+        const id = randomUUID().slice(0, 8);
+        // Validate config
+        const validated = ComparisonConfigSchema.parse(config);
+        // Resolve breakpoints
+        const resolvedBreakpoints = ViewportManager.resolve(validated.breakpoints, validated.customBreakpoints);
+        const resolvedConfig = {
+            ...validated,
+            resolvedBreakpoints,
+        };
+        onProgress?.({
+            phase: "init",
+            message: `Starting comparison with ${resolvedBreakpoints.length} breakpoints`,
+            progress: 0,
+        });
+        // Resolve separate selectors for source and target
+        const sourceSelector = validated.selector;
+        const targetSelector = validated.targetSelector ?? validated.selector;
+        try {
+            await this.browserManager.launch();
+            const breakpointResults = {};
+            for (let i = 0; i < resolvedBreakpoints.length; i++) {
+                const bp = resolvedBreakpoints[i];
+                const progressBase = Math.round(((i / resolvedBreakpoints.length) * 80) + 10);
+                onProgress?.({
+                    phase: "extracting",
+                    breakpoint: bp.name,
+                    message: `Comparing at ${bp.name} (${bp.width}×${bp.height})`,
+                    progress: progressBase,
+                });
+                // Create pages for this breakpoint
+                const sourcePage = await this.browserManager.createPage(bp);
+                const targetPage = await this.browserManager.createPage(bp);
+                try {
+                    // Navigate both pages (each waits for its own selector)
+                    await Promise.all([
+                        this.browserManager.navigateAndWait(sourcePage, validated.sourceUrl, {
+                            waitForSelector: validated.waitForSelector ?? sourceSelector,
+                            waitForTimeout: validated.waitForTimeout,
+                        }),
+                        this.browserManager.navigateAndWait(targetPage, validated.targetUrl, {
+                            waitForSelector: validated.waitForSelector ?? targetSelector,
+                            waitForTimeout: validated.waitForTimeout,
+                        }),
+                    ]);
+                    // Run comparison for this breakpoint
+                    const elementIdx = typeof validated.elementIndex === "number"
+                        ? validated.elementIndex
+                        : 0;
+                    const result = await DiffAggregator.compareBreakpoint(sourcePage, targetPage, bp, {
+                        selector: sourceSelector,
+                        targetSelector,
+                        elementIndex: elementIdx,
+                        styleCategories: validated.styleCategories,
+                        pixelThreshold: validated.pixelThreshold,
+                        includeVisual: validated.includeVisual,
+                        includeStyles: validated.includeStyles,
+                        includeLayout: validated.includeLayout,
+                    });
+                    breakpointResults[bp.name] = result;
+                }
+                finally {
+                    // Always close contexts to free resources
+                    await sourcePage.context().close();
+                    await targetPage.context().close();
+                }
+            }
+            onProgress?.({
+                phase: "reporting",
+                message: "Generating report",
+                progress: 90,
+            });
+            const summary = computeSummary(breakpointResults);
+            const result = {
+                id,
+                timestamp: new Date().toISOString(),
+                config: {
+                    sourceUrl: validated.sourceUrl,
+                    targetUrl: validated.targetUrl,
+                    selector: sourceSelector,
+                    targetSelector: targetSelector !== sourceSelector ? targetSelector : undefined,
+                    elementIndex: validated.elementIndex,
+                },
+                breakpoints: breakpointResults,
+                summary,
+                artifacts: {
+                    diffImages: {},
+                    sourceScreenshots: {},
+                    targetScreenshots: {},
+                },
+                duration: Date.now() - start,
+            };
+            onProgress?.({
+                phase: "done",
+                message: "Comparison complete",
+                progress: 100,
+            });
+            return result;
+        }
+        finally {
+            await this.browserManager.close();
+        }
+    }
+    /**
+     * Enumerate matching elements for a selector on a URL.
+     * Useful for disambiguation before comparing.
+     */
+    async enumerate(url, selector, breakpoint) {
+        const bp = ViewportManager.resolve([breakpoint ?? "desktop"])[0];
+        try {
+            await this.browserManager.launch();
+            const page = await this.browserManager.createPage(bp);
+            try {
+                await this.browserManager.navigateAndWait(page, url, {
+                    waitForSelector: selector,
+                });
+                return await SectionExtractor.enumerate(page, selector);
+            }
+            finally {
+                await page.context().close();
+            }
+        }
+        finally {
+            await this.browserManager.close();
+        }
+    }
+    /**
+     * List available breakpoint presets.
+     */
+    listBreakpoints() {
+        return ViewportManager.listPresets();
+    }
+}
+// ── Helpers ───────────────────────────────────────────────────────────
+function computeSummary(breakpoints) {
+    const entries = Object.entries(breakpoints);
+    let totalStyleDiffs = 0;
+    let totalLayoutDiffs = 0;
+    let totalPixelDiff = 0;
+    let pixelDiffCount = 0;
+    let breakpointsWithDiffs = 0;
+    let worstBreakpoint = null;
+    let worstScore = 0;
+    for (const [name, result] of entries) {
+        if (result.error)
+            continue;
+        const hasDiffs = (result.styles?.summary.total ?? 0) > 0 ||
+            (result.layout?.summary.total ?? 0) > 0 ||
+            (result.visual?.diffPercentage ?? 0) > 0;
+        if (hasDiffs)
+            breakpointsWithDiffs++;
+        totalStyleDiffs += result.styles?.summary.total ?? 0;
+        totalLayoutDiffs += result.layout?.summary.total ?? 0;
+        if (result.visual) {
+            totalPixelDiff += result.visual.diffPercentage;
+            pixelDiffCount++;
+        }
+        // Score = weighted sum of issues
+        const score = (result.styles?.summary.critical ?? 0) * 10 +
+            (result.styles?.summary.warning ?? 0) * 3 +
+            (result.styles?.summary.info ?? 0) * 1 +
+            (result.layout?.summary.critical ?? 0) * 10 +
+            (result.layout?.summary.warning ?? 0) * 3 +
+            (result.visual?.diffPercentage ?? 0) * 2;
+        if (score > worstScore) {
+            worstScore = score;
+            worstBreakpoint = name;
+        }
+    }
+    const avgPixelDiff = pixelDiffCount > 0
+        ? Math.round((totalPixelDiff / pixelDiffCount) * 100) / 100
+        : 0;
+    // Determine overall severity
+    const hasCritical = entries.some(([, r]) => (r.styles?.summary.critical ?? 0) > 0 ||
+        (r.layout?.summary.critical ?? 0) > 0 ||
+        (r.visual?.diffPercentage ?? 0) > 5);
+    const hasWarning = entries.some(([, r]) => (r.styles?.summary.warning ?? 0) > 0 ||
+        (r.layout?.summary.warning ?? 0) > 0 ||
+        (r.visual?.diffPercentage ?? 0) > 1);
+    return {
+        totalBreakpoints: entries.length,
+        breakpointsWithDifferences: breakpointsWithDiffs,
+        totalStyleDifferences: totalStyleDiffs,
+        totalLayoutDifferences: totalLayoutDiffs,
+        averagePixelDiff: avgPixelDiff,
+        worstBreakpoint,
+        overallSeverity: hasCritical
+            ? "critical"
+            : hasWarning
+                ? "warning"
+                : breakpointsWithDiffs > 0
+                    ? "info"
+                    : "pass",
+    };
+}
+//# sourceMappingURL=core.js.map

package/dist/core.js.map

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

package/dist/extractor/ScreenshotCapturer.d.ts

@@ -0,0 +1,20 @@
+import type { Locator, Page } from "playwright";
+export interface ScreenshotOptions {
+    fullPage?: boolean;
+    padding?: number;
+}
+export declare class ScreenshotCapturer {
+    /**
+     * Capture a screenshot of a specific element.
+     */
+    static captureElement(locator: Locator, options?: ScreenshotOptions): Promise<Buffer>;
+    /**
+     * Capture a screenshot of the full page.
+     */
+    static captureFullPage(page: Page): Promise<Buffer>;
+    /**
+     * Capture element with surrounding context (padding around it).
+     */
+    static captureElementWithContext(locator: Locator, padding?: number): Promise<Buffer>;
+}
+//# sourceMappingURL=ScreenshotCapturer.d.ts.map

package/dist/extractor/ScreenshotCapturer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ScreenshotCapturer.d.ts","sourceRoot":"","sources":["../../src/extractor/ScreenshotCapturer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAEhD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,qBAAa,kBAAkB;IAC7B;;OAEG;WACU,cAAc,CACzB,OAAO,EAAE,OAAO,EAChB,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,MAAM,CAAC;IAelB;;OAEG;WACU,eAAe,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC;IAUzD;;OAEG;WACU,yBAAyB,CACpC,OAAO,EAAE,OAAO,EAChB,OAAO,GAAE,MAAW,GACnB,OAAO,CAAC,MAAM,CAAC;CA8BnB"}

package/dist/extractor/ScreenshotCapturer.js

@@ -0,0 +1,56 @@
+export class ScreenshotCapturer {
+    /**
+     * Capture a screenshot of a specific element.
+     */
+    static async captureElement(locator, options = {}) {
+        // Scroll element into view first
+        await locator.scrollIntoViewIfNeeded();
+        // Small wait to ensure rendering is complete
+        await locator.page().waitForTimeout(100);
+        const screenshot = await locator.screenshot({
+            type: "png",
+            animations: "disabled",
+        });
+        return Buffer.from(screenshot);
+    }
+    /**
+     * Capture a screenshot of the full page.
+     */
+    static async captureFullPage(page) {
+        const screenshot = await page.screenshot({
+            type: "png",
+            fullPage: true,
+            animations: "disabled",
+        });
+        return Buffer.from(screenshot);
+    }
+    /**
+     * Capture element with surrounding context (padding around it).
+     */
+    static async captureElementWithContext(locator, padding = 20) {
+        await locator.scrollIntoViewIfNeeded();
+        await locator.page().waitForTimeout(100);
+        const box = await locator.boundingBox();
+        if (!box) {
+            throw new Error("Element has no bounding box (may be hidden)");
+        }
+        const page = locator.page();
+        const viewport = page.viewportSize();
+        if (!viewport) {
+            throw new Error("Page has no viewport size");
+        }
+        const clip = {
+            x: Math.max(0, box.x - padding),
+            y: Math.max(0, box.y - padding),
+            width: Math.min(viewport.width - Math.max(0, box.x - padding), box.width + padding * 2),
+            height: box.height + padding * 2,
+        };
+        const screenshot = await page.screenshot({
+            type: "png",
+            clip,
+            animations: "disabled",
+        });
+        return Buffer.from(screenshot);
+    }
+}
+//# sourceMappingURL=ScreenshotCapturer.js.map

package/dist/extractor/ScreenshotCapturer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ScreenshotCapturer.js","sourceRoot":"","sources":["../../src/extractor/ScreenshotCapturer.ts"],"names":[],"mappings":"AAOA,MAAM,OAAO,kBAAkB;IAC7B;;OAEG;IACH,MAAM,CAAC,KAAK,CAAC,cAAc,CACzB,OAAgB,EAChB,UAA6B,EAAE;QAE/B,iCAAiC;QACjC,MAAM,OAAO,CAAC,sBAAsB,EAAE,CAAC;QAEvC,6CAA6C;QAC7C,MAAM,OAAO,CAAC,IAAI,EAAE,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC;QAEzC,MAAM,UAAU,GAAG,MAAM,OAAO,CAAC,UAAU,CAAC;YAC1C,IAAI,EAAE,KAAK;YACX,UAAU,EAAE,UAAU;SACvB,CAAC,CAAC;QAEH,OAAO,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IACjC,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,KAAK,CAAC,eAAe,CAAC,IAAU;QACrC,MAAM,UAAU,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC;YACvC,IAAI,EAAE,KAAK;YACX,QAAQ,EAAE,IAAI;YACd,UAAU,EAAE,UAAU;SACvB,CAAC,CAAC;QAEH,OAAO,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IACjC,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,KAAK,CAAC,yBAAyB,CACpC,OAAgB,EAChB,UAAkB,EAAE;QAEpB,MAAM,OAAO,CAAC,sBAAsB,EAAE,CAAC;QACvC,MAAM,OAAO,CAAC,IAAI,EAAE,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC;QAEzC,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,WAAW,EAAE,CAAC;QACxC,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAC;QACjE,CAAC;QAED,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;QAC5B,MAAM,QAAQ,GAAG,IAAI,CAAC,YAAY,EAAE,CAAC;QACrC,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,MAAM,IAAI,KAAK,CAAC,2BAA2B,CAAC,CAAC;QAC/C,CAAC;QAED,MAAM,IAAI,GAAG;YACX,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,GAAG,OAAO,CAAC;YAC/B,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,GAAG,OAAO,CAAC;YAC/B,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,GAAG,OAAO,CAAC,EAAE,GAAG,CAAC,KAAK,GAAG,OAAO,GAAG,CAAC,CAAC;YACvF,MAAM,EAAE,GAAG,CAAC,MAAM,GAAG,OAAO,GAAG,CAAC;SACjC,CAAC;QAEF,MAAM,UAAU,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC;YACvC,IAAI,EAAE,KAAK;YACX,IAAI;YACJ,UAAU,EAAE,UAAU;SACvB,CAAC,CAAC;QAEH,OAAO,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IACjC,CAAC;CACF"}

package/dist/extractor/SectionExtractor.d.ts

@@ -0,0 +1,26 @@
+import type { Page } from "playwright";
+import type { ElementInfo } from "../types/comparison.js";
+export declare class SectionExtractor {
+    /**
+     * Find all elements matching a selector and return their info.
+     * Used for disambiguation when multiple elements match.
+     */
+    static enumerate(page: Page, selector: string): Promise<ElementInfo[]>;
+    /**
+     * Get a specific element by selector and index.
+     * Returns the Playwright ElementHandle locator for further operations.
+     */
+    static getElement(page: Page, selector: string, index?: number): Promise<{
+        info: ElementInfo;
+        locator: ReturnType<Page["locator"]>;
+    }>;
+    /**
+     * Validate that a selector matches at least one element.
+     */
+    static validate(page: Page, selector: string): Promise<{
+        valid: boolean;
+        count: number;
+        error?: string;
+    }>;
+}
+//# sourceMappingURL=SectionExtractor.d.ts.map

package/dist/extractor/SectionExtractor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SectionExtractor.d.ts","sourceRoot":"","sources":["../../src/extractor/SectionExtractor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,KAAK,EAAE,WAAW,EAAe,MAAM,wBAAwB,CAAC;AAEvE,qBAAa,gBAAgB;IAC3B;;;OAGG;WACU,SAAS,CACpB,IAAI,EAAE,IAAI,EACV,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,WAAW,EAAE,CAAC;IA0BzB;;;OAGG;WACU,UAAU,CACrB,IAAI,EAAE,IAAI,EACV,QAAQ,EAAE,MAAM,EAChB,KAAK,GAAE,MAAU,GAChB,OAAO,CAAC;QAAE,IAAI,EAAE,WAAW,CAAC;QAAC,OAAO,EAAE,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAA;KAAE,CAAC;IA+CvE;;OAEG;WACU,QAAQ,CACnB,IAAI,EAAE,IAAI,EACV,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAgB9D"}

package/dist/extractor/SectionExtractor.js

@@ -0,0 +1,92 @@
+export class SectionExtractor {
+    /**
+     * Find all elements matching a selector and return their info.
+     * Used for disambiguation when multiple elements match.
+     */
+    static async enumerate(page, selector) {
+        return await page.evaluate(({ sel }) => {
+            const elements = document.querySelectorAll(sel);
+            return Array.from(elements).map((el, index) => {
+                const rect = el.getBoundingClientRect();
+                const text = (el.textContent || "").trim().slice(0, 80);
+                return {
+                    selector: sel,
+                    index,
+                    tagName: el.tagName.toLowerCase(),
+                    textPreview: text.length === 80 ? text + "…" : text,
+                    boundingBox: {
+                        x: Math.round(rect.x),
+                        y: Math.round(rect.y),
+                        width: Math.round(rect.width),
+                        height: Math.round(rect.height),
+                    },
+                    exists: true,
+                };
+            });
+        }, { sel: selector });
+    }
+    /**
+     * Get a specific element by selector and index.
+     * Returns the Playwright ElementHandle locator for further operations.
+     */
+    static async getElement(page, selector, index = 0) {
+        const locator = page.locator(selector).nth(index);
+        const count = await page.locator(selector).count();
+        if (count === 0) {
+            return {
+                info: {
+                    selector,
+                    index,
+                    tagName: "unknown",
+                    textPreview: "",
+                    boundingBox: { x: 0, y: 0, width: 0, height: 0 },
+                    exists: false,
+                },
+                locator,
+            };
+        }
+        if (index >= count) {
+            throw new Error(`Element index ${index} out of range. Selector "${selector}" matched ${count} element(s).`);
+        }
+        const info = await locator.evaluate((el, idx) => {
+            const rect = el.getBoundingClientRect();
+            const text = (el.textContent || "").trim().slice(0, 80);
+            return {
+                selector: "", // filled below
+                index: idx,
+                tagName: el.tagName.toLowerCase(),
+                textPreview: text.length === 80 ? text + "…" : text,
+                boundingBox: {
+                    x: Math.round(rect.x),
+                    y: Math.round(rect.y),
+                    width: Math.round(rect.width),
+                    height: Math.round(rect.height),
+                },
+                exists: true,
+            };
+        }, index);
+        info.selector = selector;
+        return { info, locator };
+    }
+    /**
+     * Validate that a selector matches at least one element.
+     */
+    static async validate(page, selector) {
+        try {
+            const count = await page.locator(selector).count();
+            return {
+                valid: count > 0,
+                count,
+                error: count === 0 ? `No elements found matching "${selector}"` : undefined,
+            };
+        }
+        catch (err) {
+            return {
+                valid: false,
+                count: 0,
+                error: `Invalid selector "${selector}": ${err.message}`,
+            };
+        }
+    }
+}
+//# sourceMappingURL=SectionExtractor.js.map

package/dist/extractor/SectionExtractor.js.map

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

package/dist/extractor/StyleExtractor.d.ts

@@ -0,0 +1,23 @@
+import type { Locator } from "playwright";
+import { type StyleCategory } from "../types/config.js";
+import type { LayoutMetrics } from "../types/comparison.js";
+export declare class StyleExtractor {
+    /**
+     * Extract computed styles for specific categories from an element.
+     */
+    static extractStyles(locator: Locator, categories?: StyleCategory[]): Promise<Record<string, string>>;
+    /**
+     * Extract layout metrics (box model) from an element.
+     */
+    static extractLayoutMetrics(locator: Locator): Promise<LayoutMetrics>;
+    /**
+     * Extract computed styles for ALL properties (not just categorized ones).
+     * Useful for deep analysis.
+     */
+    static extractAllStyles(locator: Locator): Promise<Record<string, string>>;
+    /**
+     * Get the flat list of CSS properties for given categories.
+     */
+    private static getProperties;
+}
+//# sourceMappingURL=StyleExtractor.d.ts.map

package/dist/extractor/StyleExtractor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StyleExtractor.d.ts","sourceRoot":"","sources":["../../src/extractor/StyleExtractor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAQ,OAAO,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,EAAoB,KAAK,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAC1E,OAAO,KAAK,EAAE,aAAa,EAAc,MAAM,wBAAwB,CAAC;AAExE,qBAAa,cAAc;IACzB;;OAEG;WACU,aAAa,CACxB,OAAO,EAAE,OAAO,EAChB,UAAU,CAAC,EAAE,aAAa,EAAE,GAC3B,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAkBlC;;OAEG;WACU,oBAAoB,CAC/B,OAAO,EAAE,OAAO,GACf,OAAO,CAAC,aAAa,CAAC;IAsCzB;;;OAGG;WACU,gBAAgB,CAC3B,OAAO,EAAE,OAAO,GACf,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAclC;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,aAAa;CAa7B"}