imperium-crawl 1.5.3 → 2.0.0

package/dist/snapshot/annotator.js

@@ -0,0 +1,152 @@
+/**
+ * Annotated Screenshots — Inject visual overlay badges on interactive elements.
+ *
+ * Zero external deps — uses DOM injection via page.evaluate(),
+ * takes screenshot, then cleans up injected elements.
+ *
+ * Color coding:
+ * - Red (#e53e3e)    = button, switch
+ * - Blue (#3182ce)   = link, tab
+ * - Green (#38a169)  = textbox, searchbox, combobox, listbox
+ * - Orange (#dd6b20) = other interactive (checkbox, radio, slider, etc.)
+ */
+const ROLE_COLORS = {
+    button: "#e53e3e",
+    switch: "#e53e3e",
+    link: "#3182ce",
+    tab: "#3182ce",
+    textbox: "#38a169",
+    searchbox: "#38a169",
+    combobox: "#38a169",
+    listbox: "#38a169",
+};
+const DEFAULT_COLOR = "#dd6b20";
+const ANNOTATION_ATTR = "data-imperium-annotation";
+/**
+ * Inject annotation overlays on interactive elements, take screenshot, cleanup.
+ * Returns PNG buffer.
+ */
+export async function annotateScreenshot(page, refs) {
+    // Build annotation data for injection
+    const annotations = Object.entries(refs).map(([ref, entry]) => ({
+        ref,
+        role: entry.role,
+        name: entry.name,
+        nth: entry.nth,
+        color: ROLE_COLORS[entry.role] ?? DEFAULT_COLOR,
+    }));
+    // Inject overlays via page.evaluate
+    await page.evaluate((data) => {
+        const ATTR = "data-imperium-annotation";
+        for (const { ref, role, name, nth, color } of data) {
+            // Find the element using ARIA queries
+            let elements;
+            try {
+                // Try aria role query
+                const selector = name
+                    ? `[role="${role}"]`
+                    : `[role="${role}"]`;
+                elements = Array.from(document.querySelectorAll(selector));
+                // Filter by accessible name if provided
+                if (name) {
+                    elements = elements.filter((el) => {
+                        const accName = el.getAttribute("aria-label") ||
+                            el.getAttribute("title") ||
+                            (el.textContent ?? "").trim();
+                        return accName.includes(name) || name.includes(accName.slice(0, 80));
+                    });
+                }
+                // Handle nth
+                if (nth !== undefined && elements[nth]) {
+                    elements = [elements[nth]];
+                }
+                else if (elements.length > 0) {
+                    elements = [elements[0]];
+                }
+                // Fallback: try matching by tag for common roles
+                if (elements.length === 0) {
+                    const tagMap = {
+                        button: "button",
+                        link: "a",
+                        textbox: "input,textarea",
+                        searchbox: "input[type=search]",
+                        checkbox: "input[type=checkbox]",
+                        radio: "input[type=radio]",
+                    };
+                    if (tagMap[role]) {
+                        const tagEls = document.querySelectorAll(tagMap[role]);
+                        for (const el of tagEls) {
+                            const accName = el.getAttribute("aria-label") ||
+                                el.getAttribute("title") ||
+                                (el.textContent ?? "").trim();
+                            if (!name || accName.includes(name) || name.includes(accName.slice(0, 80))) {
+                                elements = [el];
+                                break;
+                            }
+                        }
+                    }
+                }
+            }
+            catch {
+                elements = [];
+            }
+            if (elements.length === 0)
+                continue;
+            const el = elements[0];
+            const rect = el.getBoundingClientRect();
+            if (rect.width === 0 || rect.height === 0)
+                continue;
+            // Create border overlay
+            const border = document.createElement("div");
+            border.setAttribute(ATTR, ref);
+            Object.assign(border.style, {
+                position: "absolute",
+                top: `${rect.top + window.scrollY}px`,
+                left: `${rect.left + window.scrollX}px`,
+                width: `${rect.width}px`,
+                height: `${rect.height}px`,
+                border: `2px solid ${color}`,
+                borderRadius: "3px",
+                pointerEvents: "none",
+                zIndex: "2147483647",
+                boxSizing: "border-box",
+            });
+            // Create badge
+            const badge = document.createElement("div");
+            badge.setAttribute(ATTR, `${ref}-badge`);
+            const refNum = ref.replace("e", "");
+            badge.textContent = refNum;
+            Object.assign(badge.style, {
+                position: "absolute",
+                top: `${rect.top + window.scrollY - 10}px`,
+                left: `${rect.left + window.scrollX - 10}px`,
+                width: "20px",
+                height: "20px",
+                borderRadius: "50%",
+                backgroundColor: color,
+                color: "white",
+                fontSize: "11px",
+                fontWeight: "bold",
+                fontFamily: "Arial, sans-serif",
+                display: "flex",
+                alignItems: "center",
+                justifyContent: "center",
+                pointerEvents: "none",
+                zIndex: "2147483647",
+                lineHeight: "1",
+            });
+            document.body.appendChild(border);
+            document.body.appendChild(badge);
+        }
+    }, annotations);
+    // Take screenshot with annotations
+    const screenshot = await page.screenshot({ fullPage: false });
+    // Cleanup injected elements
+    await page.evaluate((attr) => {
+        const els = document.querySelectorAll(`[${attr}]`);
+        for (const el of els)
+            el.remove();
+    }, ANNOTATION_ATTR);
+    return screenshot;
+}
+//# sourceMappingURL=annotator.js.map

package/dist/snapshot/annotator.js.map

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

package/dist/snapshot/boundary.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Content boundaries — unique markers to wrap content sections.
+ * Prevents LLM confusion about where content starts/ends.
+ */
+export declare function generateBoundary(): string;
+export declare function wrapContent(content: string, boundary: string): string;
+//# sourceMappingURL=boundary.d.ts.map

package/dist/snapshot/boundary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"boundary.d.ts","sourceRoot":"","sources":["../../src/snapshot/boundary.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC;AAED,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAErE"}

package/dist/snapshot/boundary.js

@@ -0,0 +1,12 @@
+/**
+ * Content boundaries — unique markers to wrap content sections.
+ * Prevents LLM confusion about where content starts/ends.
+ */
+import { randomBytes } from "node:crypto";
+export function generateBoundary() {
+    return randomBytes(8).toString("hex");
+}
+export function wrapContent(content, boundary) {
+    return `<imperium-boundary:${boundary}>\n${content}\n</imperium-boundary:${boundary}>`;
+}
+//# sourceMappingURL=boundary.js.map

package/dist/snapshot/boundary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"boundary.js","sourceRoot":"","sources":["../../src/snapshot/boundary.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,MAAM,UAAU,gBAAgB;IAC9B,OAAO,WAAW,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AACxC,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,OAAe,EAAE,QAAgB;IAC3D,OAAO,sBAAsB,QAAQ,MAAM,OAAO,yBAAyB,QAAQ,GAAG,CAAC;AACzF,CAAC"}

package/dist/snapshot/differ.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Dual diff system — text (Myers) + image (pixel comparison).
+ *
+ * Text diff: Line-level Myers algorithm on snapshot strings.
+ * Image diff: Canvas-based pixel comparison in an isolated browser page.
+ */
+type BrowserContext = import("rebrowser-playwright").BrowserContext;
+export interface TextDiffResult {
+    diff: string;
+    additions: number;
+    removals: number;
+    unchanged: number;
+    changed: boolean;
+}
+/**
+ * Myers diff algorithm (line-level).
+ * Returns unified diff format with +/- prefixes.
+ */
+export declare function diffSnapshots(before: string, after: string): TextDiffResult;
+export interface ImageDiffResult {
+    mismatchPercentage: number;
+    match: boolean;
+    diffImage: Buffer;
+    totalPixels: number;
+    changedPixels: number;
+}
+export interface ImageDiffOptions {
+    /** Color distance threshold (0-255). Default: 30 */
+    threshold?: number;
+    /** Match if mismatch is below this % (default: 1.0) */
+    matchThreshold?: number;
+}
+/**
+ * Pixel-level comparison of two screenshots.
+ * Opens an isolated page, loads images via intercepted routes,
+ * computes per-pixel color distance, generates diff PNG.
+ */
+export declare function diffScreenshots(context: BrowserContext, baseline: Buffer, current: Buffer, options?: ImageDiffOptions): Promise<ImageDiffResult>;
+export {};
+//# sourceMappingURL=differ.d.ts.map

package/dist/snapshot/differ.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"differ.d.ts","sourceRoot":"","sources":["../../src/snapshot/differ.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,KAAK,cAAc,GAAG,OAAO,sBAAsB,EAAE,cAAc,CAAC;AAIpE,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;CAClB;AAOD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,cAAc,CAwF3E;AAID,MAAM,WAAW,eAAe;IAC9B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,KAAK,EAAE,OAAO,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,gBAAgB;IAC/B,oDAAoD;IACpD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uDAAuD;IACvD,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,cAAc,EACvB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,eAAe,CAAC,CAkH1B"}

package/dist/snapshot/differ.js

@@ -0,0 +1,194 @@
+/**
+ * Dual diff system — text (Myers) + image (pixel comparison).
+ *
+ * Text diff: Line-level Myers algorithm on snapshot strings.
+ * Image diff: Canvas-based pixel comparison in an isolated browser page.
+ */
+/**
+ * Myers diff algorithm (line-level).
+ * Returns unified diff format with +/- prefixes.
+ */
+export function diffSnapshots(before, after) {
+    const beforeLines = before.split("\n");
+    const afterLines = after.split("\n");
+    const n = beforeLines.length;
+    const m = afterLines.length;
+    const max = n + m;
+    // Shortcut: identical
+    if (before === after) {
+        return {
+            diff: beforeLines.map((l) => `  ${l}`).join("\n"),
+            additions: 0,
+            removals: 0,
+            unchanged: n,
+            changed: false,
+        };
+    }
+    // Myers shortest edit script
+    const v = { 1: { x: 0, history: [] } };
+    for (let d = 0; d <= max; d++) {
+        for (let k = -d; k <= d; k += 2) {
+            let path;
+            // Choose path: go down (insert) or go right (delete)
+            if (k === -d || (k !== d && v[k - 1].x < v[k + 1].x)) {
+                // Move down: insert from after
+                const prev = v[k + 1];
+                path = {
+                    x: prev.x,
+                    history: [...prev.history, { type: "add", line: afterLines[prev.x - k - 1] ?? "" }],
+                };
+            }
+            else {
+                // Move right: delete from before
+                const prev = v[k - 1];
+                path = {
+                    x: prev.x + 1,
+                    history: [...prev.history, { type: "remove", line: beforeLines[prev.x] ?? "" }],
+                };
+            }
+            // Follow diagonal (equal lines)
+            while (path.x < n && path.x - k < m && beforeLines[path.x] === afterLines[path.x - k]) {
+                path.history = [...path.history, { type: "equal", line: beforeLines[path.x] }];
+                path.x++;
+            }
+            // Check if we reached the end
+            if (path.x >= n && path.x - k >= m) {
+                let additions = 0;
+                let removals = 0;
+                let unchanged = 0;
+                const lines = [];
+                for (const entry of path.history) {
+                    switch (entry.type) {
+                        case "equal":
+                            lines.push(`  ${entry.line}`);
+                            unchanged++;
+                            break;
+                        case "add":
+                            lines.push(`+ ${entry.line}`);
+                            additions++;
+                            break;
+                        case "remove":
+                            lines.push(`- ${entry.line}`);
+                            removals++;
+                            break;
+                    }
+                }
+                return {
+                    diff: lines.join("\n"),
+                    additions,
+                    removals,
+                    unchanged,
+                    changed: additions > 0 || removals > 0,
+                };
+            }
+            v[k] = path;
+        }
+    }
+    // Should never reach here for valid inputs
+    return { diff: "", additions: 0, removals: 0, unchanged: 0, changed: false };
+}
+/**
+ * Pixel-level comparison of two screenshots.
+ * Opens an isolated page, loads images via intercepted routes,
+ * computes per-pixel color distance, generates diff PNG.
+ */
+export async function diffScreenshots(context, baseline, current, options = {}) {
+    const { threshold = 30, matchThreshold = 1.0 } = options;
+    const page = await context.newPage();
+    try {
+        // Intercept image routes to serve our buffers
+        await page.route("**/baseline.png", (route) => {
+            route.fulfill({
+                status: 200,
+                contentType: "image/png",
+                body: baseline,
+            });
+        });
+        await page.route("**/current.png", (route) => {
+            route.fulfill({
+                status: 200,
+                contentType: "image/png",
+                body: current,
+            });
+        });
+        // Canvas-based pixel diff in browser context
+        const result = await page.evaluate(async (thresh) => {
+            // Load images
+            const loadImage = (src) => new Promise((resolve, reject) => {
+                const img = new Image();
+                img.onload = () => resolve(img);
+                img.onerror = reject;
+                img.src = src;
+            });
+            const [img1, img2] = await Promise.all([
+                loadImage("/baseline.png"),
+                loadImage("/current.png"),
+            ]);
+            const width = Math.max(img1.width, img2.width);
+            const height = Math.max(img1.height, img2.height);
+            // Draw images to canvases
+            const canvas1 = document.createElement("canvas");
+            canvas1.width = width;
+            canvas1.height = height;
+            canvas1.getContext("2d").drawImage(img1, 0, 0);
+            const canvas2 = document.createElement("canvas");
+            canvas2.width = width;
+            canvas2.height = height;
+            canvas2.getContext("2d").drawImage(img2, 0, 0);
+            // Diff canvas
+            const diffCanvas = document.createElement("canvas");
+            diffCanvas.width = width;
+            diffCanvas.height = height;
+            const diffCtx = diffCanvas.getContext("2d");
+            const data1 = canvas1.getContext("2d").getImageData(0, 0, width, height).data;
+            const data2 = canvas2.getContext("2d").getImageData(0, 0, width, height).data;
+            const diffData = diffCtx.createImageData(width, height);
+            let changed = 0;
+            const totalPixels = width * height;
+            for (let i = 0; i < data1.length; i += 4) {
+                const dr = Math.abs(data1[i] - data2[i]);
+                const dg = Math.abs(data1[i + 1] - data2[i + 1]);
+                const db = Math.abs(data1[i + 2] - data2[i + 2]);
+                const dist = Math.sqrt(dr * dr + dg * dg + db * db);
+                if (dist > thresh) {
+                    // Highlight difference in red
+                    diffData.data[i] = 255;
+                    diffData.data[i + 1] = 0;
+                    diffData.data[i + 2] = 0;
+                    diffData.data[i + 3] = 200;
+                    changed++;
+                }
+                else {
+                    // Darken unchanged pixels
+                    diffData.data[i] = Math.floor(data2[i] * 0.3);
+                    diffData.data[i + 1] = Math.floor(data2[i + 1] * 0.3);
+                    diffData.data[i + 2] = Math.floor(data2[i + 2] * 0.3);
+                    diffData.data[i + 3] = 255;
+                }
+            }
+            diffCtx.putImageData(diffData, 0, 0);
+            // Export as data URL
+            const dataUrl = diffCanvas.toDataURL("image/png");
+            return {
+                totalPixels,
+                changedPixels: changed,
+                mismatchPercentage: (changed / totalPixels) * 100,
+                dataUrl,
+            };
+        }, threshold);
+        // Convert data URL to buffer
+        const base64Data = result.dataUrl.split(",")[1];
+        const diffImage = Buffer.from(base64Data, "base64");
+        return {
+            mismatchPercentage: result.mismatchPercentage,
+            match: result.mismatchPercentage <= matchThreshold,
+            diffImage,
+            totalPixels: result.totalPixels,
+            changedPixels: result.changedPixels,
+        };
+    }
+    finally {
+        await page.close();
+    }
+}
+//# sourceMappingURL=differ.js.map

package/dist/snapshot/differ.js.map

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

package/dist/snapshot/extractor.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Snapshot Extractor — Core engine for ARIA-based page snapshots.
+ *
+ * Uses Playwright's locator.ariaSnapshot() for the ARIA tree,
+ * then post-processes to add [ref=eN] tags for interactive elements.
+ * Optionally detects cursor-interactive elements without ARIA roles.
+ *
+ * Inspired by agent-browser's approach but with:
+ * - Per-snapshot ref counter (thread-safe, no global state)
+ * - Hybrid cursor detection
+ * - Semantic locators (getByRole) for robust element targeting
+ */
+import type { EnhancedSnapshot, SnapshotOptions } from "./types.js";
+type Page = import("rebrowser-playwright").Page;
+/**
+ * Generate an enhanced ARIA snapshot with ref annotations.
+ *
+ * Flow:
+ * 1. Get ARIA tree from Playwright's ariaSnapshot()
+ * 2. Parse each line, identify roles
+ * 3. Two-pass ref assignment (count first for dedup, then assign)
+ * 4. Optionally detect cursor-interactive elements
+ * 5. Build RefMap and annotated tree string
+ */
+export declare function getEnhancedSnapshot(page: Page, options?: SnapshotOptions): Promise<EnhancedSnapshot>;
+export {};
+//# sourceMappingURL=extractor.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"extractor.d.ts","sourceRoot":"","sources":["../../src/snapshot/extractor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAU,gBAAgB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAE5E,KAAK,IAAI,GAAG,OAAO,sBAAsB,EAAE,IAAI,CAAC;AAkLhD;;;;;;;;;GASG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,IAAI,EACV,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,gBAAgB,CAAC,CAyH3B"}