harnery 0.0.1 → 0.2.1

package/dist/lib/browser/dev-overlay.js

@@ -0,0 +1,153 @@
+// Capture Next.js dev-overlay issues (React errors + warnings) that don't
+// route through console.error and therefore don't surface via Playwright's
+// standard `page.on("console")` listener.
+//
+// Background: in Next.js 16 + React 19, hydration errors and most React
+// dev warnings fire through React DOM's `onCaughtError` / `onUncaughtError`
+// callbacks → next-devtools' `handleClientError` → a module-scoped
+// `errorQueue`. They never hit `console.error`, so neither Playwright's
+// CDP-backed listener nor an early init-script wrapper can see them. The
+// only externally-observable surface is the dev overlay UI inside the
+// `<nextjs-portal>` shadow root.
+//
+// Strategy: detect the shadow host, click the "Open issues overlay" badge
+// when present, iterate the dialog's error pages via the prev/next buttons,
+// scrape each error's kind + code + message + call-stack, then close the
+// overlay. Returns `{ detected, issuesCount, errors }`.
+/**
+ * Detect a Next.js dev overlay on the current page and, if present, capture
+ * every queued issue. Idempotent, safe to call multiple times. The function
+ * closes the overlay on exit; if it crashes partway, the overlay may be left
+ * open (subsequent calls will recover).
+ */
+export async function captureDevOverlay(page, opts = {}) {
+    const stepDelay = opts.stepDelayMs ?? 400;
+    const detected = await page.evaluate(() => !!document.querySelector("nextjs-portal"));
+    if (!detected)
+        return { detected: false, issuesCount: 0, errors: [] };
+    // next-devtools dispatches errors to the overlay via queueMicrotask, so an
+    // error fired in the immediately-preceding evaluate() may not yet have
+    // propagated. Wait briefly for the badge to materialize before declaring
+    // "no issues", capped so the no-error path doesn't pay much.
+    await page
+        .waitForFunction(() => {
+        const portal = document.querySelector("nextjs-portal");
+        return !!portal?.shadowRoot?.querySelector("[data-issues-open]");
+    }, null, { timeout: 1_500 })
+        .catch(() => { });
+    // Click the issues-open badge if present. Its mere existence signals issues > 0;
+    // the badge's own text ("12 Issues" = index "1" + count "2 Issues" rendered side-
+    // by-side) isn't a reliable count. Authoritative total comes from the dialog's
+    // [data-nextjs-dialog-header-total-count] span after open.
+    const opened = await page.evaluate(() => {
+        const portal = document.querySelector("nextjs-portal");
+        const shadow = portal?.shadowRoot;
+        if (!shadow)
+            return false;
+        const btn = shadow.querySelector("[data-issues-open]");
+        if (!btn)
+            return false;
+        btn.click();
+        return true;
+    });
+    if (!opened) {
+        return { detected: true, issuesCount: 0, errors: [] };
+    }
+    // Wait for the dialog to render
+    await page.waitForFunction(() => {
+        const portal = document.querySelector("nextjs-portal");
+        const shadow = portal?.shadowRoot;
+        return !!shadow?.querySelector("[data-nextjs-dialog]");
+    }, null, { timeout: 4_000 });
+    // Read the canonical total from the dialog
+    const total = await page.evaluate(() => {
+        const portal = document.querySelector("nextjs-portal");
+        const shadow = portal?.shadowRoot;
+        const el = shadow?.querySelector("[data-nextjs-dialog-header-total-count]");
+        const n = Number((el?.textContent || "").trim());
+        return Number.isFinite(n) && n > 0 ? n : 1;
+    });
+    const raw = [];
+    const expected = total;
+    for (let i = 0; i < expected; i++) {
+        const error = await readCurrent(page);
+        if (error)
+            raw.push(error);
+        if (i < expected - 1) {
+            const advanced = await advance(page);
+            if (!advanced)
+                break;
+            await new Promise((r) => setTimeout(r, stepDelay));
+        }
+    }
+    // Close the overlay (click the collapse button or fall back to Esc)
+    await page.evaluate(() => {
+        const portal = document.querySelector("nextjs-portal");
+        const shadow = portal?.shadowRoot;
+        const close = shadow?.querySelector("[data-issues-collapse]");
+        if (close)
+            close.click();
+    });
+    await page.keyboard.press("Escape").catch(() => { });
+    const errors = raw.map((r, idx) => {
+        const message = stripPrefix(r.headerText, r.kind).trim();
+        return {
+            index: Number(r.index.replace(/[^0-9]/g, "")) || idx + 1,
+            kind: r.kind,
+            code: r.code,
+            message,
+            callStack: r.framesText,
+        };
+    });
+    return { detected: true, issuesCount: total, errors };
+}
+async function readCurrent(page) {
+    return page.evaluate(() => {
+        const portal = document.querySelector("nextjs-portal");
+        const shadow = portal?.shadowRoot;
+        if (!shadow)
+            return null;
+        const dialog = shadow.querySelector("[data-nextjs-dialog]");
+        if (!dialog)
+            return null;
+        const text = (el) => (el?.textContent || "").replace(/\s+/g, " ").trim();
+        const indexSpan = shadow.querySelector("[data-nextjs-dialog-error-index]");
+        const label = shadow.querySelector("[data-nextjs-error-label-group]");
+        const codeEl = shadow.querySelector("[data-nextjs-error-code]");
+        const header = shadow.querySelector("[data-nextjs-dialog-header]");
+        const body = shadow.querySelector("[data-nextjs-dialog-body]");
+        const frameEls = shadow.querySelectorAll("[data-nextjs-call-stack-frame]");
+        const frames = [];
+        for (const f of Array.from(frameEls)) {
+            const t = text(f);
+            if (t)
+                frames.push(t);
+        }
+        return {
+            index: text(indexSpan) || "1",
+            kind: text(label) || "Issue",
+            code: codeEl?.getAttribute("data-nextjs-error-code") ?? null,
+            headerText: text(header),
+            bodyText: text(body),
+            framesText: frames,
+        };
+    });
+}
+async function advance(page) {
+    return page.evaluate(() => {
+        const portal = document.querySelector("nextjs-portal");
+        const shadow = portal?.shadowRoot;
+        const next = shadow?.querySelector("[data-nextjs-dialog-error-next]");
+        if (!next || next.disabled)
+            return false;
+        next.click();
+        return true;
+    });
+}
+function stripPrefix(s, prefix) {
+    if (!prefix)
+        return s;
+    if (s.startsWith(prefix))
+        return s.slice(prefix.length);
+    return s;
+}

package/dist/lib/browser/index.d.ts

@@ -0,0 +1,5 @@
+export { Browser, type BrowserOptions, type ConsoleEvent, type Diagnostics, type FailedRequest, type NavigateResult, type PageErrorEvent, } from "./client.js";
+export { captureDevOverlay, type DevOverlayError, type DevOverlayResult, } from "./dev-overlay.js";
+export type { OverflowElement, OverflowResult, WidthResult, } from "./layout.js";
+export type { CheckVisibilityOptions, VisibilityResult, VisibilitySample, } from "./visibility.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/lib/browser/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/browser/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,OAAO,EACP,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,cAAc,GACpB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,iBAAiB,EACjB,KAAK,eAAe,EACpB,KAAK,gBAAgB,GACtB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EACV,eAAe,EACf,cAAc,EACd,WAAW,GACZ,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,sBAAsB,EACtB,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,iBAAiB,CAAC"}

package/dist/lib/browser/index.js

@@ -0,0 +1,2 @@
+export { Browser, } from "./client.js";
+export { captureDevOverlay, } from "./dev-overlay.js";

package/dist/lib/browser/layout.d.ts

@@ -0,0 +1,79 @@
+export interface WidthResult {
+    selector: string;
+    found: boolean;
+    rect: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    parentTag: string;
+    parentWidth: number;
+    viewportWidth: number;
+    /** `rect.width / viewportWidth`, rounded to 3 decimals. */
+    viewportFill: number;
+    /** `rect.width / parentWidth`, rounded to 3 decimals. 0 when no parent. */
+    parentFill: number;
+}
+/** One element protruding past the viewport. */
+export interface OverflowElement {
+    tagName: string;
+    className: string;
+    id: string;
+    rect: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /** Pixels this element's own width exceeds the viewport. 0 if it fits. */
+    widthOverflowPx: number;
+    /** Pixels this element's right edge extends past the viewport's right. */
+    rightOverflowPx: number;
+}
+export interface OverflowResult {
+    viewport: {
+        width: number;
+        height: number;
+    };
+    documentScrollWidth: number;
+    hasHorizontalOverflow: boolean;
+    /** documentScrollWidth - viewport.width. Negative/zero means no overflow. */
+    overflowPx: number;
+    /** Top N elements whose own width exceeds viewport, ranked desc. */
+    widerThanViewport: OverflowElement[];
+    /** Top N elements whose right edge protrudes past viewport (but own width fits). */
+    rightOverflow: OverflowElement[];
+}
+/**
+ * Build the JS function passed to `page.evaluate`. Returns a function
+ * reference (not a string) so Playwright serializes args properly.
+ */
+export declare function buildWidthCheck(): (args: {
+    selectors: string[];
+}) => WidthResult[];
+/**
+ * Build the JS function for overflow detection. Sweeps every element for
+ * widthOverflow (own width > viewport) and rightOverflow (right-edge past
+ * viewport). Caps each list at `sampleLimit` so a degenerate document with
+ * thousands of overflowing elements doesn't blow up the JSON envelope.
+ */
+export declare function buildOverflowCheck(): (args: {
+    sampleLimit: number;
+}) => OverflowResult;
+/**
+ * Annotate width-check + overflow results onto the live page so the captured
+ * screenshot carries the diagnostic overlay. Separate root from
+ * visibility.ts's annotations so both can coexist on the same screenshot.
+ *
+ * Width targets: green if `viewportFill >= widthThreshold`, red otherwise.
+ * Overflow: dashed amber line at the viewport's right edge + amber boxes
+ * around each protruding element.
+ */
+export declare function buildLayoutAnnotateScript(): (args: {
+    widths: WidthResult[];
+    overflow: OverflowResult | null;
+    widthThreshold: number;
+}) => void;
+export declare function buildClearLayoutAnnotationsScript(): () => void;
+//# sourceMappingURL=layout.d.ts.map

package/dist/lib/browser/layout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"layout.d.ts","sourceRoot":"","sources":["../../../src/lib/browser/layout.ts"],"names":[],"mappings":"AAgBA,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,IAAI,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9D,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,2DAA2D;IAC3D,YAAY,EAAE,MAAM,CAAC;IACrB,2EAA2E;IAC3E,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,gDAAgD;AAChD,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9D,0EAA0E;IAC1E,eAAe,EAAE,MAAM,CAAC;IACxB,0EAA0E;IAC1E,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5C,mBAAmB,EAAE,MAAM,CAAC;IAC5B,qBAAqB,EAAE,OAAO,CAAC;IAC/B,6EAA6E;IAC7E,UAAU,EAAE,MAAM,CAAC;IACnB,oEAAoE;IACpE,iBAAiB,EAAE,eAAe,EAAE,CAAC;IACrC,oFAAoF;IACpF,aAAa,EAAE,eAAe,EAAE,CAAC;CAClC;AAED;;;GAGG;AACH,wBAAgB,eAAe,IAAI,CAAC,IAAI,EAAE;IAAE,SAAS,EAAE,MAAM,EAAE,CAAA;CAAE,KAAK,WAAW,EAAE,CA4ClF;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,IAAI,CAAC,IAAI,EAAE;IAAE,WAAW,EAAE,MAAM,CAAA;CAAE,KAAK,cAAc,CAgEtF;AAED;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,IAAI,CAAC,IAAI,EAAE;IAClD,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,QAAQ,EAAE,cAAc,GAAG,IAAI,CAAC;IAChC,cAAc,EAAE,MAAM,CAAC;CACxB,KAAK,IAAI,CA6FT;AAED,wBAAgB,iCAAiC,IAAI,MAAM,IAAI,CAI9D"}

package/dist/lib/browser/layout.js

@@ -0,0 +1,220 @@
+// Width-fill + horizontal-overflow check primitives for `harn browse`.
+//
+// Companions to visibility.ts: visibility catches "the element is hidden /
+// occluded"; layout catches "the element is the wrong size or in the wrong
+// place." The bug this exists to catch: a `<table>` at 85% viewport fill
+// (correct CSS-visibility, no occlusion, where every existing per-element check
+// passes), or a `<nav>` overflowing the viewport's right edge by 92px and
+// triggering horizontal scroll on mobile.
+//
+// Two independent checks, surfaced together because they're often co-symptoms
+// of the same root cause (stacked padding, missing flex-wrap, fixed widths
+// that don't shrink on narrow viewports):
+//
+//   --check-width <selector>      assert one element's width is >= N% of viewport
+//   --check-overflow              assert document has no horizontal overflow
+/**
+ * Build the JS function passed to `page.evaluate`. Returns a function
+ * reference (not a string) so Playwright serializes args properly.
+ */
+export function buildWidthCheck() {
+    return ({ selectors }) => {
+        const vw = window.innerWidth;
+        function checkOne(selector) {
+            const empty = {
+                selector,
+                found: false,
+                rect: { x: 0, y: 0, width: 0, height: 0 },
+                parentTag: "",
+                parentWidth: 0,
+                viewportWidth: vw,
+                viewportFill: 0,
+                parentFill: 0,
+            };
+            const el = document.querySelector(selector);
+            if (!(el instanceof Element))
+                return empty;
+            const rect = el.getBoundingClientRect();
+            const parent = el.parentElement;
+            const parentRect = parent ? parent.getBoundingClientRect() : null;
+            const viewportFill = vw > 0 ? rect.width / vw : 0;
+            const parentFill = parentRect && parentRect.width > 0 ? rect.width / parentRect.width : 0;
+            return {
+                selector,
+                found: true,
+                rect: {
+                    x: Math.round(rect.x),
+                    y: Math.round(rect.y),
+                    width: Math.round(rect.width),
+                    height: Math.round(rect.height),
+                },
+                parentTag: parent ? parent.tagName.toLowerCase() : "",
+                parentWidth: parentRect ? Math.round(parentRect.width) : 0,
+                viewportWidth: vw,
+                viewportFill: Math.round(viewportFill * 1000) / 1000,
+                parentFill: Math.round(parentFill * 1000) / 1000,
+            };
+        }
+        return selectors.map(checkOne);
+    };
+}
+/**
+ * Build the JS function for overflow detection. Sweeps every element for
+ * widthOverflow (own width > viewport) and rightOverflow (right-edge past
+ * viewport). Caps each list at `sampleLimit` so a degenerate document with
+ * thousands of overflowing elements doesn't blow up the JSON envelope.
+ */
+export function buildOverflowCheck() {
+    return ({ sampleLimit }) => {
+        const vw = window.innerWidth;
+        const vh = window.innerHeight;
+        const docScrollW = document.documentElement.scrollWidth;
+        const tolerance = 1;
+        const widerThanViewport = [];
+        const rightOverflow = [];
+        const all = document.querySelectorAll("*");
+        for (let i = 0; i < all.length; i++) {
+            const el = all[i];
+            if (!el)
+                continue;
+            const r = el.getBoundingClientRect();
+            if (r.width <= 0 || r.height <= 0)
+                continue;
+            const widthOverflow = r.width - vw;
+            const rightOverflowPx = r.right - vw;
+            const cls = typeof el.className === "string"
+                ? el.className.slice(0, 200)
+                : (el.getAttribute("class") ?? "");
+            const rect = {
+                x: Math.round(r.x),
+                y: Math.round(r.y),
+                width: Math.round(r.width),
+                height: Math.round(r.height),
+            };
+            if (widthOverflow > tolerance) {
+                widerThanViewport.push({
+                    tagName: el.tagName.toLowerCase(),
+                    className: cls,
+                    id: el.id || "",
+                    rect,
+                    widthOverflowPx: Math.round(widthOverflow),
+                    rightOverflowPx: Math.max(0, Math.round(rightOverflowPx)),
+                });
+            }
+            else if (rightOverflowPx > tolerance) {
+                rightOverflow.push({
+                    tagName: el.tagName.toLowerCase(),
+                    className: cls,
+                    id: el.id || "",
+                    rect,
+                    widthOverflowPx: 0,
+                    rightOverflowPx: Math.round(rightOverflowPx),
+                });
+            }
+        }
+        widerThanViewport.sort((a, b) => b.widthOverflowPx - a.widthOverflowPx);
+        rightOverflow.sort((a, b) => b.rightOverflowPx - a.rightOverflowPx);
+        return {
+            viewport: { width: vw, height: vh },
+            documentScrollWidth: docScrollW,
+            hasHorizontalOverflow: docScrollW > vw + tolerance,
+            overflowPx: docScrollW - vw,
+            widerThanViewport: widerThanViewport.slice(0, sampleLimit),
+            rightOverflow: rightOverflow.slice(0, sampleLimit),
+        };
+    };
+}
+/**
+ * Annotate width-check + overflow results onto the live page so the captured
+ * screenshot carries the diagnostic overlay. Separate root from
+ * visibility.ts's annotations so both can coexist on the same screenshot.
+ *
+ * Width targets: green if `viewportFill >= widthThreshold`, red otherwise.
+ * Overflow: dashed amber line at the viewport's right edge + amber boxes
+ * around each protruding element.
+ */
+export function buildLayoutAnnotateScript() {
+    return ({ widths, overflow, widthThreshold }) => {
+        const ROOT_ID = "__bp-check-layout-annotations__";
+        document.getElementById(ROOT_ID)?.remove();
+        const root = document.createElement("div");
+        root.id = ROOT_ID;
+        root.style.cssText = "position: fixed; inset: 0; pointer-events: none; z-index: 2147483646;";
+        document.body.appendChild(root);
+        const drawBox = (rect, color, label, labelPos = "top") => {
+            const box = document.createElement("div");
+            box.style.cssText = `
+        position: absolute;
+        left: ${rect.x}px;
+        top: ${rect.y}px;
+        width: ${rect.width}px;
+        height: ${rect.height}px;
+        border: 2px solid ${color};
+        box-sizing: border-box;
+        background: ${color}1a;
+        pointer-events: none;
+      `;
+            const tag = document.createElement("div");
+            tag.textContent = label;
+            tag.style.cssText = `
+        position: absolute;
+        left: 0;
+        ${labelPos === "top" ? "top: -18px;" : "bottom: -18px;"}
+        background: ${color};
+        color: #fff;
+        font: 12px/1.4 -apple-system, system-ui, sans-serif;
+        padding: 1px 6px;
+        border-radius: 3px;
+        white-space: nowrap;
+        pointer-events: none;
+      `;
+            box.appendChild(tag);
+            root.appendChild(box);
+        };
+        for (const w of widths) {
+            if (!w.found)
+                continue;
+            const passing = w.viewportFill >= widthThreshold;
+            drawBox(w.rect, passing ? "#10b981" : "#ef4444", `${w.selector}  vfill=${(w.viewportFill * 100).toFixed(0)}%`);
+        }
+        if (overflow) {
+            const edgeLine = document.createElement("div");
+            edgeLine.style.cssText = `
+        position: absolute;
+        left: ${overflow.viewport.width}px;
+        top: 0;
+        width: 0;
+        height: 100vh;
+        border-left: 2px dashed #f59e0b;
+        pointer-events: none;
+      `;
+            root.appendChild(edgeLine);
+            const edgeLabel = document.createElement("div");
+            edgeLabel.textContent = `viewport edge (${overflow.viewport.width}px)`;
+            edgeLabel.style.cssText = `
+        position: absolute;
+        left: ${overflow.viewport.width + 4}px;
+        top: 4px;
+        background: #f59e0b;
+        color: #fff;
+        font: 12px/1.4 -apple-system, system-ui, sans-serif;
+        padding: 1px 6px;
+        border-radius: 3px;
+        white-space: nowrap;
+        pointer-events: none;
+      `;
+            root.appendChild(edgeLabel);
+            for (const o of [...overflow.widerThanViewport, ...overflow.rightOverflow]) {
+                const label = o.widthOverflowPx > 0
+                    ? `${o.tagName}  +${o.widthOverflowPx}px wider than viewport`
+                    : `${o.tagName}  +${o.rightOverflowPx}px past right edge`;
+                drawBox(o.rect, "#f59e0b", label, "bottom");
+            }
+        }
+    };
+}
+export function buildClearLayoutAnnotationsScript() {
+    return () => {
+        document.getElementById("__bp-check-layout-annotations__")?.remove();
+    };
+}

package/dist/lib/browser/visibility.d.ts

@@ -0,0 +1,86 @@
+export interface VisibilitySample {
+    x: number;
+    y: number;
+    status: "visible" | "occluded" | "outside-viewport" | "no-element";
+    occluderTag?: string;
+    occluderClass?: string;
+}
+export type CssHiddenReason = "display-none" | "visibility-hidden" | "opacity-zero" | "content-visibility-hidden" | "pointer-events-none-with-opacity-zero" | "unknown";
+export interface VisibilityResult {
+    selector: string;
+    found: boolean;
+    inViewport: boolean;
+    partiallyInViewport: boolean;
+    rect: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /**
+     * Pure CSS-level visibility via `Element.checkVisibility()` with opacity +
+     * visibility + content-visibility checks enabled, plus an ancestor walk
+     * to identify which property is hiding the element. Catches the class of
+     * bug where an element is in layout (has rect, is in viewport) but is
+     * painted with opacity:0 / visibility:hidden / display:none: invisible
+     * to the user but invisible to occlusion-only checks too.
+     */
+    cssVisible: boolean;
+    /** Which property+element actually hides it. Null when cssVisible=true. */
+    hiddenBy: {
+        reason: CssHiddenReason;
+        ancestorTag: string;
+        ancestorClass: string;
+        ancestorId: string;
+        propertyValue: string;
+    } | null;
+    /** Fraction of in-viewport samples where the target (or a descendant) was the topmost element. 0 = fully occluded, 1 = fully visible. Always 0 when cssVisible=false (sampling skipped). */
+    visibleRatio: number;
+    samples: VisibilitySample[];
+    occludedBy: {
+        tagName: string;
+        className: string;
+        id: string;
+        outerHTML: string;
+        computedStyles: {
+            position?: string;
+            zIndex?: string;
+            backgroundColor?: string;
+        };
+        rect: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+    } | null;
+    elementOuterHTML: string;
+}
+export interface CheckVisibilityOptions {
+    /** Grid size: sampleGrid × sampleGrid points across the target's rect. Default 3 (9 samples). */
+    sampleGrid?: number;
+}
+/**
+ * Build the JS function passed to Playwright's `page.evaluate`. Returns
+ * a function reference (not a string) so Playwright serializes args
+ * properly. Caller invokes via `page.evaluate(fn, { selectors, sampleGrid })`.
+ */
+export declare function buildVisibilityCheck(): (args: {
+    selectors: string[];
+    sampleGrid: number;
+}) => VisibilityResult[];
+/**
+ * Build a script that injects overlay rectangles for each visibility result.
+ * Green border = target, red border = dominant occluder. Caller injects via
+ * `page.evaluate`, takes the screenshot, then clears via
+ * `buildClearAnnotationsScript`. Boxes are absolutely positioned at the
+ * target/occluder's `getBoundingClientRect()` location, so they survive
+ * scroll changes between sample-time and screenshot-time only if nothing
+ * has scrolled. The recommended flow is sample → annotate → screenshot →
+ * clear without intervening scrolls.
+ */
+export declare function buildAnnotateScript(): (args: {
+    results: VisibilityResult[];
+}) => void;
+export declare function buildClearAnnotationsScript(): () => void;
+//# sourceMappingURL=visibility.d.ts.map

package/dist/lib/browser/visibility.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"visibility.d.ts","sourceRoot":"","sources":["../../../src/lib/browser/visibility.ts"],"names":[],"mappings":"AAcA,MAAM,WAAW,gBAAgB;IAC/B,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,MAAM,EAAE,SAAS,GAAG,UAAU,GAAG,kBAAkB,GAAG,YAAY,CAAC;IACnE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,MAAM,eAAe,GACvB,cAAc,GACd,mBAAmB,GACnB,cAAc,GACd,2BAA2B,GAC3B,uCAAuC,GACvC,SAAS,CAAC;AAEd,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,UAAU,EAAE,OAAO,CAAC;IACpB,mBAAmB,EAAE,OAAO,CAAC;IAC7B,IAAI,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9D;;;;;;;OAOG;IACH,UAAU,EAAE,OAAO,CAAC;IACpB,2EAA2E;IAC3E,QAAQ,EAAE;QACR,MAAM,EAAE,eAAe,CAAC;QACxB,WAAW,EAAE,MAAM,CAAC;QACpB,aAAa,EAAE,MAAM,CAAC;QACtB,UAAU,EAAE,MAAM,CAAC;QACnB,aAAa,EAAE,MAAM,CAAC;KACvB,GAAG,IAAI,CAAC;IACT,4LAA4L;IAC5L,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC5B,UAAU,EAAE;QACV,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,EAAE,MAAM,CAAC;QAClB,EAAE,EAAE,MAAM,CAAC;QACX,SAAS,EAAE,MAAM,CAAC;QAClB,cAAc,EAAE;YAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;YAAC,MAAM,CAAC,EAAE,MAAM,CAAC;YAAC,eAAe,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;QACjF,IAAI,EAAE;YAAE,CAAC,EAAE,MAAM,CAAC;YAAC,CAAC,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAA;SAAE,CAAC;KAC/D,GAAG,IAAI,CAAC;IACT,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,sBAAsB;IACrC,iGAAiG;IACjG,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,IAAI,CAAC,IAAI,EAAE;IAC7C,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;CACpB,KAAK,gBAAgB,EAAE,CAqPvB;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,IAAI,CAAC,IAAI,EAAE;IAAE,OAAO,EAAE,gBAAgB,EAAE,CAAA;CAAE,KAAK,IAAI,CA2ErF;AAED,wBAAgB,2BAA2B,IAAI,MAAM,IAAI,CAIxD"}