@hera-al/browser-server 1.0.0

package/dist/core/cdp.js

@@ -0,0 +1,309 @@
+import { appendCdpPath, fetchJson, isLoopbackHost, withCdpSocket } from "./cdp.helpers.js";
+export { appendCdpPath, fetchJson, fetchOk, getHeadersWithAuth } from "./cdp.helpers.js";
+export function normalizeCdpWsUrl(wsUrl, cdpUrl) {
+    const ws = new URL(wsUrl);
+    const cdp = new URL(cdpUrl);
+    if (isLoopbackHost(ws.hostname) && !isLoopbackHost(cdp.hostname)) {
+        ws.hostname = cdp.hostname;
+        const cdpPort = cdp.port || (cdp.protocol === "https:" ? "443" : "80");
+        if (cdpPort) {
+            ws.port = cdpPort;
+        }
+        ws.protocol = cdp.protocol === "https:" ? "wss:" : "ws:";
+    }
+    if (cdp.protocol === "https:" && ws.protocol === "ws:") {
+        ws.protocol = "wss:";
+    }
+    if (!ws.username && !ws.password && (cdp.username || cdp.password)) {
+        ws.username = cdp.username;
+        ws.password = cdp.password;
+    }
+    for (const [key, value] of cdp.searchParams.entries()) {
+        if (!ws.searchParams.has(key)) {
+            ws.searchParams.append(key, value);
+        }
+    }
+    return ws.toString();
+}
+export async function captureScreenshotPng(opts) {
+    return await captureScreenshot({
+        wsUrl: opts.wsUrl,
+        fullPage: opts.fullPage,
+        format: "png",
+    });
+}
+export async function captureScreenshot(opts) {
+    return await withCdpSocket(opts.wsUrl, async (send) => {
+        await send("Page.enable");
+        let clip;
+        if (opts.fullPage) {
+            const metrics = (await send("Page.getLayoutMetrics"));
+            const size = metrics?.cssContentSize ?? metrics?.contentSize;
+            const width = Number(size?.width ?? 0);
+            const height = Number(size?.height ?? 0);
+            if (width > 0 && height > 0) {
+                clip = { x: 0, y: 0, width, height, scale: 1 };
+            }
+        }
+        const format = opts.format ?? "png";
+        const quality = format === "jpeg" ? Math.max(0, Math.min(100, Math.round(opts.quality ?? 85))) : undefined;
+        const result = (await send("Page.captureScreenshot", {
+            format,
+            ...(quality !== undefined ? { quality } : {}),
+            fromSurface: true,
+            captureBeyondViewport: true,
+            ...(clip ? { clip } : {}),
+        }));
+        const base64 = result?.data;
+        if (!base64) {
+            throw new Error("Screenshot failed: missing data");
+        }
+        return Buffer.from(base64, "base64");
+    });
+}
+export async function createTargetViaCdp(opts) {
+    const version = await fetchJson(appendCdpPath(opts.cdpUrl, "/json/version"), 1500);
+    const wsUrlRaw = String(version?.webSocketDebuggerUrl ?? "").trim();
+    const wsUrl = wsUrlRaw ? normalizeCdpWsUrl(wsUrlRaw, opts.cdpUrl) : "";
+    if (!wsUrl) {
+        throw new Error("CDP /json/version missing webSocketDebuggerUrl");
+    }
+    return await withCdpSocket(wsUrl, async (send) => {
+        const created = (await send("Target.createTarget", { url: opts.url }));
+        const targetId = String(created?.targetId ?? "").trim();
+        if (!targetId) {
+            throw new Error("CDP Target.createTarget returned no targetId");
+        }
+        return { targetId };
+    });
+}
+export async function evaluateJavaScript(opts) {
+    return await withCdpSocket(opts.wsUrl, async (send) => {
+        await send("Runtime.enable").catch(() => { });
+        const evaluated = (await send("Runtime.evaluate", {
+            expression: opts.expression,
+            awaitPromise: Boolean(opts.awaitPromise),
+            returnByValue: opts.returnByValue ?? true,
+            userGesture: true,
+            includeCommandLineAPI: true,
+        }));
+        const result = evaluated?.result;
+        if (!result) {
+            throw new Error("CDP Runtime.evaluate returned no result");
+        }
+        return { result, exceptionDetails: evaluated.exceptionDetails };
+    });
+}
+function axValue(v) {
+    if (!v || typeof v !== "object") {
+        return "";
+    }
+    const value = v.value;
+    if (typeof value === "string") {
+        return value;
+    }
+    if (typeof value === "number" || typeof value === "boolean") {
+        return String(value);
+    }
+    return "";
+}
+export function formatAriaSnapshot(nodes, limit) {
+    const byId = new Map();
+    for (const n of nodes) {
+        if (n.nodeId) {
+            byId.set(n.nodeId, n);
+        }
+    }
+    // Heuristic: pick a root-ish node (one that is not referenced as a child), else first.
+    const referenced = new Set();
+    for (const n of nodes) {
+        for (const c of n.childIds ?? []) {
+            referenced.add(c);
+        }
+    }
+    const root = nodes.find((n) => n.nodeId && !referenced.has(n.nodeId)) ?? nodes[0];
+    if (!root?.nodeId) {
+        return [];
+    }
+    const out = [];
+    const stack = [{ id: root.nodeId, depth: 0 }];
+    while (stack.length && out.length < limit) {
+        const popped = stack.pop();
+        if (!popped) {
+            break;
+        }
+        const { id, depth } = popped;
+        const n = byId.get(id);
+        if (!n) {
+            continue;
+        }
+        const role = axValue(n.role);
+        const name = axValue(n.name);
+        const value = axValue(n.value);
+        const description = axValue(n.description);
+        const ref = `ax${out.length + 1}`;
+        out.push({
+            ref,
+            role: role || "unknown",
+            name: name || "",
+            ...(value ? { value } : {}),
+            ...(description ? { description } : {}),
+            ...(typeof n.backendDOMNodeId === "number" ? { backendDOMNodeId: n.backendDOMNodeId } : {}),
+            depth,
+        });
+        const children = (n.childIds ?? []).filter((c) => byId.has(c));
+        for (let i = children.length - 1; i >= 0; i--) {
+            const child = children[i];
+            if (child) {
+                stack.push({ id: child, depth: depth + 1 });
+            }
+        }
+    }
+    return out;
+}
+export async function snapshotAria(opts) {
+    const limit = Math.max(1, Math.min(2000, Math.floor(opts.limit ?? 500)));
+    return await withCdpSocket(opts.wsUrl, async (send) => {
+        await send("Accessibility.enable").catch(() => { });
+        const res = (await send("Accessibility.getFullAXTree"));
+        const nodes = Array.isArray(res?.nodes) ? res.nodes : [];
+        return { nodes: formatAriaSnapshot(nodes, limit) };
+    });
+}
+export async function snapshotDom(opts) {
+    const limit = Math.max(1, Math.min(5000, Math.floor(opts.limit ?? 800)));
+    const maxTextChars = Math.max(0, Math.min(5000, Math.floor(opts.maxTextChars ?? 220)));
+    const expression = `(() => {
+    const maxNodes = ${JSON.stringify(limit)};
+    const maxText = ${JSON.stringify(maxTextChars)};
+    const nodes = [];
+    const root = document.documentElement;
+    if (!root) return { nodes };
+    const stack = [{ el: root, depth: 0, parentRef: null }];
+    while (stack.length && nodes.length < maxNodes) {
+      const cur = stack.pop();
+      const el = cur.el;
+      if (!el || el.nodeType !== 1) continue;
+      const ref = "n" + String(nodes.length + 1);
+      const tag = (el.tagName || "").toLowerCase();
+      const id = el.id ? String(el.id) : undefined;
+      const className = el.className ? String(el.className).slice(0, 300) : undefined;
+      const role = el.getAttribute && el.getAttribute("role") ? String(el.getAttribute("role")) : undefined;
+      const name = el.getAttribute && el.getAttribute("aria-label") ? String(el.getAttribute("aria-label")) : undefined;
+      let text = "";
+      try { text = String(el.innerText || "").trim(); } catch {}
+      if (maxText && text.length > maxText) text = text.slice(0, maxText) + "…";
+      const href = (el.href !== undefined && el.href !== null) ? String(el.href) : undefined;
+      const type = (el.type !== undefined && el.type !== null) ? String(el.type) : undefined;
+      const value = (el.value !== undefined && el.value !== null) ? String(el.value).slice(0, 500) : undefined;
+      nodes.push({
+        ref,
+        parentRef: cur.parentRef,
+        depth: cur.depth,
+        tag,
+        ...(id ? { id } : {}),
+        ...(className ? { className } : {}),
+        ...(role ? { role } : {}),
+        ...(name ? { name } : {}),
+        ...(text ? { text } : {}),
+        ...(href ? { href } : {}),
+        ...(type ? { type } : {}),
+        ...(value ? { value } : {}),
+      });
+      const children = el.children ? Array.from(el.children) : [];
+      for (let i = children.length - 1; i >= 0; i--) {
+        stack.push({ el: children[i], depth: cur.depth + 1, parentRef: ref });
+      }
+    }
+    return { nodes };
+  })()`;
+    const evaluated = await evaluateJavaScript({
+        wsUrl: opts.wsUrl,
+        expression,
+        awaitPromise: true,
+        returnByValue: true,
+    });
+    const value = evaluated.result?.value;
+    if (!value || typeof value !== "object") {
+        return { nodes: [] };
+    }
+    const nodes = value.nodes;
+    return { nodes: Array.isArray(nodes) ? nodes : [] };
+}
+export async function getDomText(opts) {
+    const maxChars = Math.max(0, Math.min(5_000_000, Math.floor(opts.maxChars ?? 200_000)));
+    const selectorExpr = opts.selector ? JSON.stringify(opts.selector) : "null";
+    const expression = `(() => {
+    const fmt = ${JSON.stringify(opts.format)};
+    const max = ${JSON.stringify(maxChars)};
+    const sel = ${selectorExpr};
+    const pick = sel ? document.querySelector(sel) : null;
+    let out = "";
+    if (fmt === "text") {
+      const el = pick || document.body || document.documentElement;
+      try { out = String(el && el.innerText ? el.innerText : ""); } catch { out = ""; }
+    } else {
+      const el = pick || document.documentElement;
+      try { out = String(el && el.outerHTML ? el.outerHTML : ""); } catch { out = ""; }
+    }
+    if (max && out.length > max) out = out.slice(0, max) + "\\n<!-- …truncated… -->";
+    return out;
+  })()`;
+    const evaluated = await evaluateJavaScript({
+        wsUrl: opts.wsUrl,
+        expression,
+        awaitPromise: true,
+        returnByValue: true,
+    });
+    const textValue = (evaluated.result?.value ?? "");
+    const text = typeof textValue === "string"
+        ? textValue
+        : typeof textValue === "number" || typeof textValue === "boolean"
+            ? String(textValue)
+            : "";
+    return { text };
+}
+export async function querySelector(opts) {
+    const limit = Math.max(1, Math.min(200, Math.floor(opts.limit ?? 20)));
+    const maxText = Math.max(0, Math.min(5000, Math.floor(opts.maxTextChars ?? 500)));
+    const maxHtml = Math.max(0, Math.min(20000, Math.floor(opts.maxHtmlChars ?? 1500)));
+    const expression = `(() => {
+    const sel = ${JSON.stringify(opts.selector)};
+    const lim = ${JSON.stringify(limit)};
+    const maxText = ${JSON.stringify(maxText)};
+    const maxHtml = ${JSON.stringify(maxHtml)};
+    const els = Array.from(document.querySelectorAll(sel)).slice(0, lim);
+    return els.map((el, i) => {
+      const tag = (el.tagName || "").toLowerCase();
+      const id = el.id ? String(el.id) : undefined;
+      const className = el.className ? String(el.className).slice(0, 300) : undefined;
+      let text = "";
+      try { text = String(el.innerText || "").trim(); } catch {}
+      if (maxText && text.length > maxText) text = text.slice(0, maxText) + "…";
+      const value = (el.value !== undefined && el.value !== null) ? String(el.value).slice(0, 500) : undefined;
+      const href = (el.href !== undefined && el.href !== null) ? String(el.href) : undefined;
+      let outerHTML = "";
+      try { outerHTML = String(el.outerHTML || ""); } catch {}
+      if (maxHtml && outerHTML.length > maxHtml) outerHTML = outerHTML.slice(0, maxHtml) + "…";
+      return {
+        index: i + 1,
+        tag,
+        ...(id ? { id } : {}),
+        ...(className ? { className } : {}),
+        ...(text ? { text } : {}),
+        ...(value ? { value } : {}),
+        ...(href ? { href } : {}),
+        ...(outerHTML ? { outerHTML } : {}),
+      };
+    });
+  })()`;
+    const evaluated = await evaluateJavaScript({
+        wsUrl: opts.wsUrl,
+        expression,
+        awaitPromise: true,
+        returnByValue: true,
+    });
+    const matches = evaluated.result?.value;
+    return { matches: Array.isArray(matches) ? matches : [] };
+}
+//# sourceMappingURL=cdp.js.map

package/dist/core/chrome.d.ts

@@ -0,0 +1,21 @@
+import { type ChildProcessWithoutNullStreams } from "node:child_process";
+import type { ResolvedBrowserConfig, ResolvedBrowserProfile } from "../config.js";
+import { type BrowserExecutable } from "./chrome.executables.js";
+export type { BrowserExecutable } from "./chrome.executables.js";
+export { findChromeExecutableLinux, findChromeExecutableMac, findChromeExecutableWindows, resolveBrowserExecutableForPlatform, } from "./chrome.executables.js";
+export { decorateOpenClawProfile, ensureProfileCleanExit, isProfileDecorated, } from "./chrome.profile-decoration.js";
+export type RunningChrome = {
+    pid: number;
+    exe: BrowserExecutable;
+    userDataDir: string;
+    cdpPort: number;
+    startedAt: number;
+    proc: ChildProcessWithoutNullStreams;
+};
+export declare function resolveUserDataDir(profileName?: string): string;
+export declare function isChromeReachable(cdpUrl: string, timeoutMs?: number): Promise<boolean>;
+export declare function getChromeWebSocketUrl(cdpUrl: string, timeoutMs?: number): Promise<string | null>;
+export declare function isChromeCdpReady(cdpUrl: string, timeoutMs?: number, handshakeTimeoutMs?: number): Promise<boolean>;
+export declare function launchChrome(resolved: ResolvedBrowserConfig, profile: ResolvedBrowserProfile): Promise<RunningChrome>;
+export declare function stopChrome(running: RunningChrome, timeoutMs?: number): Promise<void>;
+//# sourceMappingURL=chrome.d.ts.map

package/dist/core/chrome.executables.d.ts

@@ -0,0 +1,10 @@
+import type { ResolvedBrowserConfig } from "../config.js";
+export type BrowserExecutable = {
+    kind: "brave" | "canary" | "chromium" | "chrome" | "custom" | "edge";
+    path: string;
+};
+export declare function findChromeExecutableMac(): BrowserExecutable | null;
+export declare function findChromeExecutableLinux(): BrowserExecutable | null;
+export declare function findChromeExecutableWindows(): BrowserExecutable | null;
+export declare function resolveBrowserExecutableForPlatform(resolved: ResolvedBrowserConfig, platform: NodeJS.Platform): BrowserExecutable | null;
+//# sourceMappingURL=chrome.executables.d.ts.map