@hera-al/browser-server 1.0.0

package/dist/playwright/pw-tools-core.downloads.js

@@ -0,0 +1,186 @@
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { ensurePageState, getPageForTargetId, refLocator, restoreRoleRefsForTarget, } from "./pw-session.js";
+import { bumpDialogArmId, bumpDownloadArmId, bumpUploadArmId, normalizeTimeoutMs, requireRef, toAIFriendlyError, } from "./pw-tools-core.shared.js";
+function buildTempDownloadPath(fileName) {
+    const id = crypto.randomUUID();
+    const safeName = fileName.trim() ? fileName.trim() : "download.bin";
+    return path.join(os.tmpdir(), "grabmeabeer", "downloads", `${id}-${safeName}`);
+}
+function createPageDownloadWaiter(page, timeoutMs) {
+    let done = false;
+    let timer;
+    let handler;
+    const cleanup = () => {
+        if (timer) {
+            clearTimeout(timer);
+        }
+        timer = undefined;
+        if (handler) {
+            page.off("download", handler);
+            handler = undefined;
+        }
+    };
+    const promise = new Promise((resolve, reject) => {
+        handler = (download) => {
+            if (done) {
+                return;
+            }
+            done = true;
+            cleanup();
+            resolve(download);
+        };
+        page.on("download", handler);
+        timer = setTimeout(() => {
+            if (done) {
+                return;
+            }
+            done = true;
+            cleanup();
+            reject(new Error("Timeout waiting for download"));
+        }, timeoutMs);
+    });
+    return {
+        promise,
+        cancel: () => {
+            if (done) {
+                return;
+            }
+            done = true;
+            cleanup();
+        },
+    };
+}
+export async function armFileUploadViaPlaywright(opts) {
+    const page = await getPageForTargetId(opts);
+    const state = ensurePageState(page);
+    const timeout = Math.max(500, Math.min(120_000, opts.timeoutMs ?? 120_000));
+    state.armIdUpload = bumpUploadArmId();
+    const armId = state.armIdUpload;
+    void page
+        .waitForEvent("filechooser", { timeout })
+        .then(async (fileChooser) => {
+        if (state.armIdUpload !== armId) {
+            return;
+        }
+        if (!opts.paths?.length) {
+            try {
+                await page.keyboard.press("Escape");
+            }
+            catch {
+                // Best-effort.
+            }
+            return;
+        }
+        await fileChooser.setFiles(opts.paths);
+        try {
+            const input = typeof fileChooser.element === "function"
+                ? await Promise.resolve(fileChooser.element())
+                : null;
+            if (input) {
+                await input.evaluate((el) => {
+                    el.dispatchEvent(new Event("input", { bubbles: true }));
+                    el.dispatchEvent(new Event("change", { bubbles: true }));
+                });
+            }
+        }
+        catch {
+            // Best-effort
+        }
+    })
+        .catch(() => {
+        // Ignore timeouts
+    });
+}
+export async function armDialogViaPlaywright(opts) {
+    const page = await getPageForTargetId(opts);
+    const state = ensurePageState(page);
+    const timeout = normalizeTimeoutMs(opts.timeoutMs, 120_000);
+    state.armIdDialog = bumpDialogArmId();
+    const armId = state.armIdDialog;
+    void page
+        .waitForEvent("dialog", { timeout })
+        .then(async (dialog) => {
+        if (state.armIdDialog !== armId) {
+            return;
+        }
+        if (opts.accept) {
+            await dialog.accept(opts.promptText);
+        }
+        else {
+            await dialog.dismiss();
+        }
+    })
+        .catch(() => {
+        // Ignore timeouts
+    });
+}
+export async function waitForDownloadViaPlaywright(opts) {
+    const page = await getPageForTargetId(opts);
+    const state = ensurePageState(page);
+    const timeout = normalizeTimeoutMs(opts.timeoutMs, 120_000);
+    state.armIdDownload = bumpDownloadArmId();
+    const armId = state.armIdDownload;
+    const waiter = createPageDownloadWaiter(page, timeout);
+    try {
+        const download = (await waiter.promise);
+        if (state.armIdDownload !== armId) {
+            throw new Error("Download was superseded by another waiter");
+        }
+        const suggested = download.suggestedFilename?.() || "download.bin";
+        const outPath = opts.path?.trim() || buildTempDownloadPath(suggested);
+        await fs.mkdir(path.dirname(outPath), { recursive: true });
+        await download.saveAs?.(outPath);
+        return {
+            url: download.url?.() || "",
+            suggestedFilename: suggested,
+            path: path.resolve(outPath),
+        };
+    }
+    catch (err) {
+        waiter.cancel();
+        throw err;
+    }
+}
+export async function downloadViaPlaywright(opts) {
+    const page = await getPageForTargetId(opts);
+    const state = ensurePageState(page);
+    restoreRoleRefsForTarget({ cdpUrl: opts.cdpUrl, targetId: opts.targetId, page });
+    const timeout = normalizeTimeoutMs(opts.timeoutMs, 120_000);
+    const ref = requireRef(opts.ref);
+    const outPath = String(opts.path ?? "").trim();
+    if (!outPath) {
+        throw new Error("path is required");
+    }
+    state.armIdDownload = bumpDownloadArmId();
+    const armId = state.armIdDownload;
+    const waiter = createPageDownloadWaiter(page, timeout);
+    try {
+        const locator = refLocator(page, ref);
+        try {
+            await locator.click({ timeout });
+        }
+        catch (err) {
+            throw toAIFriendlyError(err, ref);
+        }
+        const download = (await waiter.promise);
+        if (state.armIdDownload !== armId) {
+            throw new Error("Download was superseded by another waiter");
+        }
+        const suggested = download.suggestedFilename?.() || "download.bin";
+        await fs.mkdir(path.dirname(outPath), { recursive: true });
+        await download.saveAs?.(outPath);
+        return {
+            url: download.url?.() || "",
+            suggestedFilename: suggested,
+            path: path.resolve(outPath),
+        };
+    }
+    catch (err) {
+        waiter.cancel();
+        throw err;
+    }
+}
+//# sourceMappingURL=pw-tools-core.downloads.js.map

package/dist/playwright/pw-tools-core.interactions.d.ts

@@ -0,0 +1,104 @@
+export type BrowserFormField = {
+    ref: string;
+    type: string;
+    value?: string | number | boolean;
+};
+export declare function highlightViaPlaywright(opts: {
+    cdpUrl: string;
+    targetId?: string;
+    ref: string;
+}): Promise<void>;
+export declare function clickViaPlaywright(opts: {
+    cdpUrl: string;
+    targetId?: string;
+    ref: string;
+    doubleClick?: boolean;
+    button?: "left" | "right" | "middle";
+    modifiers?: Array<"Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift">;
+    timeoutMs?: number;
+}): Promise<void>;
+export declare function hoverViaPlaywright(opts: {
+    cdpUrl: string;
+    targetId?: string;
+    ref: string;
+    timeoutMs?: number;
+}): Promise<void>;
+export declare function dragViaPlaywright(opts: {
+    cdpUrl: string;
+    targetId?: string;
+    startRef: string;
+    endRef: string;
+    timeoutMs?: number;
+}): Promise<void>;
+export declare function selectOptionViaPlaywright(opts: {
+    cdpUrl: string;
+    targetId?: string;
+    ref: string;
+    values: string[];
+    timeoutMs?: number;
+}): Promise<void>;
+export declare function pressKeyViaPlaywright(opts: {
+    cdpUrl: string;
+    targetId?: string;
+    key: string;
+    delayMs?: number;
+}): Promise<void>;
+export declare function typeViaPlaywright(opts: {
+    cdpUrl: string;
+    targetId?: string;
+    ref: string;
+    text: string;
+    submit?: boolean;
+    slowly?: boolean;
+    timeoutMs?: number;
+}): Promise<void>;
+export declare function fillFormViaPlaywright(opts: {
+    cdpUrl: string;
+    targetId?: string;
+    fields: BrowserFormField[];
+    timeoutMs?: number;
+}): Promise<void>;
+export declare function evaluateViaPlaywright(opts: {
+    cdpUrl: string;
+    targetId?: string;
+    fn: string;
+    ref?: string;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}): Promise<unknown>;
+export declare function scrollIntoViewViaPlaywright(opts: {
+    cdpUrl: string;
+    targetId?: string;
+    ref: string;
+    timeoutMs?: number;
+}): Promise<void>;
+export declare function waitForViaPlaywright(opts: {
+    cdpUrl: string;
+    targetId?: string;
+    timeMs?: number;
+    text?: string;
+    textGone?: string;
+    selector?: string;
+    url?: string;
+    loadState?: "load" | "domcontentloaded" | "networkidle";
+    fn?: string;
+    timeoutMs?: number;
+}): Promise<void>;
+export declare function takeScreenshotViaPlaywright(opts: {
+    cdpUrl: string;
+    targetId?: string;
+    ref?: string;
+    element?: string;
+    fullPage?: boolean;
+    type?: "png" | "jpeg";
+}): Promise<{
+    buffer: Buffer;
+}>;
+export declare function setInputFilesViaPlaywright(opts: {
+    cdpUrl: string;
+    targetId?: string;
+    inputRef?: string;
+    element?: string;
+    paths: string[];
+}): Promise<void>;
+//# sourceMappingURL=pw-tools-core.interactions.d.ts.map

package/dist/playwright/pw-tools-core.interactions.js

@@ -0,0 +1,404 @@
+import { ensurePageState, forceDisconnectPlaywrightForTarget, getPageForTargetId, refLocator, restoreRoleRefsForTarget, } from "./pw-session.js";
+import { normalizeTimeoutMs, requireRef, toAIFriendlyError } from "./pw-tools-core.shared.js";
+export async function highlightViaPlaywright(opts) {
+    const page = await getPageForTargetId(opts);
+    ensurePageState(page);
+    restoreRoleRefsForTarget({ cdpUrl: opts.cdpUrl, targetId: opts.targetId, page });
+    const ref = requireRef(opts.ref);
+    try {
+        await refLocator(page, ref).highlight();
+    }
+    catch (err) {
+        throw toAIFriendlyError(err, ref);
+    }
+}
+export async function clickViaPlaywright(opts) {
+    const page = await getPageForTargetId({
+        cdpUrl: opts.cdpUrl,
+        targetId: opts.targetId,
+    });
+    ensurePageState(page);
+    restoreRoleRefsForTarget({ cdpUrl: opts.cdpUrl, targetId: opts.targetId, page });
+    const ref = requireRef(opts.ref);
+    const locator = refLocator(page, ref);
+    const timeout = Math.max(500, Math.min(60_000, Math.floor(opts.timeoutMs ?? 8000)));
+    try {
+        if (opts.doubleClick) {
+            await locator.dblclick({
+                timeout,
+                button: opts.button,
+                modifiers: opts.modifiers,
+            });
+        }
+        else {
+            await locator.click({
+                timeout,
+                button: opts.button,
+                modifiers: opts.modifiers,
+            });
+        }
+    }
+    catch (err) {
+        throw toAIFriendlyError(err, ref);
+    }
+}
+export async function hoverViaPlaywright(opts) {
+    const ref = requireRef(opts.ref);
+    const page = await getPageForTargetId(opts);
+    ensurePageState(page);
+    restoreRoleRefsForTarget({ cdpUrl: opts.cdpUrl, targetId: opts.targetId, page });
+    try {
+        await refLocator(page, ref).hover({
+            timeout: Math.max(500, Math.min(60_000, opts.timeoutMs ?? 8000)),
+        });
+    }
+    catch (err) {
+        throw toAIFriendlyError(err, ref);
+    }
+}
+export async function dragViaPlaywright(opts) {
+    const startRef = requireRef(opts.startRef);
+    const endRef = requireRef(opts.endRef);
+    if (!startRef || !endRef) {
+        throw new Error("startRef and endRef are required");
+    }
+    const page = await getPageForTargetId(opts);
+    ensurePageState(page);
+    restoreRoleRefsForTarget({ cdpUrl: opts.cdpUrl, targetId: opts.targetId, page });
+    try {
+        await refLocator(page, startRef).dragTo(refLocator(page, endRef), {
+            timeout: Math.max(500, Math.min(60_000, opts.timeoutMs ?? 8000)),
+        });
+    }
+    catch (err) {
+        throw toAIFriendlyError(err, `${startRef} -> ${endRef}`);
+    }
+}
+export async function selectOptionViaPlaywright(opts) {
+    const ref = requireRef(opts.ref);
+    if (!opts.values?.length) {
+        throw new Error("values are required");
+    }
+    const page = await getPageForTargetId(opts);
+    ensurePageState(page);
+    restoreRoleRefsForTarget({ cdpUrl: opts.cdpUrl, targetId: opts.targetId, page });
+    try {
+        await refLocator(page, ref).selectOption(opts.values, {
+            timeout: Math.max(500, Math.min(60_000, opts.timeoutMs ?? 8000)),
+        });
+    }
+    catch (err) {
+        throw toAIFriendlyError(err, ref);
+    }
+}
+export async function pressKeyViaPlaywright(opts) {
+    const key = String(opts.key ?? "").trim();
+    if (!key) {
+        throw new Error("key is required");
+    }
+    const page = await getPageForTargetId(opts);
+    ensurePageState(page);
+    await page.keyboard.press(key, {
+        delay: Math.max(0, Math.floor(opts.delayMs ?? 0)),
+    });
+}
+export async function typeViaPlaywright(opts) {
+    const text = String(opts.text ?? "");
+    const page = await getPageForTargetId(opts);
+    ensurePageState(page);
+    restoreRoleRefsForTarget({ cdpUrl: opts.cdpUrl, targetId: opts.targetId, page });
+    const ref = requireRef(opts.ref);
+    const locator = refLocator(page, ref);
+    const timeout = Math.max(500, Math.min(60_000, opts.timeoutMs ?? 8000));
+    try {
+        if (opts.slowly) {
+            await locator.click({ timeout });
+            await locator.type(text, { timeout, delay: 75 });
+        }
+        else {
+            await locator.fill(text, { timeout });
+        }
+        if (opts.submit) {
+            await locator.press("Enter", { timeout });
+        }
+    }
+    catch (err) {
+        throw toAIFriendlyError(err, ref);
+    }
+}
+export async function fillFormViaPlaywright(opts) {
+    const page = await getPageForTargetId(opts);
+    ensurePageState(page);
+    restoreRoleRefsForTarget({ cdpUrl: opts.cdpUrl, targetId: opts.targetId, page });
+    const timeout = Math.max(500, Math.min(60_000, opts.timeoutMs ?? 8000));
+    for (const field of opts.fields) {
+        const ref = field.ref.trim();
+        const type = field.type.trim();
+        const rawValue = field.value;
+        const value = typeof rawValue === "string"
+            ? rawValue
+            : typeof rawValue === "number" || typeof rawValue === "boolean"
+                ? String(rawValue)
+                : "";
+        if (!ref || !type) {
+            continue;
+        }
+        const locator = refLocator(page, ref);
+        if (type === "checkbox" || type === "radio") {
+            const checked = rawValue === true || rawValue === 1 || rawValue === "1" || rawValue === "true";
+            try {
+                await locator.setChecked(checked, { timeout });
+            }
+            catch (err) {
+                throw toAIFriendlyError(err, ref);
+            }
+            continue;
+        }
+        try {
+            await locator.fill(value, { timeout });
+        }
+        catch (err) {
+            throw toAIFriendlyError(err, ref);
+        }
+    }
+}
+export async function evaluateViaPlaywright(opts) {
+    const fnText = String(opts.fn ?? "").trim();
+    if (!fnText) {
+        throw new Error("function is required");
+    }
+    const page = await getPageForTargetId(opts);
+    ensurePageState(page);
+    restoreRoleRefsForTarget({ cdpUrl: opts.cdpUrl, targetId: opts.targetId, page });
+    const outerTimeout = normalizeTimeoutMs(opts.timeoutMs, 20_000);
+    let evaluateTimeout = Math.max(1000, Math.min(120_000, outerTimeout - 500));
+    evaluateTimeout = Math.min(evaluateTimeout, outerTimeout);
+    const signal = opts.signal;
+    let abortListener;
+    let abortReject;
+    let abortPromise;
+    if (signal) {
+        abortPromise = new Promise((_, reject) => {
+            abortReject = reject;
+        });
+        void abortPromise.catch(() => { });
+    }
+    if (signal) {
+        const disconnect = () => {
+            void forceDisconnectPlaywrightForTarget({
+                cdpUrl: opts.cdpUrl,
+                targetId: opts.targetId,
+                reason: "evaluate aborted",
+            }).catch(() => { });
+        };
+        if (signal.aborted) {
+            disconnect();
+            throw signal.reason ?? new Error("aborted");
+        }
+        abortListener = () => {
+            disconnect();
+            abortReject?.(signal.reason ?? new Error("aborted"));
+        };
+        signal.addEventListener("abort", abortListener, { once: true });
+        if (signal.aborted) {
+            abortListener();
+            throw signal.reason ?? new Error("aborted");
+        }
+    }
+    try {
+        if (opts.ref) {
+            const locator = refLocator(page, opts.ref);
+            // eslint-disable-next-line @typescript-eslint/no-implied-eval
+            const elementEvaluator = new Function("el", "args", `
+        "use strict";
+        var fnBody = args.fnBody, timeoutMs = args.timeoutMs;
+        try {
+          var candidate = eval("(" + fnBody + ")");
+          var result = typeof candidate === "function" ? candidate(el) : candidate;
+          if (result && typeof result.then === "function") {
+            return Promise.race([
+              result,
+              new Promise(function(_, reject) {
+                setTimeout(function() { reject(new Error("evaluate timed out after " + timeoutMs + "ms")); }, timeoutMs);
+              })
+            ]);
+          }
+          return result;
+        } catch (err) {
+          throw new Error("Invalid evaluate function: " + (err && err.message ? err.message : String(err)));
+        }
+        `);
+            const evalPromise = locator.evaluate(elementEvaluator, {
+                fnBody: fnText,
+                timeoutMs: evaluateTimeout,
+            });
+            if (!abortPromise) {
+                return await evalPromise;
+            }
+            try {
+                return await Promise.race([evalPromise, abortPromise]);
+            }
+            catch (err) {
+                void evalPromise.catch(() => { });
+                throw err;
+            }
+        }
+        // eslint-disable-next-line @typescript-eslint/no-implied-eval
+        const browserEvaluator = new Function("args", `
+        "use strict";
+        var fnBody = args.fnBody, timeoutMs = args.timeoutMs;
+        try {
+          var candidate = eval("(" + fnBody + ")");
+          var result = typeof candidate === "function" ? candidate() : candidate;
+          if (result && typeof result.then === "function") {
+            return Promise.race([
+              result,
+              new Promise(function(_, reject) {
+                setTimeout(function() { reject(new Error("evaluate timed out after " + timeoutMs + "ms")); }, timeoutMs);
+              })
+            ]);
+          }
+          return result;
+        } catch (err) {
+          throw new Error("Invalid evaluate function: " + (err && err.message ? err.message : String(err)));
+        }
+      `);
+        const evalPromise = page.evaluate(browserEvaluator, {
+            fnBody: fnText,
+            timeoutMs: evaluateTimeout,
+        });
+        if (!abortPromise) {
+            return await evalPromise;
+        }
+        try {
+            return await Promise.race([evalPromise, abortPromise]);
+        }
+        catch (err) {
+            void evalPromise.catch(() => { });
+            throw err;
+        }
+    }
+    finally {
+        if (signal && abortListener) {
+            signal.removeEventListener("abort", abortListener);
+        }
+    }
+}
+export async function scrollIntoViewViaPlaywright(opts) {
+    const page = await getPageForTargetId(opts);
+    ensurePageState(page);
+    restoreRoleRefsForTarget({ cdpUrl: opts.cdpUrl, targetId: opts.targetId, page });
+    const timeout = normalizeTimeoutMs(opts.timeoutMs, 20_000);
+    const ref = requireRef(opts.ref);
+    const locator = refLocator(page, ref);
+    try {
+        await locator.scrollIntoViewIfNeeded({ timeout });
+    }
+    catch (err) {
+        throw toAIFriendlyError(err, ref);
+    }
+}
+export async function waitForViaPlaywright(opts) {
+    const page = await getPageForTargetId(opts);
+    ensurePageState(page);
+    const timeout = normalizeTimeoutMs(opts.timeoutMs, 20_000);
+    if (typeof opts.timeMs === "number" && Number.isFinite(opts.timeMs)) {
+        await page.waitForTimeout(Math.max(0, opts.timeMs));
+    }
+    if (opts.text) {
+        await page.getByText(opts.text).first().waitFor({
+            state: "visible",
+            timeout,
+        });
+    }
+    if (opts.textGone) {
+        await page.getByText(opts.textGone).first().waitFor({
+            state: "hidden",
+            timeout,
+        });
+    }
+    if (opts.selector) {
+        const selector = String(opts.selector).trim();
+        if (selector) {
+            await page.locator(selector).first().waitFor({ state: "visible", timeout });
+        }
+    }
+    if (opts.url) {
+        const url = String(opts.url).trim();
+        if (url) {
+            await page.waitForURL(url, { timeout });
+        }
+    }
+    if (opts.loadState) {
+        await page.waitForLoadState(opts.loadState, { timeout });
+    }
+    if (opts.fn) {
+        const fn = String(opts.fn).trim();
+        if (fn) {
+            await page.waitForFunction(fn, { timeout });
+        }
+    }
+}
+export async function takeScreenshotViaPlaywright(opts) {
+    const page = await getPageForTargetId(opts);
+    ensurePageState(page);
+    restoreRoleRefsForTarget({ cdpUrl: opts.cdpUrl, targetId: opts.targetId, page });
+    const type = opts.type ?? "png";
+    if (opts.ref) {
+        if (opts.fullPage) {
+            throw new Error("fullPage is not supported for element screenshots");
+        }
+        const locator = refLocator(page, opts.ref);
+        const buffer = await locator.screenshot({ type });
+        return { buffer };
+    }
+    if (opts.element) {
+        if (opts.fullPage) {
+            throw new Error("fullPage is not supported for element screenshots");
+        }
+        const locator = page.locator(opts.element).first();
+        const buffer = await locator.screenshot({ type });
+        return { buffer };
+    }
+    const buffer = await page.screenshot({
+        type,
+        fullPage: Boolean(opts.fullPage),
+    });
+    return { buffer };
+}
+export async function setInputFilesViaPlaywright(opts) {
+    const page = await getPageForTargetId(opts);
+    ensurePageState(page);
+    restoreRoleRefsForTarget({ cdpUrl: opts.cdpUrl, targetId: opts.targetId, page });
+    if (!opts.paths.length) {
+        throw new Error("paths are required");
+    }
+    const inputRef = typeof opts.inputRef === "string" ? opts.inputRef.trim() : "";
+    const element = typeof opts.element === "string" ? opts.element.trim() : "";
+    if (inputRef && element) {
+        throw new Error("inputRef and element are mutually exclusive");
+    }
+    if (!inputRef && !element) {
+        throw new Error("inputRef or element is required");
+    }
+    const locator = inputRef ? refLocator(page, inputRef) : page.locator(element).first();
+    try {
+        await locator.setInputFiles(opts.paths);
+    }
+    catch (err) {
+        throw toAIFriendlyError(err, inputRef || element);
+    }
+    try {
+        const handle = await locator.elementHandle();
+        if (handle) {
+            await handle.evaluate((el) => {
+                el.dispatchEvent(new Event("input", { bubbles: true }));
+                el.dispatchEvent(new Event("change", { bubbles: true }));
+            });
+        }
+    }
+    catch {
+        // Best-effort
+    }
+}
+//# sourceMappingURL=pw-tools-core.interactions.js.map

package/dist/playwright/pw-tools-core.js

@@ -0,0 +1,9 @@
+export * from "./pw-tools-core.activity.js";
+export * from "./pw-tools-core.downloads.js";
+export * from "./pw-tools-core.interactions.js";
+export * from "./pw-tools-core.responses.js";
+export * from "./pw-tools-core.snapshot.js";
+export * from "./pw-tools-core.state.js";
+export * from "./pw-tools-core.storage.js";
+export * from "./pw-tools-core.trace.js";
+//# sourceMappingURL=pw-tools-core.js.map