@hera-al/browser-server 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TGP / Hera Artificial Life
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,212 @@
+# @hera-al/browser-server
+
+> **Part of [Hera Artificial Life](https://github.com/ltoscano/hera_al)** — an opinionated AI assistant platform that runs locally on your machine. This package provides the browser automation layer used by Hera agents to interact with the web. It can also be used independently in any Node.js project.
+
+Local browser automation server powered by [Playwright](https://playwright.dev/) and the Chrome DevTools Protocol (CDP).
+
+Exposes a lightweight HTTP API on `127.0.0.1` that lets AI agents — or any local process — launch, control, and inspect browser sessions without embedding a full browser SDK.
+
+## Features
+
+- **Launch or attach** to a local Chrome/Chromium instance via CDP
+- **Multi-profile** support (separate CDP ports, colors, isolated sessions)
+- **Tab management** — open, list, focus, close tabs
+- **Page actions** — click, type, hover, scroll, drag, select, fill forms, press keys, navigate
+- **Snapshots** — role-based (Playwright), ARIA, DOM, text/HTML extraction, CSS query, AI-digest
+- **Screenshots & PDF** — full-page or element-level capture
+- **Storage** — read/write cookies, localStorage, sessionStorage
+- **JavaScript evaluation** — run arbitrary JS in page context
+- **Wait conditions** — wait for text, selector, URL, load state, or custom function
+- **Standalone or embedded** — run as a standalone process or import into your own Node.js app
+
+## Install
+
+```bash
+npm install @hera-al/browser-server
+```
+
+> **Peer dependency:** Requires `playwright-core` ≥ 1.50 and a Chromium-based browser available on the system.
+
+## Quick start
+
+### Standalone (CLI)
+
+```bash
+npx hera-browser --port 3002 --headless false
+```
+
+All CLI flags:
+
+| Flag               | Default | Description                              |
+| ------------------ | ------- | ---------------------------------------- |
+| `--port`           | `3002`  | HTTP control port                        |
+| `--headless`       | `false` | Run Chrome headless                      |
+| `--noSandbox`      | `false` | Disable Chrome sandbox (CI/Docker)       |
+| `--attachOnly`     | `false` | Never launch Chrome, only attach via CDP |
+| `--executablePath` | —       | Custom Chrome/Chromium binary path       |
+
+### Programmatic
+
+```ts
+import { startBrowserServer, stopBrowserServer } from "@hera-al/browser-server";
+import { resolveBrowserConfig, BrowserConfigSchema } from "@hera-al/browser-server/config";
+
+const config = resolveBrowserConfig(
+  BrowserConfigSchema.parse({
+    enabled: true,
+    controlPort: 3002,
+    headless: false,
+  })
+);
+
+await startBrowserServer(config);
+
+// ... your app logic ...
+
+await stopBrowserServer();
+```
+
+## HTTP API Reference
+
+All endpoints listen on `http://127.0.0.1:{port}`. Responses are JSON with an `ok` boolean.
+
+### Status & lifecycle
+
+| Method | Path     | Description                       |
+| ------ | -------- | --------------------------------- |
+| GET    | `/`      | Check browser status (`running` / `stopped`) |
+| POST   | `/start` | Launch or attach to the browser   |
+| POST   | `/stop`  | Stop the browser                  |
+
+### Tabs
+
+| Method | Path          | Description   |
+| ------ | ------------- | ------------- |
+| GET    | `/tabs`       | List all open tabs |
+| POST   | `/tabs/open`  | Open a new tab (`{ url }`) |
+| POST   | `/tabs/focus` | Focus a tab (`{ id }`) |
+| DELETE | `/tabs/:id`   | Close a tab   |
+
+### Actions (`POST /act`)
+
+Send `{ kind, ...params }` to perform a page action:
+
+| Kind         | Key params                                                    |
+| ------------ | ------------------------------------------------------------- |
+| `navigate`   | `url`, `timeoutMs?`                                           |
+| `click`      | `ref`, `doubleClick?`, `button?`, `modifiers?`                |
+| `type`       | `ref`, `text`, `submit?`, `slowly?`                           |
+| `press`      | `key`, `delayMs?`                                             |
+| `hover`      | `ref`                                                         |
+| `scroll`     | `ref`                                                         |
+| `drag`       | `startRef`, `endRef`                                          |
+| `select`     | `ref`, `values`                                               |
+| `fill_form`  | `fields: [{ ref, type, value }]`                              |
+| `screenshot` | `ref?`, `element?`, `fullPage?`, `type?` (`png` \| `jpeg`)   |
+| `evaluate`   | `fn` (JS string), `ref?`                                      |
+| `wait`       | `timeMs?`, `text?`, `textGone?`, `selector?`, `url?`, `loadState?`, `fn?` |
+
+All actions accept optional `profile`, `targetId`, and `timeoutMs`.
+
+### Snapshots (`GET /snapshot`)
+
+Query params:
+
+| Param           | Values                                      | Description                        |
+| --------------- | ------------------------------------------- | ---------------------------------- |
+| `mode`          | `role` (default), `aria`, `dom`, `text`, `html`, `ai`, `query` | Snapshot format |
+| `selector`      | CSS selector string                         | Scope to element (for `text`, `html`, `query`) |
+| `frameSelector` | CSS selector string                         | Target iframe                      |
+| `interactive`   | `true` / `false`                            | Include interactive elements only  |
+| `compact`       | `true` / `false`                            | Compact output                     |
+
+### Screenshots & PDF
+
+| Method | Path          | Description                            |
+| ------ | ------------- | -------------------------------------- |
+| POST   | `/screenshot` | Capture screenshot (`{ fullPage?, type?, ref?, element? }`) |
+| POST   | `/pdf`        | Export page as PDF                     |
+
+### Storage
+
+| Method | Path              | Description                   |
+| ------ | ----------------- | ----------------------------- |
+| GET    | `/cookies`        | Get all cookies               |
+| POST   | `/cookies`        | Set a cookie (`{ cookie }`)   |
+| DELETE | `/cookies`        | Clear all cookies             |
+| GET    | `/storage/:kind`  | Get localStorage or sessionStorage (`kind` = `local` \| `session`) |
+| POST   | `/storage/:kind`  | Set a key (`{ key, value }`)  |
+| DELETE | `/storage/:kind`  | Clear storage                 |
+
+## Configuration
+
+When using the programmatic API, the full config schema is:
+
+```ts
+{
+  enabled: boolean;           // default: false
+  controlPort: number;        // default: 3002
+  headless: boolean;          // default: false
+  noSandbox: boolean;         // default: false
+  attachOnly: boolean;        // default: false
+  executablePath?: string;    // custom Chrome path
+  remoteCdpTimeoutMs: number; // default: 1500
+  profiles: {
+    [name: string]: {
+      cdpPort?: number;       // default: 9222
+      cdpUrl?: string;        // overrides cdpPort
+      color?: string;         // hex color, default: "#FF4500"
+    }
+  }
+}
+```
+
+### Profiles
+
+Profiles allow managing multiple isolated browser sessions on different CDP ports. The `default` profile is always available.
+
+```ts
+const config = resolveBrowserConfig(
+  BrowserConfigSchema.parse({
+    enabled: true,
+    profiles: {
+      default: { cdpPort: 9222 },
+      social: { cdpPort: 9223, color: "#1DA1F2" },
+    },
+  })
+);
+```
+
+Pass `?profile=social` (GET) or `{ "profile": "social" }` (POST) to target a specific profile.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────┐
+│          HTTP API (Hono)                │
+│  basic · tabs · act · snapshot · storage│
+└────────────────┬────────────────────────┘
+                 │
+         ┌───────┴───────┐
+         │ BrowserContext │  ← multi-profile manager
+         └───────┬───────┘
+                 │
+    ┌────────────┼────────────┐
+    │            │            │
+ Chrome      Playwright    CDP
+ launcher    session mgr   helpers
+```
+
+- **Hono** — lightweight HTTP framework (< 15 KB)
+- **Playwright** — used for page interactions, snapshots, screenshots (connects to existing Chrome via CDP)
+- **CDP direct** — used for ARIA/DOM snapshots, tab management, WebSocket resolution
+
+## Requirements
+
+- Node.js ≥ 18
+- Chrome or Chromium installed locally (or provide `executablePath`)
+- macOS, Linux, or WSL
+
+## License
+
+[MIT](./LICENSE) — © 2026 TGP / Hera Artificial Life

package/dist/config.d.ts

@@ -0,0 +1,44 @@
+import { z } from "zod";
+export declare const BrowserProfileSchema: z.ZodObject<{
+    cdpPort: z.ZodOptional<z.ZodNumber>;
+    cdpUrl: z.ZodOptional<z.ZodString>;
+    color: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>;
+export declare const BrowserConfigSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    controlPort: z.ZodDefault<z.ZodNumber>;
+    headless: z.ZodDefault<z.ZodBoolean>;
+    noSandbox: z.ZodDefault<z.ZodBoolean>;
+    attachOnly: z.ZodDefault<z.ZodBoolean>;
+    executablePath: z.ZodOptional<z.ZodString>;
+    remoteCdpTimeoutMs: z.ZodDefault<z.ZodNumber>;
+    profiles: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+        cdpPort: z.ZodOptional<z.ZodNumber>;
+        cdpUrl: z.ZodOptional<z.ZodString>;
+        color: z.ZodDefault<z.ZodString>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type BrowserConfig = z.infer<typeof BrowserConfigSchema>;
+export type BrowserProfileConfig = z.infer<typeof BrowserProfileSchema>;
+export type ResolvedBrowserConfig = {
+    enabled: boolean;
+    controlPort: number;
+    remoteCdpTimeoutMs: number;
+    color: string;
+    executablePath?: string;
+    headless: boolean;
+    noSandbox: boolean;
+    attachOnly: boolean;
+    profiles: Record<string, BrowserProfileConfig>;
+};
+export type ResolvedBrowserProfile = {
+    name: string;
+    cdpPort: number;
+    cdpUrl: string;
+    cdpHost: string;
+    cdpIsLoopback: boolean;
+    color: string;
+};
+export declare function resolveBrowserConfig(cfg: BrowserConfig | undefined): ResolvedBrowserConfig;
+export declare function resolveProfile(resolved: ResolvedBrowserConfig, profileName: string): ResolvedBrowserProfile | null;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.js

@@ -0,0 +1,74 @@
+import { z } from "zod";
+import { isLoopbackHost } from "./utils.js";
+// --- Zod Schemas ---
+export const BrowserProfileSchema = z.object({
+    cdpPort: z.number().optional(),
+    cdpUrl: z.string().optional(),
+    color: z.string().default("#FF4500"),
+});
+export const BrowserConfigSchema = z.object({
+    enabled: z.boolean().default(false),
+    controlPort: z.number().default(3002),
+    headless: z.boolean().default(false),
+    noSandbox: z.boolean().default(false),
+    attachOnly: z.boolean().default(false),
+    executablePath: z.string().optional(),
+    remoteCdpTimeoutMs: z.number().default(1500),
+    profiles: z.record(z.string(), BrowserProfileSchema).default({
+        default: { cdpPort: 9222, color: "#FF4500" },
+    }),
+});
+// --- Resolution ---
+function normalizeHexColor(raw) {
+    const value = (raw ?? "").trim();
+    if (!value)
+        return "#FF4500";
+    const normalized = value.startsWith("#") ? value : `#${value}`;
+    if (!/^#[0-9a-fA-F]{6}$/.test(normalized))
+        return "#FF4500";
+    return normalized.toUpperCase();
+}
+export function resolveBrowserConfig(cfg) {
+    const defaults = BrowserConfigSchema.parse(cfg ?? {});
+    return {
+        enabled: defaults.enabled,
+        controlPort: defaults.controlPort,
+        remoteCdpTimeoutMs: defaults.remoteCdpTimeoutMs,
+        color: normalizeHexColor(Object.values(defaults.profiles)[0]?.color),
+        executablePath: defaults.executablePath?.trim() || undefined,
+        headless: defaults.headless,
+        noSandbox: defaults.noSandbox,
+        attachOnly: defaults.attachOnly,
+        profiles: defaults.profiles,
+    };
+}
+export function resolveProfile(resolved, profileName) {
+    const profile = resolved.profiles[profileName];
+    if (!profile)
+        return null;
+    const rawUrl = profile.cdpUrl?.trim() ?? "";
+    let cdpHost = "127.0.0.1";
+    let cdpPort = profile.cdpPort ?? 0;
+    let cdpUrl = "";
+    if (rawUrl) {
+        const parsed = new URL(rawUrl);
+        cdpHost = parsed.hostname;
+        cdpPort = parsed.port ? parseInt(parsed.port, 10) : (parsed.protocol === "https:" ? 443 : 80);
+        cdpUrl = parsed.toString().replace(/\/$/, "");
+    }
+    else if (cdpPort) {
+        cdpUrl = `http://127.0.0.1:${cdpPort}`;
+    }
+    else {
+        return null;
+    }
+    return {
+        name: profileName,
+        cdpPort,
+        cdpUrl,
+        cdpHost,
+        cdpIsLoopback: isLoopbackHost(cdpHost),
+        color: normalizeHexColor(profile.color),
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/core/cdp.d.ts

@@ -0,0 +1,124 @@
+export { appendCdpPath, fetchJson, fetchOk, getHeadersWithAuth } from "./cdp.helpers.js";
+export declare function normalizeCdpWsUrl(wsUrl: string, cdpUrl: string): string;
+export declare function captureScreenshotPng(opts: {
+    wsUrl: string;
+    fullPage?: boolean;
+}): Promise<Buffer>;
+export declare function captureScreenshot(opts: {
+    wsUrl: string;
+    fullPage?: boolean;
+    format?: "png" | "jpeg";
+    quality?: number;
+}): Promise<Buffer>;
+export declare function createTargetViaCdp(opts: {
+    cdpUrl: string;
+    url: string;
+}): Promise<{
+    targetId: string;
+}>;
+export type CdpRemoteObject = {
+    type: string;
+    subtype?: string;
+    value?: unknown;
+    description?: string;
+    unserializableValue?: string;
+    preview?: unknown;
+};
+export type CdpExceptionDetails = {
+    text?: string;
+    lineNumber?: number;
+    columnNumber?: number;
+    exception?: CdpRemoteObject;
+    stackTrace?: unknown;
+};
+export declare function evaluateJavaScript(opts: {
+    wsUrl: string;
+    expression: string;
+    awaitPromise?: boolean;
+    returnByValue?: boolean;
+}): Promise<{
+    result: CdpRemoteObject;
+    exceptionDetails?: CdpExceptionDetails;
+}>;
+export type AriaSnapshotNode = {
+    ref: string;
+    role: string;
+    name: string;
+    value?: string;
+    description?: string;
+    backendDOMNodeId?: number;
+    depth: number;
+};
+export type RawAXNode = {
+    nodeId?: string;
+    role?: {
+        value?: string;
+    };
+    name?: {
+        value?: string;
+    };
+    value?: {
+        value?: string;
+    };
+    description?: {
+        value?: string;
+    };
+    childIds?: string[];
+    backendDOMNodeId?: number;
+};
+export declare function formatAriaSnapshot(nodes: RawAXNode[], limit: number): AriaSnapshotNode[];
+export declare function snapshotAria(opts: {
+    wsUrl: string;
+    limit?: number;
+}): Promise<{
+    nodes: AriaSnapshotNode[];
+}>;
+export declare function snapshotDom(opts: {
+    wsUrl: string;
+    limit?: number;
+    maxTextChars?: number;
+}): Promise<{
+    nodes: DomSnapshotNode[];
+}>;
+export type DomSnapshotNode = {
+    ref: string;
+    parentRef: string | null;
+    depth: number;
+    tag: string;
+    id?: string;
+    className?: string;
+    role?: string;
+    name?: string;
+    text?: string;
+    href?: string;
+    type?: string;
+    value?: string;
+};
+export declare function getDomText(opts: {
+    wsUrl: string;
+    format: "html" | "text";
+    maxChars?: number;
+    selector?: string;
+}): Promise<{
+    text: string;
+}>;
+export declare function querySelector(opts: {
+    wsUrl: string;
+    selector: string;
+    limit?: number;
+    maxTextChars?: number;
+    maxHtmlChars?: number;
+}): Promise<{
+    matches: QueryMatch[];
+}>;
+export type QueryMatch = {
+    index: number;
+    tag: string;
+    id?: string;
+    className?: string;
+    text?: string;
+    value?: string;
+    href?: string;
+    outerHTML?: string;
+};
+//# sourceMappingURL=cdp.d.ts.map

package/dist/core/cdp.helpers.d.ts

@@ -0,0 +1,14 @@
+import { isLoopbackHost } from "../utils.js";
+export { isLoopbackHost };
+export type CdpSendFn = (method: string, params?: Record<string, unknown>, sessionId?: string) => Promise<unknown>;
+export declare function getHeadersWithAuth(url: string, headers?: Record<string, string>): {
+    [x: string]: string;
+};
+export declare function appendCdpPath(cdpUrl: string, path: string): string;
+export declare function fetchJson<T>(url: string, timeoutMs?: number, init?: RequestInit): Promise<T>;
+export declare function fetchOk(url: string, timeoutMs?: number, init?: RequestInit): Promise<void>;
+export declare function withCdpSocket<T>(wsUrl: string, fn: (send: CdpSendFn) => Promise<T>, opts?: {
+    headers?: Record<string, string>;
+    handshakeTimeoutMs?: number;
+}): Promise<T>;
+//# sourceMappingURL=cdp.helpers.d.ts.map

package/dist/core/cdp.helpers.js

@@ -0,0 +1,148 @@
+import WebSocket from "ws";
+import { isLoopbackHost, rawDataToString } from "../utils.js";
+export { isLoopbackHost };
+export function getHeadersWithAuth(url, headers = {}) {
+    const mergedHeaders = { ...headers };
+    try {
+        const parsed = new URL(url);
+        const hasAuthHeader = Object.keys(mergedHeaders).some((key) => key.toLowerCase() === "authorization");
+        if (hasAuthHeader) {
+            return mergedHeaders;
+        }
+        if (parsed.username || parsed.password) {
+            const auth = Buffer.from(`${parsed.username}:${parsed.password}`).toString("base64");
+            return { ...mergedHeaders, Authorization: `Basic ${auth}` };
+        }
+    }
+    catch {
+        // ignore
+    }
+    return mergedHeaders;
+}
+export function appendCdpPath(cdpUrl, path) {
+    const url = new URL(cdpUrl);
+    const basePath = url.pathname.replace(/\/$/, "");
+    const suffix = path.startsWith("/") ? path : `/${path}`;
+    url.pathname = `${basePath}${suffix}`;
+    return url.toString();
+}
+function createCdpSender(ws) {
+    let nextId = 1;
+    const pending = new Map();
+    const send = (method, params, sessionId) => {
+        const id = nextId++;
+        const msg = { id, method, params, sessionId };
+        ws.send(JSON.stringify(msg));
+        return new Promise((resolve, reject) => {
+            pending.set(id, { resolve, reject });
+        });
+    };
+    const closeWithError = (err) => {
+        for (const [, p] of pending) {
+            p.reject(err);
+        }
+        pending.clear();
+        try {
+            ws.close();
+        }
+        catch {
+            // ignore
+        }
+    };
+    ws.on("error", (err) => {
+        closeWithError(err instanceof Error ? err : new Error(String(err)));
+    });
+    ws.on("message", (data) => {
+        try {
+            const parsed = JSON.parse(rawDataToString(data));
+            if (typeof parsed.id !== "number") {
+                return;
+            }
+            const p = pending.get(parsed.id);
+            if (!p) {
+                return;
+            }
+            pending.delete(parsed.id);
+            if (parsed.error?.message) {
+                p.reject(new Error(parsed.error.message));
+                return;
+            }
+            p.resolve(parsed.result);
+        }
+        catch {
+            // ignore
+        }
+    });
+    ws.on("close", () => {
+        closeWithError(new Error("CDP socket closed"));
+    });
+    return { send, closeWithError };
+}
+export async function fetchJson(url, timeoutMs = 1500, init) {
+    const ctrl = new AbortController();
+    const t = setTimeout(() => ctrl.abort(), timeoutMs);
+    try {
+        const headers = getHeadersWithAuth(url, init?.headers || {});
+        const res = await fetch(url, { ...init, headers, signal: ctrl.signal });
+        if (!res.ok) {
+            throw new Error(`HTTP ${res.status}`);
+        }
+        return (await res.json());
+    }
+    finally {
+        clearTimeout(t);
+    }
+}
+export async function fetchOk(url, timeoutMs = 1500, init) {
+    const ctrl = new AbortController();
+    const t = setTimeout(() => ctrl.abort(), timeoutMs);
+    try {
+        const headers = getHeadersWithAuth(url, init?.headers || {});
+        const res = await fetch(url, { ...init, headers, signal: ctrl.signal });
+        if (!res.ok) {
+            throw new Error(`HTTP ${res.status}`);
+        }
+    }
+    finally {
+        clearTimeout(t);
+    }
+}
+export async function withCdpSocket(wsUrl, fn, opts) {
+    const headers = getHeadersWithAuth(wsUrl, opts?.headers ?? {});
+    const handshakeTimeoutMs = typeof opts?.handshakeTimeoutMs === "number" && Number.isFinite(opts.handshakeTimeoutMs)
+        ? Math.max(1, Math.floor(opts.handshakeTimeoutMs))
+        : 5000;
+    const ws = new WebSocket(wsUrl, {
+        handshakeTimeout: handshakeTimeoutMs,
+        ...(Object.keys(headers).length ? { headers } : {}),
+    });
+    const { send, closeWithError } = createCdpSender(ws);
+    const openPromise = new Promise((resolve, reject) => {
+        ws.once("open", () => resolve());
+        ws.once("error", (err) => reject(err));
+        ws.once("close", () => reject(new Error("CDP socket closed")));
+    });
+    try {
+        await openPromise;
+    }
+    catch (err) {
+        closeWithError(err instanceof Error ? err : new Error(String(err)));
+        throw err;
+    }
+    try {
+        return await fn(send);
+    }
+    catch (err) {
+        closeWithError(err instanceof Error ? err : new Error(String(err)));
+        throw err;
+    }
+    finally {
+        try {
+            ws.close();
+        }
+        catch {
+            // ignore
+        }
+    }
+}
+//# sourceMappingURL=cdp.helpers.js.map