@hera-al/browser-server 1.0.0

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

@@ -0,0 +1,14 @@
+export declare function responseBodyViaPlaywright(opts: {
+    cdpUrl: string;
+    targetId?: string;
+    url: string;
+    timeoutMs?: number;
+    maxChars?: number;
+}): Promise<{
+    url: string;
+    status?: number;
+    headers?: Record<string, string>;
+    body: string;
+    truncated?: boolean;
+}>;
+//# sourceMappingURL=pw-tools-core.responses.d.ts.map

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

@@ -0,0 +1,91 @@
+import { ensurePageState, getPageForTargetId } from "./pw-session.js";
+import { normalizeTimeoutMs } from "./pw-tools-core.shared.js";
+function matchUrlPattern(pattern, url) {
+    const p = pattern.trim();
+    if (!p) {
+        return false;
+    }
+    if (p === url) {
+        return true;
+    }
+    if (p.includes("*")) {
+        const escaped = p.replace(/[|\\{}()[\]^$+?.]/g, "\\$&");
+        const regex = new RegExp(`^${escaped.replace(/\*\*/g, ".*").replace(/\*/g, ".*")}$`);
+        return regex.test(url);
+    }
+    return url.includes(p);
+}
+export async function responseBodyViaPlaywright(opts) {
+    const pattern = String(opts.url ?? "").trim();
+    if (!pattern) {
+        throw new Error("url is required");
+    }
+    const maxChars = typeof opts.maxChars === "number" && Number.isFinite(opts.maxChars)
+        ? Math.max(1, Math.min(5_000_000, Math.floor(opts.maxChars)))
+        : 200_000;
+    const timeout = normalizeTimeoutMs(opts.timeoutMs, 20_000);
+    const page = await getPageForTargetId(opts);
+    ensurePageState(page);
+    const promise = new Promise((resolve, reject) => {
+        let done = false;
+        let timer;
+        let handler;
+        const cleanup = () => {
+            if (timer) {
+                clearTimeout(timer);
+            }
+            timer = undefined;
+            if (handler) {
+                page.off("response", handler);
+            }
+        };
+        handler = (resp) => {
+            if (done) {
+                return;
+            }
+            const r = resp;
+            const u = r.url?.() || "";
+            if (!matchUrlPattern(pattern, u)) {
+                return;
+            }
+            done = true;
+            cleanup();
+            resolve(resp);
+        };
+        page.on("response", handler);
+        timer = setTimeout(() => {
+            if (done) {
+                return;
+            }
+            done = true;
+            cleanup();
+            reject(new Error(`Response not found for url pattern "${pattern}". Check recent network activity.`));
+        }, timeout);
+    });
+    const resp = (await promise);
+    const url = resp.url?.() || "";
+    const status = resp.status?.();
+    const headers = resp.headers?.();
+    let bodyText = "";
+    try {
+        if (typeof resp.text === "function") {
+            bodyText = await resp.text();
+        }
+        else if (typeof resp.body === "function") {
+            const buf = await resp.body();
+            bodyText = new TextDecoder("utf-8").decode(buf);
+        }
+    }
+    catch (err) {
+        throw new Error(`Failed to read response body for "${url}": ${String(err)}`, { cause: err });
+    }
+    const trimmed = bodyText.length > maxChars ? bodyText.slice(0, maxChars) : bodyText;
+    return {
+        url,
+        status,
+        headers,
+        body: trimmed,
+        truncated: bodyText.length > maxChars ? true : undefined,
+    };
+}
+//# sourceMappingURL=pw-tools-core.responses.js.map

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

@@ -0,0 +1,7 @@
+export declare function bumpUploadArmId(): number;
+export declare function bumpDialogArmId(): number;
+export declare function bumpDownloadArmId(): number;
+export declare function requireRef(value: unknown): string;
+export declare function normalizeTimeoutMs(timeoutMs: number | undefined, fallback: number): number;
+export declare function toAIFriendlyError(error: unknown, selector: string): Error;
+//# sourceMappingURL=pw-tools-core.shared.d.ts.map

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

@@ -0,0 +1,50 @@
+import { parseRoleRef } from "./pw-role-snapshot.js";
+let nextUploadArmId = 0;
+let nextDialogArmId = 0;
+let nextDownloadArmId = 0;
+export function bumpUploadArmId() {
+    nextUploadArmId += 1;
+    return nextUploadArmId;
+}
+export function bumpDialogArmId() {
+    nextDialogArmId += 1;
+    return nextDialogArmId;
+}
+export function bumpDownloadArmId() {
+    nextDownloadArmId += 1;
+    return nextDownloadArmId;
+}
+export function requireRef(value) {
+    const raw = typeof value === "string" ? value.trim() : "";
+    const roleRef = raw ? parseRoleRef(raw) : null;
+    const ref = roleRef ?? (raw.startsWith("@") ? raw.slice(1) : raw);
+    if (!ref) {
+        throw new Error("ref is required");
+    }
+    return ref;
+}
+export function normalizeTimeoutMs(timeoutMs, fallback) {
+    return Math.max(500, Math.min(120_000, timeoutMs ?? fallback));
+}
+export function toAIFriendlyError(error, selector) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (message.includes("strict mode violation")) {
+        const countMatch = message.match(/resolved to (\d+) elements/);
+        const count = countMatch ? countMatch[1] : "multiple";
+        return new Error(`Selector "${selector}" matched ${count} elements. ` +
+            `Run a new snapshot to get updated refs, or use a different ref.`);
+    }
+    if ((message.includes("Timeout") || message.includes("waiting for")) &&
+        (message.includes("to be visible") || message.includes("not visible"))) {
+        return new Error(`Element "${selector}" not found or not visible. ` +
+            `Run a new snapshot to see current page elements.`);
+    }
+    if (message.includes("intercepts pointer events") ||
+        message.includes("not visible") ||
+        message.includes("not receive pointer events")) {
+        return new Error(`Element "${selector}" is not interactable (hidden or covered). ` +
+            `Try scrolling it into view, closing overlays, or re-snapshotting.`);
+    }
+    return error instanceof Error ? error : new Error(message);
+}
+//# sourceMappingURL=pw-tools-core.shared.js.map

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

@@ -0,0 +1,65 @@
+import { type AriaSnapshotNode } from "../core/cdp.js";
+import { type RoleSnapshotOptions, type RoleRefMap } from "./pw-role-snapshot.js";
+export declare function snapshotAriaViaPlaywright(opts: {
+    cdpUrl: string;
+    targetId?: string;
+    limit?: number;
+}): Promise<{
+    nodes: AriaSnapshotNode[];
+}>;
+export declare function snapshotAiViaPlaywright(opts: {
+    cdpUrl: string;
+    targetId?: string;
+    timeoutMs?: number;
+    maxChars?: number;
+}): Promise<{
+    snapshot: string;
+    truncated?: boolean;
+    refs: RoleRefMap;
+}>;
+export declare function snapshotRoleViaPlaywright(opts: {
+    cdpUrl: string;
+    targetId?: string;
+    selector?: string;
+    frameSelector?: string;
+    refsMode?: "role" | "aria";
+    options?: RoleSnapshotOptions;
+}): Promise<{
+    snapshot: string;
+    refs: Record<string, {
+        role: string;
+        name?: string;
+        nth?: number;
+    }>;
+    stats: {
+        lines: number;
+        chars: number;
+        refs: number;
+        interactive: number;
+    };
+}>;
+export declare function navigateViaPlaywright(opts: {
+    cdpUrl: string;
+    targetId?: string;
+    url: string;
+    timeoutMs?: number;
+}): Promise<{
+    url: string;
+}>;
+export declare function resizeViewportViaPlaywright(opts: {
+    cdpUrl: string;
+    targetId?: string;
+    width: number;
+    height: number;
+}): Promise<void>;
+export declare function closePageViaPlaywright(opts: {
+    cdpUrl: string;
+    targetId?: string;
+}): Promise<void>;
+export declare function pdfViaPlaywright(opts: {
+    cdpUrl: string;
+    targetId?: string;
+}): Promise<{
+    buffer: Buffer;
+}>;
+//# sourceMappingURL=pw-tools-core.snapshot.d.ts.map

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

@@ -0,0 +1,144 @@
+import { formatAriaSnapshot } from "../core/cdp.js";
+import { buildRoleSnapshotFromAiSnapshot, buildRoleSnapshotFromAriaSnapshot, getRoleSnapshotStats, } from "./pw-role-snapshot.js";
+import { ensurePageState, getPageForTargetId, storeRoleRefsForTarget, } from "./pw-session.js";
+export async function snapshotAriaViaPlaywright(opts) {
+    const limit = Math.max(1, Math.min(2000, Math.floor(opts.limit ?? 500)));
+    const page = await getPageForTargetId({
+        cdpUrl: opts.cdpUrl,
+        targetId: opts.targetId,
+    });
+    ensurePageState(page);
+    const session = await page.context().newCDPSession(page);
+    try {
+        await session.send("Accessibility.enable").catch(() => { });
+        const res = (await session.send("Accessibility.getFullAXTree"));
+        const nodes = Array.isArray(res?.nodes) ? res.nodes : [];
+        return { nodes: formatAriaSnapshot(nodes, limit) };
+    }
+    finally {
+        await session.detach().catch(() => { });
+    }
+}
+export async function snapshotAiViaPlaywright(opts) {
+    const page = await getPageForTargetId({
+        cdpUrl: opts.cdpUrl,
+        targetId: opts.targetId,
+    });
+    ensurePageState(page);
+    const maybe = page;
+    if (!maybe._snapshotForAI) {
+        throw new Error("Playwright _snapshotForAI is not available. Upgrade playwright-core.");
+    }
+    const result = await maybe._snapshotForAI({
+        timeout: Math.max(500, Math.min(60_000, Math.floor(opts.timeoutMs ?? 5000))),
+        track: "response",
+    });
+    let snapshot = String(result?.full ?? "");
+    const maxChars = opts.maxChars;
+    const limit = typeof maxChars === "number" && Number.isFinite(maxChars) && maxChars > 0
+        ? Math.floor(maxChars)
+        : undefined;
+    let truncated = false;
+    if (limit && snapshot.length > limit) {
+        snapshot = `${snapshot.slice(0, limit)}\n\n[...TRUNCATED - page too large]`;
+        truncated = true;
+    }
+    const built = buildRoleSnapshotFromAiSnapshot(snapshot);
+    storeRoleRefsForTarget({
+        page,
+        cdpUrl: opts.cdpUrl,
+        targetId: opts.targetId,
+        refs: built.refs,
+        mode: "aria",
+    });
+    return truncated ? { snapshot, truncated, refs: built.refs } : { snapshot, refs: built.refs };
+}
+export async function snapshotRoleViaPlaywright(opts) {
+    const page = await getPageForTargetId({
+        cdpUrl: opts.cdpUrl,
+        targetId: opts.targetId,
+    });
+    ensurePageState(page);
+    if (opts.refsMode === "aria") {
+        if (opts.selector?.trim() || opts.frameSelector?.trim()) {
+            throw new Error("refs=aria does not support selector/frame snapshots yet.");
+        }
+        const maybe = page;
+        if (!maybe._snapshotForAI) {
+            throw new Error("refs=aria requires Playwright _snapshotForAI support.");
+        }
+        const result = await maybe._snapshotForAI({
+            timeout: 5000,
+            track: "response",
+        });
+        const built = buildRoleSnapshotFromAiSnapshot(String(result?.full ?? ""), opts.options);
+        storeRoleRefsForTarget({
+            page,
+            cdpUrl: opts.cdpUrl,
+            targetId: opts.targetId,
+            refs: built.refs,
+            mode: "aria",
+        });
+        return {
+            snapshot: built.snapshot,
+            refs: built.refs,
+            stats: getRoleSnapshotStats(built.snapshot, built.refs),
+        };
+    }
+    const frameSelector = opts.frameSelector?.trim() || "";
+    const selector = opts.selector?.trim() || "";
+    const locator = frameSelector
+        ? selector
+            ? page.frameLocator(frameSelector).locator(selector)
+            : page.frameLocator(frameSelector).locator(":root")
+        : selector
+            ? page.locator(selector)
+            : page.locator(":root");
+    const ariaSnapshot = await locator.ariaSnapshot();
+    const built = buildRoleSnapshotFromAriaSnapshot(String(ariaSnapshot ?? ""), opts.options);
+    storeRoleRefsForTarget({
+        page,
+        cdpUrl: opts.cdpUrl,
+        targetId: opts.targetId,
+        refs: built.refs,
+        frameSelector: frameSelector || undefined,
+        mode: "role",
+    });
+    return {
+        snapshot: built.snapshot,
+        refs: built.refs,
+        stats: getRoleSnapshotStats(built.snapshot, built.refs),
+    };
+}
+export async function navigateViaPlaywright(opts) {
+    const url = String(opts.url ?? "").trim();
+    if (!url) {
+        throw new Error("url is required");
+    }
+    const page = await getPageForTargetId(opts);
+    ensurePageState(page);
+    await page.goto(url, {
+        timeout: Math.max(1000, Math.min(120_000, opts.timeoutMs ?? 20_000)),
+    });
+    return { url: page.url() };
+}
+export async function resizeViewportViaPlaywright(opts) {
+    const page = await getPageForTargetId(opts);
+    ensurePageState(page);
+    await page.setViewportSize({
+        width: Math.max(1, Math.floor(opts.width)),
+        height: Math.max(1, Math.floor(opts.height)),
+    });
+}
+export async function closePageViaPlaywright(opts) {
+    const page = await getPageForTargetId(opts);
+    ensurePageState(page);
+    await page.close();
+}
+export async function pdfViaPlaywright(opts) {
+    const page = await getPageForTargetId(opts);
+    ensurePageState(page);
+    const buffer = await page.pdf({ printBackground: true });
+    return { buffer };
+}
+//# sourceMappingURL=pw-tools-core.snapshot.js.map

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

@@ -0,0 +1,47 @@
+export declare function setOfflineViaPlaywright(opts: {
+    cdpUrl: string;
+    targetId?: string;
+    offline: boolean;
+}): Promise<void>;
+export declare function setExtraHTTPHeadersViaPlaywright(opts: {
+    cdpUrl: string;
+    targetId?: string;
+    headers: Record<string, string>;
+}): Promise<void>;
+export declare function setHttpCredentialsViaPlaywright(opts: {
+    cdpUrl: string;
+    targetId?: string;
+    username?: string;
+    password?: string;
+    clear?: boolean;
+}): Promise<void>;
+export declare function setGeolocationViaPlaywright(opts: {
+    cdpUrl: string;
+    targetId?: string;
+    latitude?: number;
+    longitude?: number;
+    accuracy?: number;
+    origin?: string;
+    clear?: boolean;
+}): Promise<void>;
+export declare function emulateMediaViaPlaywright(opts: {
+    cdpUrl: string;
+    targetId?: string;
+    colorScheme: "dark" | "light" | "no-preference" | null;
+}): Promise<void>;
+export declare function setLocaleViaPlaywright(opts: {
+    cdpUrl: string;
+    targetId?: string;
+    locale: string;
+}): Promise<void>;
+export declare function setTimezoneViaPlaywright(opts: {
+    cdpUrl: string;
+    targetId?: string;
+    timezoneId: string;
+}): Promise<void>;
+export declare function setDeviceViaPlaywright(opts: {
+    cdpUrl: string;
+    targetId?: string;
+    name: string;
+}): Promise<void>;
+//# sourceMappingURL=pw-tools-core.state.d.ts.map

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

@@ -0,0 +1,154 @@
+import { devices as playwrightDevices } from "playwright-core";
+import { ensurePageState, getPageForTargetId } from "./pw-session.js";
+async function withCdpSession(page, fn) {
+    const session = await page.context().newCDPSession(page);
+    try {
+        return await fn(session);
+    }
+    finally {
+        await session.detach().catch(() => { });
+    }
+}
+export async function setOfflineViaPlaywright(opts) {
+    const page = await getPageForTargetId(opts);
+    ensurePageState(page);
+    await page.context().setOffline(Boolean(opts.offline));
+}
+export async function setExtraHTTPHeadersViaPlaywright(opts) {
+    const page = await getPageForTargetId(opts);
+    ensurePageState(page);
+    await page.context().setExtraHTTPHeaders(opts.headers);
+}
+export async function setHttpCredentialsViaPlaywright(opts) {
+    const page = await getPageForTargetId(opts);
+    ensurePageState(page);
+    if (opts.clear) {
+        await page.context().setHTTPCredentials(null);
+        return;
+    }
+    const username = String(opts.username ?? "");
+    const password = String(opts.password ?? "");
+    if (!username) {
+        throw new Error("username is required (or set clear=true)");
+    }
+    await page.context().setHTTPCredentials({ username, password });
+}
+export async function setGeolocationViaPlaywright(opts) {
+    const page = await getPageForTargetId(opts);
+    ensurePageState(page);
+    const context = page.context();
+    if (opts.clear) {
+        await context.setGeolocation(null);
+        await context.clearPermissions().catch(() => { });
+        return;
+    }
+    if (typeof opts.latitude !== "number" || typeof opts.longitude !== "number") {
+        throw new Error("latitude and longitude are required (or set clear=true)");
+    }
+    await context.setGeolocation({
+        latitude: opts.latitude,
+        longitude: opts.longitude,
+        accuracy: typeof opts.accuracy === "number" ? opts.accuracy : undefined,
+    });
+    const origin = opts.origin?.trim() ||
+        (() => {
+            try {
+                return new URL(page.url()).origin;
+            }
+            catch {
+                return "";
+            }
+        })();
+    if (origin) {
+        await context.grantPermissions(["geolocation"], { origin }).catch(() => { });
+    }
+}
+export async function emulateMediaViaPlaywright(opts) {
+    const page = await getPageForTargetId(opts);
+    ensurePageState(page);
+    await page.emulateMedia({ colorScheme: opts.colorScheme });
+}
+export async function setLocaleViaPlaywright(opts) {
+    const page = await getPageForTargetId(opts);
+    ensurePageState(page);
+    const locale = String(opts.locale ?? "").trim();
+    if (!locale) {
+        throw new Error("locale is required");
+    }
+    await withCdpSession(page, async (session) => {
+        try {
+            await session.send("Emulation.setLocaleOverride", { locale });
+        }
+        catch (err) {
+            if (String(err).includes("Another locale override is already in effect")) {
+                return;
+            }
+            throw err;
+        }
+    });
+}
+export async function setTimezoneViaPlaywright(opts) {
+    const page = await getPageForTargetId(opts);
+    ensurePageState(page);
+    const timezoneId = String(opts.timezoneId ?? "").trim();
+    if (!timezoneId) {
+        throw new Error("timezoneId is required");
+    }
+    await withCdpSession(page, async (session) => {
+        try {
+            await session.send("Emulation.setTimezoneOverride", { timezoneId });
+        }
+        catch (err) {
+            const msg = String(err);
+            if (msg.includes("Timezone override is already in effect")) {
+                return;
+            }
+            if (msg.includes("Invalid timezone")) {
+                throw new Error(`Invalid timezone ID: ${timezoneId}`, { cause: err });
+            }
+            throw err;
+        }
+    });
+}
+export async function setDeviceViaPlaywright(opts) {
+    const page = await getPageForTargetId(opts);
+    ensurePageState(page);
+    const name = String(opts.name ?? "").trim();
+    if (!name) {
+        throw new Error("device name is required");
+    }
+    const descriptor = playwrightDevices[name];
+    if (!descriptor) {
+        throw new Error(`Unknown device "${name}".`);
+    }
+    if (descriptor.viewport) {
+        await page.setViewportSize({
+            width: descriptor.viewport.width,
+            height: descriptor.viewport.height,
+        });
+    }
+    await withCdpSession(page, async (session) => {
+        if (descriptor.userAgent || descriptor.locale) {
+            await session.send("Emulation.setUserAgentOverride", {
+                userAgent: descriptor.userAgent ?? "",
+                acceptLanguage: descriptor.locale ?? undefined,
+            });
+        }
+        if (descriptor.viewport) {
+            await session.send("Emulation.setDeviceMetricsOverride", {
+                mobile: Boolean(descriptor.isMobile),
+                width: descriptor.viewport.width,
+                height: descriptor.viewport.height,
+                deviceScaleFactor: descriptor.deviceScaleFactor ?? 1,
+                screenWidth: descriptor.viewport.width,
+                screenHeight: descriptor.viewport.height,
+            });
+        }
+        if (descriptor.hasTouch) {
+            await session.send("Emulation.setTouchEmulationEnabled", {
+                enabled: true,
+            });
+        }
+    });
+}
+//# sourceMappingURL=pw-tools-core.state.js.map

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

@@ -0,0 +1,48 @@
+export declare function cookiesGetViaPlaywright(opts: {
+    cdpUrl: string;
+    targetId?: string;
+}): Promise<{
+    cookies: unknown[];
+}>;
+export declare function cookiesSetViaPlaywright(opts: {
+    cdpUrl: string;
+    targetId?: string;
+    cookie: {
+        name: string;
+        value: string;
+        url?: string;
+        domain?: string;
+        path?: string;
+        expires?: number;
+        httpOnly?: boolean;
+        secure?: boolean;
+        sameSite?: "Lax" | "None" | "Strict";
+    };
+}): Promise<void>;
+export declare function cookiesClearViaPlaywright(opts: {
+    cdpUrl: string;
+    targetId?: string;
+}): Promise<void>;
+type StorageKind = "local" | "session";
+export declare function storageGetViaPlaywright(opts: {
+    cdpUrl: string;
+    targetId?: string;
+    kind: StorageKind;
+    key?: string;
+}): Promise<{
+    values: Record<string, string>;
+}>;
+export declare function storageSetViaPlaywright(opts: {
+    cdpUrl: string;
+    targetId?: string;
+    kind: StorageKind;
+    key: string;
+    value: string;
+}): Promise<void>;
+export declare function storageClearViaPlaywright(opts: {
+    cdpUrl: string;
+    targetId?: string;
+    kind: StorageKind;
+}): Promise<void>;
+export {};
+//# sourceMappingURL=pw-tools-core.storage.d.ts.map