@hera-al/browser-server 1.0.0

package/dist/playwright/pw-session.js

@@ -0,0 +1,530 @@
+import { chromium } from "playwright-core";
+import { formatErrorMessage } from "../utils.js";
+import { appendCdpPath, fetchJson, getHeadersWithAuth, withCdpSocket } from "../core/cdp.helpers.js";
+import { normalizeCdpWsUrl } from "../core/cdp.js";
+import { getChromeWebSocketUrl } from "../core/chrome.js";
+const pageStates = new WeakMap();
+const contextStates = new WeakMap();
+const observedContexts = new WeakSet();
+const observedPages = new WeakSet();
+const roleRefsByTarget = new Map();
+const MAX_ROLE_REFS_CACHE = 50;
+const MAX_CONSOLE_MESSAGES = 500;
+const MAX_PAGE_ERRORS = 200;
+const MAX_NETWORK_REQUESTS = 500;
+let cached = null;
+let connecting = null;
+function normalizeCdpUrl(raw) {
+    return raw.replace(/\/$/, "");
+}
+function roleRefsKey(cdpUrl, targetId) {
+    return `${normalizeCdpUrl(cdpUrl)}::${targetId}`;
+}
+export function rememberRoleRefsForTarget(opts) {
+    const targetId = opts.targetId.trim();
+    if (!targetId) {
+        return;
+    }
+    roleRefsByTarget.set(roleRefsKey(opts.cdpUrl, targetId), {
+        refs: opts.refs,
+        ...(opts.frameSelector ? { frameSelector: opts.frameSelector } : {}),
+        ...(opts.mode ? { mode: opts.mode } : {}),
+    });
+    while (roleRefsByTarget.size > MAX_ROLE_REFS_CACHE) {
+        const first = roleRefsByTarget.keys().next();
+        if (first.done) {
+            break;
+        }
+        roleRefsByTarget.delete(first.value);
+    }
+}
+export function storeRoleRefsForTarget(opts) {
+    const state = ensurePageState(opts.page);
+    state.roleRefs = opts.refs;
+    state.roleRefsFrameSelector = opts.frameSelector;
+    state.roleRefsMode = opts.mode;
+    if (!opts.targetId?.trim()) {
+        return;
+    }
+    rememberRoleRefsForTarget({
+        cdpUrl: opts.cdpUrl,
+        targetId: opts.targetId,
+        refs: opts.refs,
+        frameSelector: opts.frameSelector,
+        mode: opts.mode,
+    });
+}
+export function restoreRoleRefsForTarget(opts) {
+    const targetId = opts.targetId?.trim() || "";
+    if (!targetId) {
+        return;
+    }
+    const cachedEntry = roleRefsByTarget.get(roleRefsKey(opts.cdpUrl, targetId));
+    if (!cachedEntry) {
+        return;
+    }
+    const state = ensurePageState(opts.page);
+    if (state.roleRefs) {
+        return;
+    }
+    state.roleRefs = cachedEntry.refs;
+    state.roleRefsFrameSelector = cachedEntry.frameSelector;
+    state.roleRefsMode = cachedEntry.mode;
+}
+export function ensurePageState(page) {
+    const existing = pageStates.get(page);
+    if (existing) {
+        return existing;
+    }
+    const state = {
+        console: [],
+        errors: [],
+        requests: [],
+        requestIds: new WeakMap(),
+        nextRequestId: 0,
+        armIdUpload: 0,
+        armIdDialog: 0,
+        armIdDownload: 0,
+    };
+    pageStates.set(page, state);
+    if (!observedPages.has(page)) {
+        observedPages.add(page);
+        page.on("console", (msg) => {
+            const entry = {
+                type: msg.type(),
+                text: msg.text(),
+                timestamp: new Date().toISOString(),
+                location: msg.location(),
+            };
+            state.console.push(entry);
+            if (state.console.length > MAX_CONSOLE_MESSAGES) {
+                state.console.shift();
+            }
+        });
+        page.on("pageerror", (err) => {
+            state.errors.push({
+                message: err?.message ? String(err.message) : String(err),
+                name: err?.name ? String(err.name) : undefined,
+                stack: err?.stack ? String(err.stack) : undefined,
+                timestamp: new Date().toISOString(),
+            });
+            if (state.errors.length > MAX_PAGE_ERRORS) {
+                state.errors.shift();
+            }
+        });
+        page.on("request", (req) => {
+            state.nextRequestId += 1;
+            const id = `r${state.nextRequestId}`;
+            state.requestIds.set(req, id);
+            state.requests.push({
+                id,
+                timestamp: new Date().toISOString(),
+                method: req.method(),
+                url: req.url(),
+                resourceType: req.resourceType(),
+            });
+            if (state.requests.length > MAX_NETWORK_REQUESTS) {
+                state.requests.shift();
+            }
+        });
+        page.on("response", (resp) => {
+            const req = resp.request();
+            const id = state.requestIds.get(req);
+            if (!id) {
+                return;
+            }
+            let rec;
+            for (let i = state.requests.length - 1; i >= 0; i -= 1) {
+                const candidate = state.requests[i];
+                if (candidate && candidate.id === id) {
+                    rec = candidate;
+                    break;
+                }
+            }
+            if (!rec) {
+                return;
+            }
+            rec.status = resp.status();
+            rec.ok = resp.ok();
+        });
+        page.on("requestfailed", (req) => {
+            const id = state.requestIds.get(req);
+            if (!id) {
+                return;
+            }
+            let rec;
+            for (let i = state.requests.length - 1; i >= 0; i -= 1) {
+                const candidate = state.requests[i];
+                if (candidate && candidate.id === id) {
+                    rec = candidate;
+                    break;
+                }
+            }
+            if (!rec) {
+                return;
+            }
+            rec.failureText = req.failure()?.errorText;
+            rec.ok = false;
+        });
+        page.on("close", () => {
+            pageStates.delete(page);
+            observedPages.delete(page);
+        });
+    }
+    return state;
+}
+function observeContext(context) {
+    if (observedContexts.has(context)) {
+        return;
+    }
+    observedContexts.add(context);
+    ensureContextState(context);
+    for (const page of context.pages()) {
+        ensurePageState(page);
+    }
+    context.on("page", (page) => ensurePageState(page));
+}
+export function ensureContextState(context) {
+    const existing = contextStates.get(context);
+    if (existing) {
+        return existing;
+    }
+    const state = { traceActive: false };
+    contextStates.set(context, state);
+    return state;
+}
+function observeBrowser(browser) {
+    for (const context of browser.contexts()) {
+        observeContext(context);
+    }
+}
+async function connectBrowser(cdpUrl) {
+    const normalized = normalizeCdpUrl(cdpUrl);
+    if (cached?.cdpUrl === normalized) {
+        return cached;
+    }
+    if (connecting) {
+        return await connecting;
+    }
+    const connectWithRetry = async () => {
+        let lastErr;
+        for (let attempt = 0; attempt < 3; attempt += 1) {
+            try {
+                const timeout = 5000 + attempt * 2000;
+                const wsUrl = await getChromeWebSocketUrl(normalized, timeout).catch(() => null);
+                const endpoint = wsUrl ?? normalized;
+                const headers = getHeadersWithAuth(endpoint);
+                const browser = await chromium.connectOverCDP(endpoint, { timeout, headers });
+                const onDisconnected = () => {
+                    if (cached?.browser === browser) {
+                        cached = null;
+                    }
+                };
+                const connected = { browser, cdpUrl: normalized, onDisconnected };
+                cached = connected;
+                browser.on("disconnected", onDisconnected);
+                observeBrowser(browser);
+                return connected;
+            }
+            catch (err) {
+                lastErr = err;
+                const delay = 250 + attempt * 250;
+                await new Promise((r) => setTimeout(r, delay));
+            }
+        }
+        if (lastErr instanceof Error) {
+            throw lastErr;
+        }
+        const message = lastErr ? formatErrorMessage(lastErr) : "CDP connect failed";
+        throw new Error(message);
+    };
+    connecting = connectWithRetry().finally(() => {
+        connecting = null;
+    });
+    return await connecting;
+}
+async function getAllPages(browser) {
+    const contexts = browser.contexts();
+    const pages = contexts.flatMap((c) => c.pages());
+    return pages;
+}
+async function pageTargetId(page) {
+    const session = await page.context().newCDPSession(page);
+    try {
+        const info = (await session.send("Target.getTargetInfo"));
+        const targetId = String(info?.targetInfo?.targetId ?? "").trim();
+        return targetId || null;
+    }
+    finally {
+        await session.detach().catch(() => { });
+    }
+}
+async function findPageByTargetId(browser, targetId, cdpUrl) {
+    const pages = await getAllPages(browser);
+    for (const page of pages) {
+        const tid = await pageTargetId(page).catch(() => null);
+        if (tid && tid === targetId) {
+            return page;
+        }
+    }
+    if (cdpUrl) {
+        try {
+            const baseUrl = cdpUrl
+                .replace(/\/+$/, "")
+                .replace(/^ws:/, "http:")
+                .replace(/\/cdp$/, "");
+            const listUrl = `${baseUrl}/json/list`;
+            const response = await fetch(listUrl, { headers: getHeadersWithAuth(listUrl) });
+            if (response.ok) {
+                const targets = (await response.json());
+                const target = targets.find((t) => t.id === targetId);
+                if (target) {
+                    const urlMatch = pages.filter((p) => p.url() === target.url);
+                    if (urlMatch.length === 1) {
+                        return urlMatch[0];
+                    }
+                    if (urlMatch.length > 1) {
+                        const sameUrlTargets = targets.filter((t) => t.url === target.url);
+                        if (sameUrlTargets.length === urlMatch.length) {
+                            const idx = sameUrlTargets.findIndex((t) => t.id === targetId);
+                            if (idx >= 0 && idx < urlMatch.length) {
+                                return urlMatch[idx];
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        catch {
+            // Ignore fetch errors
+        }
+    }
+    return null;
+}
+export async function getPageForTargetId(opts) {
+    const { browser } = await connectBrowser(opts.cdpUrl);
+    const pages = await getAllPages(browser);
+    if (!pages.length) {
+        throw new Error("No pages available in the connected browser.");
+    }
+    const first = pages[0];
+    if (!opts.targetId) {
+        return first;
+    }
+    const found = await findPageByTargetId(browser, opts.targetId, opts.cdpUrl);
+    if (!found) {
+        if (pages.length === 1) {
+            return first;
+        }
+        throw new Error("tab not found");
+    }
+    return found;
+}
+export function refLocator(page, ref) {
+    const normalized = ref.startsWith("@")
+        ? ref.slice(1)
+        : ref.startsWith("ref=")
+            ? ref.slice(4)
+            : ref;
+    if (/^e\d+$/.test(normalized)) {
+        const state = pageStates.get(page);
+        if (state?.roleRefsMode === "aria") {
+            const scope = state.roleRefsFrameSelector
+                ? page.frameLocator(state.roleRefsFrameSelector)
+                : page;
+            return scope.locator(`aria-ref=${normalized}`);
+        }
+        const info = state?.roleRefs?.[normalized];
+        if (!info) {
+            throw new Error(`Unknown ref "${normalized}". Run a new snapshot and use a ref from that snapshot.`);
+        }
+        const scope = state?.roleRefsFrameSelector
+            ? page.frameLocator(state.roleRefsFrameSelector)
+            : page;
+        const locAny = scope;
+        const locator = info.name
+            ? locAny.getByRole(info.role, { name: info.name, exact: true })
+            : locAny.getByRole(info.role);
+        return info.nth !== undefined ? locator.nth(info.nth) : locator;
+    }
+    return page.locator(`aria-ref=${normalized}`);
+}
+export async function closePlaywrightBrowserConnection() {
+    const cur = cached;
+    cached = null;
+    connecting = null;
+    if (!cur) {
+        return;
+    }
+    if (cur.onDisconnected && typeof cur.browser.off === "function") {
+        cur.browser.off("disconnected", cur.onDisconnected);
+    }
+    await cur.browser.close().catch(() => { });
+}
+function normalizeCdpHttpBaseForJsonEndpoints(cdpUrl) {
+    try {
+        const url = new URL(cdpUrl);
+        if (url.protocol === "ws:") {
+            url.protocol = "http:";
+        }
+        else if (url.protocol === "wss:") {
+            url.protocol = "https:";
+        }
+        url.pathname = url.pathname.replace(/\/devtools\/browser\/.*$/, "");
+        url.pathname = url.pathname.replace(/\/cdp$/, "");
+        return url.toString().replace(/\/$/, "");
+    }
+    catch {
+        return cdpUrl
+            .replace(/^ws:/, "http:")
+            .replace(/^wss:/, "https:")
+            .replace(/\/devtools\/browser\/.*$/, "")
+            .replace(/\/cdp$/, "")
+            .replace(/\/$/, "");
+    }
+}
+function cdpSocketNeedsAttach(wsUrl) {
+    try {
+        const pathname = new URL(wsUrl).pathname;
+        return (pathname === "/cdp" || pathname.endsWith("/cdp") || pathname.includes("/devtools/browser/"));
+    }
+    catch {
+        return false;
+    }
+}
+async function tryTerminateExecutionViaCdp(opts) {
+    const cdpHttpBase = normalizeCdpHttpBaseForJsonEndpoints(opts.cdpUrl);
+    const listUrl = appendCdpPath(cdpHttpBase, "/json/list");
+    const pages = await fetchJson(listUrl, 2000).catch(() => null);
+    if (!pages || pages.length === 0) {
+        return;
+    }
+    const target = pages.find((p) => String(p.id ?? "").trim() === opts.targetId);
+    const wsUrlRaw = String(target?.webSocketDebuggerUrl ?? "").trim();
+    if (!wsUrlRaw) {
+        return;
+    }
+    const wsUrl = normalizeCdpWsUrl(wsUrlRaw, cdpHttpBase);
+    const needsAttach = cdpSocketNeedsAttach(wsUrl);
+    const runWithTimeout = async (work, ms) => {
+        let timer;
+        const timeoutPromise = new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new Error("CDP command timed out")), ms);
+        });
+        try {
+            return await Promise.race([work, timeoutPromise]);
+        }
+        finally {
+            if (timer) {
+                clearTimeout(timer);
+            }
+        }
+    };
+    await withCdpSocket(wsUrl, async (send) => {
+        let sessionId;
+        try {
+            if (needsAttach) {
+                const attached = (await runWithTimeout(send("Target.attachToTarget", { targetId: opts.targetId, flatten: true }), 1500));
+                if (typeof attached?.sessionId === "string" && attached.sessionId.trim()) {
+                    sessionId = attached.sessionId;
+                }
+            }
+            await runWithTimeout(send("Runtime.terminateExecution", undefined, sessionId), 1500);
+            if (sessionId) {
+                void send("Target.detachFromTarget", { sessionId }).catch(() => { });
+            }
+        }
+        catch {
+            // Best-effort; ignore
+        }
+    }, { handshakeTimeoutMs: 2000 }).catch(() => { });
+}
+export async function forceDisconnectPlaywrightForTarget(opts) {
+    const normalized = normalizeCdpUrl(opts.cdpUrl);
+    if (cached?.cdpUrl !== normalized) {
+        return;
+    }
+    const cur = cached;
+    cached = null;
+    connecting = null;
+    if (cur) {
+        if (cur.onDisconnected && typeof cur.browser.off === "function") {
+            cur.browser.off("disconnected", cur.onDisconnected);
+        }
+        const targetId = opts.targetId?.trim() || "";
+        if (targetId) {
+            await tryTerminateExecutionViaCdp({ cdpUrl: normalized, targetId }).catch(() => { });
+        }
+        cur.browser.close().catch(() => { });
+    }
+}
+export async function listPagesViaPlaywright(opts) {
+    const { browser } = await connectBrowser(opts.cdpUrl);
+    const pages = await getAllPages(browser);
+    const results = [];
+    for (const page of pages) {
+        const tid = await pageTargetId(page).catch(() => null);
+        if (tid) {
+            results.push({
+                targetId: tid,
+                title: await page.title().catch(() => ""),
+                url: page.url(),
+                type: "page",
+            });
+        }
+    }
+    return results;
+}
+export async function createPageViaPlaywright(opts) {
+    const { browser } = await connectBrowser(opts.cdpUrl);
+    const context = browser.contexts()[0] ?? (await browser.newContext());
+    ensureContextState(context);
+    const page = await context.newPage();
+    ensurePageState(page);
+    const targetUrl = opts.url.trim() || "about:blank";
+    if (targetUrl !== "about:blank") {
+        await page.goto(targetUrl, { timeout: 30_000 }).catch(() => { });
+    }
+    const tid = await pageTargetId(page).catch(() => null);
+    if (!tid) {
+        throw new Error("Failed to get targetId for new page");
+    }
+    return {
+        targetId: tid,
+        title: await page.title().catch(() => ""),
+        url: page.url(),
+        type: "page",
+    };
+}
+export async function closePageByTargetIdViaPlaywright(opts) {
+    const { browser } = await connectBrowser(opts.cdpUrl);
+    const page = await findPageByTargetId(browser, opts.targetId, opts.cdpUrl);
+    if (!page) {
+        throw new Error("tab not found");
+    }
+    await page.close();
+}
+export async function focusPageByTargetIdViaPlaywright(opts) {
+    const { browser } = await connectBrowser(opts.cdpUrl);
+    const page = await findPageByTargetId(browser, opts.targetId, opts.cdpUrl);
+    if (!page) {
+        throw new Error("tab not found");
+    }
+    try {
+        await page.bringToFront();
+    }
+    catch (err) {
+        const session = await page.context().newCDPSession(page);
+        try {
+            await session.send("Page.bringToFront");
+            return;
+        }
+        catch {
+            throw err;
+        }
+        finally {
+            await session.detach().catch(() => { });
+        }
+    }
+}
+//# sourceMappingURL=pw-session.js.map

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

@@ -0,0 +1,22 @@
+import type { BrowserConsoleMessage, BrowserNetworkRequest, BrowserPageError } from "./pw-session.js";
+export declare function getPageErrorsViaPlaywright(opts: {
+    cdpUrl: string;
+    targetId?: string;
+    clear?: boolean;
+}): Promise<{
+    errors: BrowserPageError[];
+}>;
+export declare function getNetworkRequestsViaPlaywright(opts: {
+    cdpUrl: string;
+    targetId?: string;
+    filter?: string;
+    clear?: boolean;
+}): Promise<{
+    requests: BrowserNetworkRequest[];
+}>;
+export declare function getConsoleMessagesViaPlaywright(opts: {
+    cdpUrl: string;
+    targetId?: string;
+    level?: string;
+}): Promise<BrowserConsoleMessage[]>;
+//# sourceMappingURL=pw-tools-core.activity.d.ts.map

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

@@ -0,0 +1,47 @@
+import { ensurePageState, getPageForTargetId } from "./pw-session.js";
+export async function getPageErrorsViaPlaywright(opts) {
+    const page = await getPageForTargetId(opts);
+    const state = ensurePageState(page);
+    const errors = [...state.errors];
+    if (opts.clear) {
+        state.errors = [];
+    }
+    return { errors };
+}
+export async function getNetworkRequestsViaPlaywright(opts) {
+    const page = await getPageForTargetId(opts);
+    const state = ensurePageState(page);
+    const raw = [...state.requests];
+    const filter = typeof opts.filter === "string" ? opts.filter.trim() : "";
+    const requests = filter ? raw.filter((r) => r.url.includes(filter)) : raw;
+    if (opts.clear) {
+        state.requests = [];
+        state.requestIds = new WeakMap();
+    }
+    return { requests };
+}
+function consolePriority(level) {
+    switch (level) {
+        case "error":
+            return 3;
+        case "warning":
+            return 2;
+        case "info":
+        case "log":
+            return 1;
+        case "debug":
+            return 0;
+        default:
+            return 1;
+    }
+}
+export async function getConsoleMessagesViaPlaywright(opts) {
+    const page = await getPageForTargetId(opts);
+    const state = ensurePageState(page);
+    if (!opts.level) {
+        return [...state.console];
+    }
+    const min = consolePriority(opts.level);
+    return state.console.filter((msg) => consolePriority(msg.type) >= min);
+}
+//# sourceMappingURL=pw-tools-core.activity.js.map

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

@@ -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.d.ts.map

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

@@ -0,0 +1,35 @@
+export declare function armFileUploadViaPlaywright(opts: {
+    cdpUrl: string;
+    targetId?: string;
+    paths?: string[];
+    timeoutMs?: number;
+}): Promise<void>;
+export declare function armDialogViaPlaywright(opts: {
+    cdpUrl: string;
+    targetId?: string;
+    accept: boolean;
+    promptText?: string;
+    timeoutMs?: number;
+}): Promise<void>;
+export declare function waitForDownloadViaPlaywright(opts: {
+    cdpUrl: string;
+    targetId?: string;
+    path?: string;
+    timeoutMs?: number;
+}): Promise<{
+    url: string;
+    suggestedFilename: string;
+    path: string;
+}>;
+export declare function downloadViaPlaywright(opts: {
+    cdpUrl: string;
+    targetId?: string;
+    ref: string;
+    path: string;
+    timeoutMs?: number;
+}): Promise<{
+    url: string;
+    suggestedFilename: string;
+    path: string;
+}>;
+//# sourceMappingURL=pw-tools-core.downloads.d.ts.map