harnery 0.0.1 → 0.2.1

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

@@ -0,0 +1,193 @@
+import { type Page } from "playwright";
+import type { CookieJar } from "../cookies/index.js";
+import { type OverflowResult, type WidthResult } from "./layout.js";
+import { type CheckVisibilityOptions, type VisibilityResult } from "./visibility.js";
+/**
+ * Headless-Chromium wrapper for the `browse` command.
+ *
+ * Two persistence layers:
+ *   1. Persistent profile (Playwright's `launchPersistentContext`) keeps
+ *      browser state (localStorage, IndexedDB, login session) across runs.
+ *   2. Optional cookie jar, shared with `fetch`/`cookies` so a session
+ *      built up in one tool is visible to the others.
+ *
+ * Designed to be opened, used for one or more navigations, and closed.
+ * It is not a long-lived service. For multi-step workflows, the caller drives
+ * `navigate`/`click`/`fill` directly between `open()` and `close()`.
+ */
+export interface BrowserOptions {
+    /** Persistent profile dir. Default `~/.cache/harnery/browser-profile/`. Created if missing. */
+    profileDir?: string;
+    /** Launch headed (visible window). Default false. */
+    headed?: boolean;
+    /** Cookie jar to seed/sync with. Pass `null` to skip jar entirely. */
+    jar?: CookieJar | null;
+    /** Viewport. Default 1280x800. */
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    /** Default navigation timeout in ms. Default 30000. */
+    navigationTimeout?: number;
+    /**
+     * `wait_until` strategy for `navigate`. Default `"load"`.
+     * Use `"domcontentloaded"` for sites with long-running analytics scripts
+     * that never let `"load"` fire.
+     */
+    waitUntil?: "load" | "domcontentloaded" | "networkidle" | "commit";
+    /**
+     * If set, record network traffic to a HAR file at this absolute path.
+     * The HAR is finalized when `close()` is called.
+     */
+    recordHarPath?: string;
+    /**
+     * Optional callback returning extra headers to attach to every request,
+     * keyed by request URL. Consumers can inject extra HTTP headers per-URL
+     * via this callback (e.g., a Cloudflare-bypass header for specific zones).
+     */
+    extraHeaders?: (url: string) => Record<string, string>;
+}
+export interface NavigateResult {
+    url: string;
+    title: string;
+    status: number | null;
+}
+export interface ConsoleEvent {
+    type: string;
+    text: string;
+    location?: {
+        url: string;
+        lineNumber?: number;
+        columnNumber?: number;
+    };
+}
+export interface PageErrorEvent {
+    message: string;
+    stack?: string;
+}
+export interface FailedRequest {
+    url: string;
+    method: string;
+    failure: string;
+    resourceType: string;
+}
+export interface Diagnostics {
+    consoleEvents: ConsoleEvent[];
+    consoleErrors: ConsoleEvent[];
+    pageErrors: PageErrorEvent[];
+    failedRequests: FailedRequest[];
+    viewport: {
+        width: number;
+        height: number;
+    } | null;
+}
+export declare class Browser {
+    private opts;
+    private context;
+    private page;
+    readonly profileDir: string;
+    private consoleEvents;
+    private pageErrors;
+    private failedRequests;
+    constructor(opts?: BrowserOptions);
+    /** Lazy: caller-side helper to find the active page if mid-flow. */
+    get currentPage(): Page;
+    open(): Promise<void>;
+    /**
+     * Hook console + pageerror + requestfailed events. Called on `open()`
+     * before any navigation so we don't miss early-fired events.
+     */
+    private attachDiagnosticListeners;
+    /**
+     * Snapshot of every event captured since `open()`. Returned objects are
+     * copies, so callers can safely store them after `close()`.
+     */
+    diagnostics(): Diagnostics;
+    navigate(url: string): Promise<NavigateResult>;
+    /**
+     * Reload the current page. Preserves cookies + sessionStorage so callers can
+     * reproduce sessionStorage-restored UI state (e.g. drawers/modals that open
+     * automatically on reload, where Dialog auto-focus + Tooltip-on-focus may
+     * interact differently than the click-to-open path).
+     */
+    reload(): Promise<NavigateResult>;
+    /** Full-page PNG screenshot. Returns the byte count written. */
+    screenshot(path: string, opts?: {
+        fullPage?: boolean;
+    }): Promise<number>;
+    /**
+     * Plain-text snapshot of the document body. Suitable as a coarse "what's
+     * on screen" signal for LLM iteration loops. For richer extraction, use
+     * `htmlContent()` and pipe through a readability filter.
+     */
+    textSnapshot(): Promise<string>;
+    /** Raw outer HTML of the page (or a selector if provided). */
+    htmlContent(selector?: string): Promise<string>;
+    click(selector: string): Promise<void>;
+    fill(selector: string, value: string): Promise<void>;
+    press(key: string): Promise<void>;
+    waitForSelector(selector: string, timeout?: number): Promise<void>;
+    /** Evaluate JS in the page context. Caller is responsible for safety. */
+    evaluate<T = unknown>(script: string): Promise<T>;
+    /**
+     * Read the system clipboard via the page context. Grants `clipboard-read`
+     * to the page's origin first because Chromium gates `navigator.clipboard
+     * .readText()` behind a user-gesture + permission check; in headless
+     * Playwright there is no user gesture, so the permission grant is the
+     * substitute. Returns an empty string if the read returns nullish or
+     * throws (insecure context, focus race). Used by `browse --batch
+     * clipboard ...` to verify a UI Copy action end-to-end.
+     */
+    readClipboard(): Promise<string>;
+    /**
+     * Run occlusion checks on one or more selectors. For each, samples a grid
+     * of points inside the element's bounding rect and uses
+     * `document.elementFromPoint` to detect whether the target is the topmost
+     * paintable element at each sample. Catches the class of UI bugs where
+     * an element's rect IS in-viewport but a higher-z-index sibling is
+     * painting over it.
+     */
+    checkVisibility(selectors: string[], opts?: CheckVisibilityOptions): Promise<VisibilityResult[]>;
+    /** Inject annotation overlays for visibility results. Used before screenshot. */
+    annotateVisibility(results: VisibilityResult[]): Promise<void>;
+    /** Remove visibility annotation overlays. */
+    clearVisibilityAnnotations(): Promise<void>;
+    /**
+     * Measure each selector's bounding rect + viewport-fill + parent-fill
+     * ratios. Catches the class of mobile-layout bug where a table sits at
+     * (say) 85% viewport fill because of stacked padding: every per-element
+     * check passes, but the user sees too-narrow content.
+     */
+    checkWidth(selectors: string[]): Promise<WidthResult[]>;
+    /**
+     * Detect horizontal overflow at the document level. Returns viewport size,
+     * `document.scrollWidth`, and the top N elements protruding past the
+     * viewport's right edge. Catches the class of bug where a nav/table is
+     * wider than the viewport, forcing horizontal scroll on mobile.
+     */
+    checkOverflow(opts?: {
+        sampleLimit?: number;
+    }): Promise<OverflowResult>;
+    /** Inject annotation overlays for width + overflow results. Used before screenshot. */
+    annotateLayout(args: {
+        widths: WidthResult[];
+        overflow: OverflowResult | null;
+        widthThreshold: number;
+    }): Promise<void>;
+    /** Remove layout annotation overlays. */
+    clearLayoutAnnotations(): Promise<void>;
+    /**
+     * Inject a script that runs in every page context before page scripts
+     * execute. Useful for seeding localStorage before an SSR/CSR comparison;
+     * without this, state-dependent hydration mismatches are invisible to a
+     * clean-profile probe. Must be called after `open()` and before
+     * `navigate()`.
+     */
+    addInitScript(script: string): Promise<void>;
+    /**
+     * Sync cookies from the live context back into the jar (if one was provided),
+     * then tear everything down. Safe to call multiple times.
+     */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=client.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/lib/browser/client.ts"],"names":[],"mappings":"AAGA,OAAO,EAIL,KAAK,IAAI,EAGV,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,SAAS,EAAuB,MAAM,qBAAqB,CAAC;AAC1E,OAAO,EAKL,KAAK,cAAc,EACnB,KAAK,WAAW,EACjB,MAAM,aAAa,CAAC;AACrB,OAAO,EAIL,KAAK,sBAAsB,EAC3B,KAAK,gBAAgB,EACtB,MAAM,iBAAiB,CAAC;AAEzB;;;;;;;;;;;;GAYG;AAEH,MAAM,WAAW,cAAc;IAC7B,+FAA+F;IAC/F,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qDAAqD;IACrD,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,sEAAsE;IACtE,GAAG,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;IACvB,kCAAkC;IAClC,QAAQ,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC7C,uDAAuD;IACvD,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,GAAG,kBAAkB,GAAG,aAAa,GAAG,QAAQ,CAAC;IACnE;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACxD;AAED,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACxE;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,WAAW;IAC1B,aAAa,EAAE,YAAY,EAAE,CAAC;IAC9B,aAAa,EAAE,YAAY,EAAE,CAAC;IAC9B,UAAU,EAAE,cAAc,EAAE,CAAC;IAC7B,cAAc,EAAE,aAAa,EAAE,CAAC;IAChC,QAAQ,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CACpD;AAID,qBAAa,OAAO;IAQN,OAAO,CAAC,IAAI;IAPxB,OAAO,CAAC,OAAO,CAA+B;IAC9C,OAAO,CAAC,IAAI,CAAqB;IACjC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,OAAO,CAAC,aAAa,CAAsB;IAC3C,OAAO,CAAC,UAAU,CAAwB;IAC1C,OAAO,CAAC,cAAc,CAAuB;gBAEzB,IAAI,GAAE,cAAmB;IAI7C,oEAAoE;IACpE,IAAI,WAAW,IAAI,IAAI,CAKtB;IAEK,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAsC3B;;;OAGG;IACH,OAAO,CAAC,yBAAyB;IAwBjC;;;OAGG;IACH,WAAW,IAAI,WAAW;IAUpB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAUpD;;;;;OAKG;IACG,MAAM,IAAI,OAAO,CAAC,cAAc,CAAC;IAUvC,gEAAgE;IAC1D,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAO,GAAG,OAAO,CAAC,MAAM,CAAC;IAMlF;;;;OAIG;IACG,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC;IAKrC,8DAA8D;IACxD,WAAW,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAU/C,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAItC,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIpD,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIjC,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIxE,yEAAyE;IACnE,QAAQ,CAAC,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;IAIvD;;;;;;;;OAQG;IACG,aAAa,IAAI,OAAO,CAAC,MAAM,CAAC;IAmBtC;;;;;;;OAOG;IACG,eAAe,CACnB,SAAS,EAAE,MAAM,EAAE,EACnB,IAAI,GAAE,sBAA2B,GAChC,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAO9B,iFAAiF;IAC3E,kBAAkB,CAAC,OAAO,EAAE,gBAAgB,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAIpE,6CAA6C;IACvC,0BAA0B,IAAI,OAAO,CAAC,IAAI,CAAC;IAIjD;;;;;OAKG;IACG,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAI7D;;;;;OAKG;IACG,aAAa,CAAC,IAAI,GAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,OAAO,CAAC,cAAc,CAAC;IAMjF,uFAAuF;IACjF,cAAc,CAAC,IAAI,EAAE;QACzB,MAAM,EAAE,WAAW,EAAE,CAAC;QACtB,QAAQ,EAAE,cAAc,GAAG,IAAI,CAAC;QAChC,cAAc,EAAE,MAAM,CAAC;KACxB,GAAG,OAAO,CAAC,IAAI,CAAC;IAIjB,yCAAyC;IACnC,sBAAsB,IAAI,OAAO,CAAC,IAAI,CAAC;IAI7C;;;;;;OAMG;IACG,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKlD;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAgB7B"}

package/dist/lib/browser/client.js

@@ -0,0 +1,325 @@
+import { mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+import { chromium, } from "playwright";
+import { buildClearLayoutAnnotationsScript, buildLayoutAnnotateScript, buildOverflowCheck, buildWidthCheck, } from "./layout.js";
+import { buildAnnotateScript, buildClearAnnotationsScript, buildVisibilityCheck, } from "./visibility.js";
+const DEFAULT_PROFILE = resolve(homedir(), ".cache", "harnery", "browser-profile");
+export class Browser {
+    opts;
+    context = null;
+    page = null;
+    profileDir;
+    consoleEvents = [];
+    pageErrors = [];
+    failedRequests = [];
+    constructor(opts = {}) {
+        this.opts = opts;
+        this.profileDir = opts.profileDir ?? DEFAULT_PROFILE;
+    }
+    /** Lazy: caller-side helper to find the active page if mid-flow. */
+    get currentPage() {
+        if (!this.page) {
+            throw new Error("Browser not opened. Call open() first.");
+        }
+        return this.page;
+    }
+    async open() {
+        if (this.context)
+            return;
+        mkdirSync(this.profileDir, { recursive: true });
+        this.context = await chromium.launchPersistentContext(this.profileDir, {
+            headless: !this.opts.headed,
+            viewport: this.opts.viewport ?? { width: 1280, height: 800 },
+            ...(this.opts.recordHarPath
+                ? { recordHar: { path: this.opts.recordHarPath, mode: "full" } }
+                : {}),
+        });
+        this.context.setDefaultNavigationTimeout(this.opts.navigationTimeout ?? 30_000);
+        if (this.opts.jar) {
+            const jarCookies = this.opts.jar.list();
+            if (jarCookies.length > 0) {
+                await this.context.addCookies(jarCookies.map(toPWCookie));
+            }
+        }
+        // Caller-injected extraHeaders callback (e.g., for Cloudflare-bypass
+        // or custom auth headers). Per-request route handler so headers only
+        // attach when the callback returns non-empty.
+        const headersCb = this.opts.extraHeaders;
+        if (headersCb) {
+            await this.context.route("**/*", async (route, request) => {
+                const extra = headersCb(request.url());
+                if (Object.keys(extra).length === 0)
+                    return route.continue();
+                const headers = { ...request.headers(), ...extra };
+                return route.continue({ headers });
+            });
+        }
+        const pages = this.context.pages();
+        this.page = pages[0] ?? (await this.context.newPage());
+        this.attachDiagnosticListeners(this.page);
+    }
+    /**
+     * Hook console + pageerror + requestfailed events. Called on `open()`
+     * before any navigation so we don't miss early-fired events.
+     */
+    attachDiagnosticListeners(page) {
+        page.on("console", (msg) => {
+            const loc = msg.location();
+            this.consoleEvents.push({
+                type: msg.type(),
+                text: msg.text(),
+                location: loc.url
+                    ? { url: loc.url, lineNumber: loc.lineNumber, columnNumber: loc.columnNumber }
+                    : undefined,
+            });
+        });
+        page.on("pageerror", (err) => {
+            this.pageErrors.push({ message: err.message, stack: err.stack });
+        });
+        page.on("requestfailed", (req) => {
+            this.failedRequests.push({
+                url: req.url(),
+                method: req.method(),
+                failure: req.failure()?.errorText ?? "unknown",
+                resourceType: req.resourceType(),
+            });
+        });
+    }
+    /**
+     * Snapshot of every event captured since `open()`. Returned objects are
+     * copies, so callers can safely store them after `close()`.
+     */
+    diagnostics() {
+        return {
+            consoleEvents: [...this.consoleEvents],
+            consoleErrors: this.consoleEvents.filter((e) => e.type === "error"),
+            pageErrors: [...this.pageErrors],
+            failedRequests: [...this.failedRequests],
+            viewport: this.page?.viewportSize() ?? null,
+        };
+    }
+    async navigate(url) {
+        const page = this.currentPage;
+        const response = await page.goto(url, { waitUntil: this.opts.waitUntil ?? "load" });
+        return {
+            url: page.url(),
+            title: await page.title(),
+            status: response?.status() ?? null,
+        };
+    }
+    /**
+     * Reload the current page. Preserves cookies + sessionStorage so callers can
+     * reproduce sessionStorage-restored UI state (e.g. drawers/modals that open
+     * automatically on reload, where Dialog auto-focus + Tooltip-on-focus may
+     * interact differently than the click-to-open path).
+     */
+    async reload() {
+        const page = this.currentPage;
+        const response = await page.reload({ waitUntil: this.opts.waitUntil ?? "load" });
+        return {
+            url: page.url(),
+            title: await page.title(),
+            status: response?.status() ?? null,
+        };
+    }
+    /** Full-page PNG screenshot. Returns the byte count written. */
+    async screenshot(path, opts = {}) {
+        const page = this.currentPage;
+        const buf = await page.screenshot({ path, fullPage: opts.fullPage ?? true, type: "png" });
+        return buf.length;
+    }
+    /**
+     * Plain-text snapshot of the document body. Suitable as a coarse "what's
+     * on screen" signal for LLM iteration loops. For richer extraction, use
+     * `htmlContent()` and pipe through a readability filter.
+     */
+    async textSnapshot() {
+        const page = this.currentPage;
+        return await page.evaluate(() => document.body?.innerText ?? "");
+    }
+    /** Raw outer HTML of the page (or a selector if provided). */
+    async htmlContent(selector) {
+        const page = this.currentPage;
+        if (selector) {
+            const el = await page.$(selector);
+            if (!el)
+                throw new Error(`Selector matched nothing: ${selector}`);
+            return await el.evaluate((node) => node.outerHTML);
+        }
+        return await page.content();
+    }
+    async click(selector) {
+        await this.currentPage.click(selector);
+    }
+    async fill(selector, value) {
+        await this.currentPage.fill(selector, value);
+    }
+    async press(key) {
+        await this.currentPage.keyboard.press(key);
+    }
+    async waitForSelector(selector, timeout) {
+        await this.currentPage.waitForSelector(selector, timeout ? { timeout } : undefined);
+    }
+    /** Evaluate JS in the page context. Caller is responsible for safety. */
+    async evaluate(script) {
+        return await this.currentPage.evaluate(script);
+    }
+    /**
+     * Read the system clipboard via the page context. Grants `clipboard-read`
+     * to the page's origin first because Chromium gates `navigator.clipboard
+     * .readText()` behind a user-gesture + permission check; in headless
+     * Playwright there is no user gesture, so the permission grant is the
+     * substitute. Returns an empty string if the read returns nullish or
+     * throws (insecure context, focus race). Used by `browse --batch
+     * clipboard ...` to verify a UI Copy action end-to-end.
+     */
+    async readClipboard() {
+        if (!this.context)
+            throw new Error("Browser not opened. Call open() first.");
+        const url = this.currentPage.url();
+        try {
+            const origin = new URL(url).origin;
+            await this.context.grantPermissions(["clipboard-read"], { origin });
+        }
+        catch {
+            /* about:blank / data: URL, skip permission; evaluate may still work */
+        }
+        return await this.currentPage.evaluate(async () => {
+            try {
+                const text = await navigator.clipboard.readText();
+                return typeof text === "string" ? text : "";
+            }
+            catch {
+                return "";
+            }
+        });
+    }
+    /**
+     * Run occlusion checks on one or more selectors. For each, samples a grid
+     * of points inside the element's bounding rect and uses
+     * `document.elementFromPoint` to detect whether the target is the topmost
+     * paintable element at each sample. Catches the class of UI bugs where
+     * an element's rect IS in-viewport but a higher-z-index sibling is
+     * painting over it.
+     */
+    async checkVisibility(selectors, opts = {}) {
+        return await this.currentPage.evaluate(buildVisibilityCheck(), {
+            selectors,
+            sampleGrid: opts.sampleGrid ?? 3,
+        });
+    }
+    /** Inject annotation overlays for visibility results. Used before screenshot. */
+    async annotateVisibility(results) {
+        await this.currentPage.evaluate(buildAnnotateScript(), { results });
+    }
+    /** Remove visibility annotation overlays. */
+    async clearVisibilityAnnotations() {
+        await this.currentPage.evaluate(buildClearAnnotationsScript());
+    }
+    /**
+     * Measure each selector's bounding rect + viewport-fill + parent-fill
+     * ratios. Catches the class of mobile-layout bug where a table sits at
+     * (say) 85% viewport fill because of stacked padding: every per-element
+     * check passes, but the user sees too-narrow content.
+     */
+    async checkWidth(selectors) {
+        return await this.currentPage.evaluate(buildWidthCheck(), { selectors });
+    }
+    /**
+     * Detect horizontal overflow at the document level. Returns viewport size,
+     * `document.scrollWidth`, and the top N elements protruding past the
+     * viewport's right edge. Catches the class of bug where a nav/table is
+     * wider than the viewport, forcing horizontal scroll on mobile.
+     */
+    async checkOverflow(opts = {}) {
+        return await this.currentPage.evaluate(buildOverflowCheck(), {
+            sampleLimit: opts.sampleLimit ?? 5,
+        });
+    }
+    /** Inject annotation overlays for width + overflow results. Used before screenshot. */
+    async annotateLayout(args) {
+        await this.currentPage.evaluate(buildLayoutAnnotateScript(), args);
+    }
+    /** Remove layout annotation overlays. */
+    async clearLayoutAnnotations() {
+        await this.currentPage.evaluate(buildClearLayoutAnnotationsScript());
+    }
+    /**
+     * Inject a script that runs in every page context before page scripts
+     * execute. Useful for seeding localStorage before an SSR/CSR comparison;
+     * without this, state-dependent hydration mismatches are invisible to a
+     * clean-profile probe. Must be called after `open()` and before
+     * `navigate()`.
+     */
+    async addInitScript(script) {
+        if (!this.context)
+            throw new Error("Browser not opened. Call open() first.");
+        await this.context.addInitScript(script);
+    }
+    /**
+     * Sync cookies from the live context back into the jar (if one was provided),
+     * then tear everything down. Safe to call multiple times.
+     */
+    async close() {
+        if (!this.context)
+            return;
+        if (this.opts.jar) {
+            try {
+                const live = await this.context.cookies();
+                for (const c of live) {
+                    this.opts.jar.set(toJarCookie(c));
+                }
+            }
+            catch {
+                // Cookie persist is best-effort; never block close on it.
+            }
+        }
+        await this.context.close().catch(() => { });
+        this.context = null;
+        this.page = null;
+    }
+}
+// ---------------------------------------------------------------------------
+// Cookie shape conversion
+// ---------------------------------------------------------------------------
+function toPWCookie(c) {
+    // Playwright's PWCookie type requires sameSite to be a literal; undefined
+    // is not allowed. Default to "Lax" (matches Chromium's modern default).
+    return {
+        name: c.name,
+        value: c.value,
+        domain: c.domain,
+        path: c.path,
+        expires: c.expires,
+        httpOnly: c.httpOnly,
+        secure: c.secure,
+        sameSite: normalizeSameSite(c.sameSite) ?? "Lax",
+    };
+}
+function toJarCookie(c) {
+    return {
+        name: c.name,
+        value: c.value,
+        domain: c.domain,
+        path: c.path,
+        expires: c.expires,
+        httpOnly: c.httpOnly,
+        secure: c.secure,
+        sameSite: c.sameSite ?? undefined,
+        session: c.expires <= 0,
+        size: c.name.length + c.value.length,
+    };
+}
+function normalizeSameSite(s) {
+    if (!s)
+        return undefined;
+    const lower = s.toLowerCase();
+    if (lower === "strict")
+        return "Strict";
+    if (lower === "lax")
+        return "Lax";
+    if (lower === "none")
+        return "None";
+    return undefined;
+}

package/dist/lib/browser/dev-overlay.d.ts

@@ -0,0 +1,23 @@
+import type { Page } from "playwright";
+export interface DevOverlayError {
+    index: number;
+    kind: string;
+    code: string | null;
+    message: string;
+    callStack: string[];
+}
+export interface DevOverlayResult {
+    detected: boolean;
+    issuesCount: number;
+    errors: DevOverlayError[];
+}
+/**
+ * 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 declare function captureDevOverlay(page: Page, opts?: {
+    stepDelayMs?: number;
+}): Promise<DevOverlayResult>;
+//# sourceMappingURL=dev-overlay.d.ts.map

package/dist/lib/browser/dev-overlay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev-overlay.d.ts","sourceRoot":"","sources":["../../../src/lib/browser/dev-overlay.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAEvC,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,OAAO,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,eAAe,EAAE,CAAC;CAC3B;AAWD;;;;;GAKG;AACH,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,IAAI,EACV,IAAI,GAAE;IAAE,WAAW,CAAC,EAAE,MAAM,CAAA;CAAO,GAClC,OAAO,CAAC,gBAAgB,CAAC,CAsG3B"}