@fusengine/browser-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fusengine
+
+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,175 @@
+# fuse-browser
+
+Agentic browser for AI agents — an **MCP server** and **CLI** on top of
+[Patchright](https://github.com/Kaliiiiiiiiii-Vinyzu/patchright-nodejs) (stealth) with a
+Playwright fallback.
+
+It gives an LLM a **real browser** with: per-country identity (locale/currency/timezone/geo),
+stealth, self-healing actions, an accessibility-style snapshot with stable refs,
+multi-step plans, semantic waits, structured extraction, and **human guardrails** for
+payments and bookings. Because it drives a real Chromium, it reads **Next.js / SPA**
+pages after hydration — not just static HTML.
+
+TypeScript port of the original Python `fusengine-browser-agent`, redesigned around the
+official MCP SDK with a persistent session model, image-content screenshots, and a
+swappable engine layer (Playwright / Patchright / CDP attach).
+
+## Requirements
+
+- Node.js >= 20 (runtime). Bun is the dev toolchain.
+- A Chromium build for the bundled engine:
+
+```bash
+npx patchright install chromium   # stealth engine (default)
+npx playwright install chromium    # fallback engine
+```
+
+## Three ways to get a browser
+
+| Mode | How | Use |
+| --- | --- | --- |
+| **Bundled** | default | Downloaded stealth Chromium (Patchright) |
+| **Installed** | `channel: "chrome" \| "msedge"` | The Chrome/Edge installed on the machine |
+| **Attach (CDP)** | `cdpEndpoint` or `browser_connect` | Drive an already-running browser — **Chrome, Edge, Dia, Arc, Brave** — using the user's real session |
+
+`browser_connect` launches an installed browser with a remote-debugging port and attaches
+to it automatically. Verified end-to-end against **Dia** (Chromium 148).
+
+## CLI
+
+```bash
+# One-shot probe of a real page
+npx fuse-browser probe https://example.com --extract-prices --observe-visual
+
+# Hotels with country identity, proxy routing, replay
+npx fuse-browser probe 'https://www.booking.com/searchresults.html?ss=Tokyo' \
+  --country JP --proxy-map proxies.json --replay --auto-consent --extract-prices
+
+# Use the installed Chrome
+npx fuse-browser probe https://example.com --channel chrome
+```
+
+Sensitive actions (`pay`, `book`, `checkout`, `confirm`, …) are **blocked** unless
+`--approved` is passed.
+
+## MCP server
+
+```json
+{
+  "mcpServers": {
+    "fuse-browser": { "command": "npx", "args": ["-y", "@fusengine/browser-mcp"] }
+  }
+}
+```
+
+### Default browser via env
+
+By default the server uses the bundled stealth Chromium. To pin a different
+default **for every tool call** (without the agent specifying it each time), set
+`FUSE_*` env vars in the MCP config — an explicit per-call argument still wins:
+
+```json
+{
+  "mcpServers": {
+    "fuse-browser": {
+      "command": "npx",
+      "args": ["-y", "@fusengine/browser-mcp"],
+      "env": { "FUSE_CHANNEL": "chrome", "FUSE_CDP_ENDPOINT": "http://localhost:9222" }
+    }
+  }
+}
+```
+
+Supported: `FUSE_ENGINE`, `FUSE_CHANNEL`, `FUSE_CDP_ENDPOINT`, `FUSE_EXECUTABLE_PATH`,
+`FUSE_HEADLESS`, `FUSE_COUNTRY`, `FUSE_CURRENCY`, `FUSE_USER_DATA_DIR`,
+`FUSE_STORAGE_STATE`, `FUSE_OUTPUT_DIR`.
+
+### Tools (23)
+
+| Group | Tools |
+| --- | --- |
+| **One-shot** | `browser_probe`, `browser_probe_html` |
+| **Session** | `browser_open`, `browser_connect`, `browser_status`, `browser_close` |
+| **Navigate** | `browser_navigate`, `browser_back`, `browser_forward`, `browser_wait`, `browser_wait_for` |
+| **Act** | `browser_click`, `browser_fill`, `browser_login`, `browser_scroll`, `browser_press`, `browser_select` |
+| **Agentic** | `browser_snapshot` (indexed refs), `browser_act` (by ref + page diff), `browser_run` (multi-step plan) |
+| **Extract** | `browser_extract` (text/prices/hotels/challenges), `browser_extract_schema` (typed, by CSS selectors) |
+| **Vision** | `browser_screenshot` (page or single element by `ref`) |
+
+Key agentic patterns:
+
+- **`browser_snapshot` → `browser_act`** — snapshot tags each interactive element with a
+  stable `ref`; act on a `ref` deterministically (or by text fallback). `browser_act`
+  returns a **diff** of what changed (added/removed/text/url).
+- **`browser_wait_for`** — wait on a condition (`text` / `selector` / `gone` / `urlContains`),
+  not a fixed delay.
+- **`browser_run`** — execute an ordered plan (navigate/act/wait/extract) in one call,
+  stopping at the first failure. Guardrails apply to the whole plan.
+
+A `runs` resource exposes the JSON reports and screenshots written under `runs/`.
+
+## Library
+
+```ts
+import { BrowserAgent } from "fuse-browser";
+
+const agent = new BrowserAgent({ countryCode: "CH", engine: "patchright" });
+const report = await agent.probe("https://example.com", { extractPrices: true });
+```
+
+## Development
+
+```bash
+bun install
+bun run typecheck       # tsc strict, no emit
+bun test tests/unit     # pure unit tests
+bun run test:integration # real headless Chromium + MCP in-process
+bun run build           # emit dist/ (JS + .d.ts)
+```
+
+CI (`.github/workflows/ci.yml`) runs typecheck + unit + build + integration on every push.
+
+## Output & data location
+
+Artifacts (reports, screenshots, site-memory, replay) are written **outside the repo by default**:
+
+- nested under the detected host-agent config dir when present —
+  `.claude/fuse-browser/`, `.cursor/`, `.codex/`, `.windsurf/`, `.gemini/`, `.continue/`, `.junie/`, `.github/`;
+- otherwise `~/.fuse-browser/`.
+
+Override per run with `outputDir` (library / MCP arg) or `--output-dir` (CLI). Cookies
+(`storageStatePath`) and the Chromium profile (`userDataDir`) are separate paths you set explicitly.
+
+> ⚠️ Reports and `storage-state` files contain page content, screenshots and **session cookies in
+> clear text** — never commit them. The bundled `.gitignore` already excludes the defaults.
+
+## Guardrails & limits
+
+- No payment/booking/ticketing/card action without explicit human approval.
+- Passwords masked in reports; proxy credentials redacted.
+- CAPTCHA / 2FA: detection by default; an **opt-in** solver is available for authorized testing only — see *Resilience & captcha*.
+- Concurrent sessions are capped (`maxSessions`, default 8) to avoid OOM.
+- CDP attach: the remote-debugging port is a local attack surface — use a dedicated profile.
+
+## Resilience & captcha
+
+- **Navigation retry** (on by default): transient failures and HTTP `429/502/503/504`
+  are retried with full-jitter exponential backoff, honoring `Retry-After`. Tune via
+  `retry: { maxAttempts, baseMs, capMs, throttleMs }` (defaults `3 / 300 / 10000 / 0`).
+  `throttleMs` enforces a minimum gap between hits on the same host.
+- **Captcha solver** (off by default, **opt-in**): set `solveCaptcha: true` on a probe and
+  provide `captcha: { provider, apiKey }` (`2captcha` | `anticaptcha` | `capmonster`). It
+  solves reCAPTCHA v2 / Cloudflare Turnstile via the provider's API; the result is reported
+  as `captcha: { attempted, solved, kind, provider, reason }`. Failures are reported, never thrown.
+
+## Disclaimer
+
+Provided **as-is** under MIT, with no warranty. `fuse-browser` is a neutral, dual-use
+automation tool. **You alone are responsible** for how you use it and for complying with
+applicable law, the target sites' Terms of Service, `robots.txt`, and data-protection rules
+(e.g. GDPR). The opt-in captcha solver is intended for **authorized testing only** — on
+systems you own or are explicitly permitted to test.
+
+## License
+
+MIT

package/dist/actions/act-by-ref.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Execute an action on an element referenced by its `data-fuse-ref`
+ * (produced by {@link captureSnapshot}). Deterministic counterpart to the
+ * text/heuristic targeting of smart-click/smart-fill.
+ * @module actions/act-by-ref
+ */
+import type { Page } from "playwright";
+import type { ActionResult } from "../interfaces/types.js";
+/** Action kinds that can target a snapshot ref. */
+export type RefActionKind = "click" | "fill" | "select";
+/** Run `kind` on the element carrying `data-fuse-ref="ref"`. */
+export declare function actByRef(page: Page, ref: number, kind: RefActionKind, value?: string): Promise<ActionResult>;
+//# sourceMappingURL=act-by-ref.d.ts.map

package/dist/actions/act-by-ref.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"act-by-ref.d.ts","sourceRoot":"","sources":["../../src/actions/act-by-ref.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAG3D,mDAAmD;AACnD,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,MAAM,GAAG,QAAQ,CAAC;AAExD,gEAAgE;AAChE,wBAAsB,QAAQ,CAC5B,IAAI,EAAE,IAAI,EACV,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,aAAa,EACnB,KAAK,SAAK,GACT,OAAO,CAAC,YAAY,CAAC,CAkBvB"}

package/dist/actions/act-by-ref.js

@@ -0,0 +1,25 @@
+import { REF_ATTRIBUTE } from "../extraction/snapshot.js";
+/** Run `kind` on the element carrying `data-fuse-ref="ref"`. */
+export async function actByRef(page, ref, kind, value = "") {
+    const selector = `[${REF_ATTRIBUTE}="${ref}"]`;
+    const locator = page.locator(selector).first();
+    try {
+        if ((await locator.count()) === 0) {
+            return { type: kind, ok: false, ref, error: "ref_not_found" };
+        }
+        if (kind === "click") {
+            await locator.click({ timeout: 5_000 });
+        }
+        else if (kind === "fill") {
+            await locator.fill(value, { timeout: 5_000 });
+        }
+        else {
+            await locator.selectOption(value, { timeout: 5_000 });
+        }
+        return { type: kind, ok: true, ref, strategy: "ref" };
+    }
+    catch (err) {
+        return { type: kind, ok: false, ref, error: String(err).split("\n")[0] ?? "error" };
+    }
+}
+//# sourceMappingURL=act-by-ref.js.map

package/dist/actions/act-by-ref.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"act-by-ref.js","sourceRoot":"","sources":["../../src/actions/act-by-ref.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAK1D,gEAAgE;AAChE,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,IAAU,EACV,GAAW,EACX,IAAmB,EACnB,KAAK,GAAG,EAAE;IAEV,MAAM,QAAQ,GAAG,IAAI,aAAa,KAAK,GAAG,IAAI,CAAC;IAC/C,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,KAAK,EAAE,CAAC;IAC/C,IAAI,CAAC;QACH,IAAI,CAAC,MAAM,OAAO,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC;YAClC,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,eAAe,EAAE,CAAC;QAChE,CAAC;QACD,IAAI,IAAI,KAAK,OAAO,EAAE,CAAC;YACrB,MAAM,OAAO,CAAC,KAAK,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC;QAC1C,CAAC;aAAM,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;YAC3B,MAAM,OAAO,CAAC,IAAI,CAAC,KAAK,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC;QAChD,CAAC;aAAM,CAAC;YACN,MAAM,OAAO,CAAC,YAAY,CAAC,KAAK,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC;QACxD,CAAC;QACD,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;IACxD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,OAAO,EAAE,CAAC;IACtF,CAAC;AACH,CAAC"}

package/dist/actions/human.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Human-like behaviors: random pauses.
+ * @module actions/human
+ */
+import type { Page } from "playwright";
+/** Short random pause to mimic a real user. */
+export declare function humanPause(page: Page): Promise<void>;
+//# sourceMappingURL=human.d.ts.map

package/dist/actions/human.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"human.d.ts","sourceRoot":"","sources":["../../src/actions/human.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAGvC,+CAA+C;AAC/C,wBAAsB,UAAU,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAE1D"}

package/dist/actions/human.js

@@ -0,0 +1,6 @@
+import { randInt } from "../lib/text.js";
+/** Short random pause to mimic a real user. */
+export async function humanPause(page) {
+    await page.waitForTimeout(randInt(120, 420));
+}
+//# sourceMappingURL=human.js.map

package/dist/actions/human.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"human.js","sourceRoot":"","sources":["../../src/actions/human.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAEzC,+CAA+C;AAC/C,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,IAAU;IACzC,MAAM,IAAI,CAAC,cAAc,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC;AAC/C,CAAC"}

package/dist/actions/login.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Structured login action (username + password + submit), password masked.
+ * @module actions/login
+ */
+import type { Page } from "playwright";
+import type { ActionResult } from "../interfaces/types.js";
+/** Fields accepted by the login action (loose, like the Python dict). */
+export interface LoginAction {
+    usernameTarget?: string;
+    passwordTarget?: string;
+    submitTarget?: string;
+    username?: string;
+    password?: string;
+}
+/** Fill credentials then submit; masks the password in the report. */
+export declare function login(page: Page, action: LoginAction, humanMode?: boolean): Promise<ActionResult>;
+//# sourceMappingURL=login.d.ts.map

package/dist/actions/login.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"login.d.ts","sourceRoot":"","sources":["../../src/actions/login.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAI3D,yEAAyE;AACzE,MAAM,WAAW,WAAW;IAC1B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,sEAAsE;AACtE,wBAAsB,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,SAAS,UAAQ,GAAG,OAAO,CAAC,YAAY,CAAC,CAYrG"}

package/dist/actions/login.js

@@ -0,0 +1,11 @@
+import { smartClick } from "./smart-click.js";
+import { smartFill } from "./smart-fill.js";
+/** Fill credentials then submit; masks the password in the report. */
+export async function login(page, action, humanMode = false) {
+    const username = await smartFill(page, action.usernameTarget ?? "email", action.username ?? "", "", humanMode);
+    const password = await smartFill(page, action.passwordTarget ?? "password", action.password ?? "", "", humanMode);
+    const submit = await smartClick(page, action.submitTarget ?? "Sign in", "", humanMode);
+    const ok = Boolean(username.ok && password.ok && submit.ok);
+    return { type: "login", ok, username, password: { ...password, value: "***" }, submit };
+}
+//# sourceMappingURL=login.js.map

package/dist/actions/login.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"login.js","sourceRoot":"","sources":["../../src/actions/login.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAW5C,sEAAsE;AACtE,MAAM,CAAC,KAAK,UAAU,KAAK,CAAC,IAAU,EAAE,MAAmB,EAAE,SAAS,GAAG,KAAK;IAC5E,MAAM,QAAQ,GAAG,MAAM,SAAS,CAAC,IAAI,EAAE,MAAM,CAAC,cAAc,IAAI,OAAO,EAAE,MAAM,CAAC,QAAQ,IAAI,EAAE,EAAE,EAAE,EAAE,SAAS,CAAC,CAAC;IAC/G,MAAM,QAAQ,GAAG,MAAM,SAAS,CAC9B,IAAI,EACJ,MAAM,CAAC,cAAc,IAAI,UAAU,EACnC,MAAM,CAAC,QAAQ,IAAI,EAAE,EACrB,EAAE,EACF,SAAS,CACV,CAAC;IACF,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,YAAY,IAAI,SAAS,EAAE,EAAE,EAAE,SAAS,CAAC,CAAC;IACvF,MAAM,EAAE,GAAG,OAAO,CAAC,QAAQ,CAAC,EAAE,IAAI,QAAQ,CAAC,EAAE,IAAI,MAAM,CAAC,EAAE,CAAC,CAAC;IAC5D,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,EAAE,GAAG,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,MAAM,EAAE,CAAC;AAC1F,CAAC"}

package/dist/actions/navigation.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Low-level page interactions: scroll, key press, select, history.
+ * @module actions/navigation
+ */
+import type { Page } from "playwright";
+import type { ActionResult } from "../interfaces/types.js";
+/** Scroll the page by a pixel delta (positive = down/right). */
+export declare function scroll(page: Page, deltaY: number, deltaX?: number): Promise<ActionResult>;
+/** Press a key or shortcut (e.g. "Enter", "ArrowDown", "Control+a"). */
+export declare function pressKey(page: Page, key: string): Promise<ActionResult>;
+/** Select option(s) in a <select> by value, label or index. */
+export declare function selectOption(page: Page, target: string, value: string): Promise<ActionResult>;
+/** Go back or forward in session history. */
+export declare function navigateHistory(page: Page, direction: "back" | "forward"): Promise<ActionResult>;
+//# sourceMappingURL=navigation.d.ts.map

package/dist/actions/navigation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"navigation.d.ts","sourceRoot":"","sources":["../../src/actions/navigation.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAE3D,gEAAgE;AAChE,wBAAsB,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,SAAI,GAAG,OAAO,CAAC,YAAY,CAAC,CAG1F;AAED,wEAAwE;AACxE,wBAAsB,QAAQ,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAO7E;AAED,+DAA+D;AAC/D,wBAAsB,YAAY,CAChC,IAAI,EAAE,IAAI,EACV,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,YAAY,CAAC,CAOvB;AAED,6CAA6C;AAC7C,wBAAsB,eAAe,CACnC,IAAI,EAAE,IAAI,EACV,SAAS,EAAE,MAAM,GAAG,SAAS,GAC5B,OAAO,CAAC,YAAY,CAAC,CAMvB"}

package/dist/actions/navigation.js

@@ -0,0 +1,33 @@
+/** Scroll the page by a pixel delta (positive = down/right). */
+export async function scroll(page, deltaY, deltaX = 0) {
+    await page.mouse.wheel(deltaX, deltaY);
+    return { type: "scroll", ok: true, deltaX, deltaY };
+}
+/** Press a key or shortcut (e.g. "Enter", "ArrowDown", "Control+a"). */
+export async function pressKey(page, key) {
+    try {
+        await page.keyboard.press(key);
+        return { type: "press", ok: true, key };
+    }
+    catch (err) {
+        return { type: "press", ok: false, key, error: String(err).split("\n")[0] ?? "error" };
+    }
+}
+/** Select option(s) in a <select> by value, label or index. */
+export async function selectOption(page, target, value) {
+    try {
+        const selected = await page.locator(target).first().selectOption(value, { timeout: 5_000 });
+        return { type: "select", ok: selected.length > 0, target, selected };
+    }
+    catch (err) {
+        return { type: "select", ok: false, target, error: String(err).split("\n")[0] ?? "error" };
+    }
+}
+/** Go back or forward in session history. */
+export async function navigateHistory(page, direction) {
+    const response = direction === "back"
+        ? await page.goBack({ waitUntil: "domcontentloaded", timeout: 20_000 })
+        : await page.goForward({ waitUntil: "domcontentloaded", timeout: 20_000 });
+    return { type: direction, ok: response !== null, url: page.url() };
+}
+//# sourceMappingURL=navigation.js.map

package/dist/actions/navigation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"navigation.js","sourceRoot":"","sources":["../../src/actions/navigation.ts"],"names":[],"mappings":"AAOA,gEAAgE;AAChE,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,IAAU,EAAE,MAAc,EAAE,MAAM,GAAG,CAAC;IACjE,MAAM,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;AACtD,CAAC;AAED,wEAAwE;AACxE,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,IAAU,EAAE,GAAW;IACpD,IAAI,CAAC;QACH,MAAM,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC/B,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC;IAC1C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,OAAO,EAAE,CAAC;IACzF,CAAC;AACH,CAAC;AAED,+DAA+D;AAC/D,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,IAAU,EACV,MAAc,EACd,KAAa;IAEb,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,CAAC,YAAY,CAAC,KAAK,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC;QAC5F,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;IACvE,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,OAAO,EAAE,CAAC;IAC7F,CAAC;AACH,CAAC;AAED,6CAA6C;AAC7C,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,IAAU,EACV,SAA6B;IAE7B,MAAM,QAAQ,GACZ,SAAS,KAAK,MAAM;QAClB,CAAC,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,kBAAkB,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;QACvE,CAAC,CAAC,MAAM,IAAI,CAAC,SAAS,CAAC,EAAE,SAAS,EAAE,kBAAkB,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;IAC/E,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,QAAQ,KAAK,IAAI,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC;AACrE,CAAC"}

package/dist/actions/perform.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Dispatch actions to their specialized implementations.
+ * @module actions/perform
+ */
+import type { Page } from "playwright";
+import type { ActionResult } from "../interfaces/types.js";
+/** Loose runtime action (may carry `preferredStrategy` injected by site memory). */
+export type ActionInput = Record<string, unknown> & {
+    type: string;
+};
+/** Execute an action based on its `type`. */
+export declare function performAction(page: Page, action: ActionInput, humanMode?: boolean): Promise<ActionResult>;
+/** Copy of an action for the report, password masked. */
+export declare function safeActionForReport(action: ActionInput): Record<string, unknown>;
+//# sourceMappingURL=perform.d.ts.map

package/dist/actions/perform.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"perform.d.ts","sourceRoot":"","sources":["../../src/actions/perform.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAM3D,oFAAoF;AACpF,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAErE,6CAA6C;AAC7C,wBAAsB,aAAa,CACjC,IAAI,EAAE,IAAI,EACV,MAAM,EAAE,WAAW,EACnB,SAAS,UAAQ,GAChB,OAAO,CAAC,YAAY,CAAC,CA2BvB;AAED,yDAAyD;AACzD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAIhF"}

package/dist/actions/perform.js

@@ -0,0 +1,41 @@
+import { login } from "./login.js";
+import { navigateHistory, pressKey, scroll, selectOption } from "./navigation.js";
+import { smartClick } from "./smart-click.js";
+import { smartFill } from "./smart-fill.js";
+/** Execute an action based on its `type`. */
+export async function performAction(page, action, humanMode = false) {
+    const target = String(action.target ?? "");
+    const preferred = String(action.preferredStrategy ?? "");
+    switch (action.type) {
+        case "click":
+            return smartClick(page, target, preferred, humanMode);
+        case "fill":
+            return smartFill(page, target, String(action.value ?? ""), preferred, humanMode);
+        case "login":
+            return login(page, action, humanMode);
+        case "scroll":
+            return scroll(page, Number(action.deltaY ?? 600), Number(action.deltaX ?? 0));
+        case "press":
+            return pressKey(page, String(action.key ?? ""));
+        case "select":
+            return selectOption(page, target, String(action.value ?? ""));
+        case "back":
+        case "forward":
+            return navigateHistory(page, action.type);
+        case "wait": {
+            const ms = Number(action.ms ?? 500);
+            await page.waitForTimeout(ms);
+            return { type: "wait", ok: true, ms };
+        }
+        default:
+            return { type: action.type, ok: false, error: "unknown_action" };
+    }
+}
+/** Copy of an action for the report, password masked. */
+export function safeActionForReport(action) {
+    const safe = { ...action };
+    if ("password" in safe)
+        safe.password = "***";
+    return safe;
+}
+//# sourceMappingURL=perform.js.map

package/dist/actions/perform.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"perform.js","sourceRoot":"","sources":["../../src/actions/perform.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,KAAK,EAAoB,MAAM,YAAY,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAClF,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAK5C,6CAA6C;AAC7C,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,IAAU,EACV,MAAmB,EACnB,SAAS,GAAG,KAAK;IAEjB,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC;IAC3C,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,CAAC,iBAAiB,IAAI,EAAE,CAAC,CAAC;IACzD,QAAQ,MAAM,CAAC,IAAI,EAAE,CAAC;QACpB,KAAK,OAAO;YACV,OAAO,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC;QACxD,KAAK,MAAM;YACT,OAAO,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,KAAK,IAAI,EAAE,CAAC,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC;QACnF,KAAK,OAAO;YACV,OAAO,KAAK,CAAC,IAAI,EAAE,MAAqB,EAAE,SAAS,CAAC,CAAC;QACvD,KAAK,QAAQ;YACX,OAAO,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,IAAI,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,IAAI,CAAC,CAAC,CAAC,CAAC;QAChF,KAAK,OAAO;YACV,OAAO,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,GAAG,IAAI,EAAE,CAAC,CAAC,CAAC;QAClD,KAAK,QAAQ;YACX,OAAO,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,CAAC;QAChE,KAAK,MAAM,CAAC;QACZ,KAAK,SAAS;YACZ,OAAO,eAAe,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;QAC5C,KAAK,MAAM,CAAC,CAAC,CAAC;YACZ,MAAM,EAAE,GAAG,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,GAAG,CAAC,CAAC;YACpC,MAAM,IAAI,CAAC,cAAc,CAAC,EAAE,CAAC,CAAC;YAC9B,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;QACxC,CAAC;QACD;YACE,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,gBAAgB,EAAE,CAAC;IACrE,CAAC;AACH,CAAC;AAED,yDAAyD;AACzD,MAAM,UAAU,mBAAmB,CAAC,MAAmB;IACrD,MAAM,IAAI,GAAG,EAAE,GAAG,MAAM,EAAE,CAAC;IAC3B,IAAI,UAAU,IAAI,IAAI;QAAE,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC;IAC9C,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/actions/smart-click.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Smart multi-strategy click with heuristic fallback.
+ * @module actions/smart-click
+ */
+import type { Page } from "playwright";
+import type { ActionResult } from "../interfaces/types.js";
+/** Try several locating strategies, ordered by the preferred strategy. */
+export declare function smartClick(page: Page, target: string, preferredStrategy?: string, humanMode?: boolean): Promise<ActionResult>;
+//# sourceMappingURL=smart-click.d.ts.map

package/dist/actions/smart-click.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"smart-click.d.ts","sourceRoot":"","sources":["../../src/actions/smart-click.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAW,IAAI,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAgB3D,0EAA0E;AAC1E,wBAAsB,UAAU,CAC9B,IAAI,EAAE,IAAI,EACV,MAAM,EAAE,MAAM,EACd,iBAAiB,SAAK,EACtB,SAAS,UAAQ,GAChB,OAAO,CAAC,YAAY,CAAC,CAoCvB"}

package/dist/actions/smart-click.js

@@ -0,0 +1,55 @@
+import { evalScriptArg } from "../lib/evaluate.js";
+import { escapeRegExp } from "../lib/text.js";
+import { humanPause } from "./human.js";
+const HEURISTIC_CLICK = `(target) => {
+  const needle = target.toLowerCase();
+  const els = [...document.querySelectorAll('button,a,[role=button],input[type=button],input[type=submit]')];
+  const el = els.find(e => (
+    (e.innerText || '') + ' ' + (e.value || '') + ' ' + (e.getAttribute('aria-label') || '')
+  ).toLowerCase().includes(needle));
+  if (!el) return false;
+  el.click();
+  return true;
+}`;
+/** Try several locating strategies, ordered by the preferred strategy. */
+export async function smartClick(page, target, preferredStrategy = "", humanMode = false) {
+    const rx = new RegExp(escapeRegExp(target), "i");
+    const strategies = [
+        ["selector", () => page.locator(target).first()],
+        ["role", () => page.getByRole("button", { name: rx }).first()],
+        ["text", () => page.getByText(rx).first()],
+        ["label", () => page.getByLabel(rx).first()],
+    ];
+    if (preferredStrategy) {
+        strategies.sort((a, b) => (a[0] === preferredStrategy ? 0 : 1) - (b[0] === preferredStrategy ? 0 : 1));
+    }
+    let lastError = "not_tried";
+    for (const [strategy, factory] of strategies) {
+        try {
+            const locator = factory();
+            if ((await locator.count()) > 0) {
+                if (humanMode) {
+                    await humanPause(page);
+                    await locator.scrollIntoViewIfNeeded({ timeout: 2_000 });
+                    await locator.hover({ timeout: 2_000 });
+                    await humanPause(page);
+                }
+                await locator.click({ timeout: 2_000 });
+                return { type: "click", target, ok: true, strategy };
+            }
+        }
+        catch (err) {
+            lastError = String(err).split("\n")[0] ?? "error";
+        }
+    }
+    try {
+        const clicked = await evalScriptArg(page, HEURISTIC_CLICK, target);
+        if (clicked)
+            return { type: "click", target, ok: true, strategy: "heuristic" };
+    }
+    catch (err) {
+        lastError = String(err).split("\n")[0] ?? "error";
+    }
+    return { type: "click", target, ok: false, error: lastError };
+}
+//# sourceMappingURL=smart-click.js.map

package/dist/actions/smart-click.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"smart-click.js","sourceRoot":"","sources":["../../src/actions/smart-click.ts"],"names":[],"mappings":"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"}

package/dist/actions/smart-fill.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Smart multi-strategy fill with human-like typing.
+ * @module actions/smart-fill
+ */
+import type { Page } from "playwright";
+import type { ActionResult } from "../interfaces/types.js";
+/** Fill a field via selector, label or placeholder, with a preferred strategy. */
+export declare function smartFill(page: Page, target: string, value: string, preferredStrategy?: string, humanMode?: boolean): Promise<ActionResult>;
+//# sourceMappingURL=smart-fill.d.ts.map

package/dist/actions/smart-fill.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"smart-fill.d.ts","sourceRoot":"","sources":["../../src/actions/smart-fill.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAW,IAAI,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAkB3D,kFAAkF;AAClF,wBAAsB,SAAS,CAC7B,IAAI,EAAE,IAAI,EACV,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,iBAAiB,SAAK,EACtB,SAAS,UAAQ,GAChB,OAAO,CAAC,YAAY,CAAC,CAwBvB"}

package/dist/actions/smart-fill.js

@@ -0,0 +1,46 @@
+import { escapeRegExp, randInt } from "../lib/text.js";
+import { humanPause } from "./human.js";
+async function humanType(page, locator, value) {
+    await humanPause(page);
+    try {
+        await locator.scrollIntoViewIfNeeded({ timeout: 2_000 });
+        await locator.hover({ timeout: 2_000 });
+        await locator.click({ timeout: 2_000 });
+        await page.keyboard.type(value, { delay: randInt(35, 95) });
+    }
+    catch {
+        // Some composite widgets expose a textbox but intercept pointer events:
+        // keep the human attempt, then fall back to a direct fill.
+        await locator.fill(value, { timeout: 2_000 });
+    }
+}
+/** Fill a field via selector, label or placeholder, with a preferred strategy. */
+export async function smartFill(page, target, value, preferredStrategy = "", humanMode = false) {
+    const rx = new RegExp(escapeRegExp(target), "i");
+    const strategies = [
+        ["selector", () => page.locator(target).first()],
+        ["label", () => page.getByLabel(rx).first()],
+        ["placeholder", () => page.getByPlaceholder(rx).first()],
+    ];
+    if (preferredStrategy) {
+        strategies.sort((a, b) => (a[0] === preferredStrategy ? 0 : 1) - (b[0] === preferredStrategy ? 0 : 1));
+    }
+    let lastError = "not_tried";
+    for (const [strategy, factory] of strategies) {
+        try {
+            const locator = factory();
+            if ((await locator.count()) > 0) {
+                if (humanMode)
+                    await humanType(page, locator, value);
+                else
+                    await locator.fill(value, { timeout: 2_000 });
+                return { type: "fill", target, ok: true, strategy };
+            }
+        }
+        catch (err) {
+            lastError = String(err).split("\n")[0] ?? "error";
+        }
+    }
+    return { type: "fill", target, ok: false, error: lastError };
+}
+//# sourceMappingURL=smart-fill.js.map

package/dist/actions/smart-fill.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"smart-fill.js","sourceRoot":"","sources":["../../src/actions/smart-fill.ts"],"names":[],"mappings":"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"}

package/dist/actions/wait-for.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Semantic waits: wait for a condition (text/selector/url/gone) instead of a
+ * fixed delay. Essential for reliable agentic loops on slow pages and SPAs.
+ * @module actions/wait-for
+ */
+import type { Page } from "playwright";
+import type { ActionResult } from "../interfaces/types.js";
+/**
+ * A semantic wait condition. Set one field; if several are set they are
+ * evaluated in priority order: text > selector > gone > urlContains.
+ */
+export interface WaitCondition {
+    text?: string;
+    selector?: string;
+    urlContains?: string;
+    gone?: string;
+    timeoutMs?: number;
+}
+/** Wait until the condition holds; returns ok=false on timeout. */
+export declare function waitForCondition(page: Page, cond: WaitCondition): Promise<ActionResult>;
+//# sourceMappingURL=wait-for.d.ts.map

package/dist/actions/wait-for.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wait-for.d.ts","sourceRoot":"","sources":["../../src/actions/wait-for.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAE3D;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,mEAAmE;AACnE,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CAwB7F"}