claw-browser-automation 0.2.0

package/README.md

@@ -0,0 +1,288 @@
+# claw-browser-automation
+
+Reliable browser automation layer for [OpenClaw](https://github.com/openclaw/openclaw). Replaces the flaky extension relay with managed Playwright sessions that the AI agent drives directly.
+
+The agent (clawbot) is the workflow engine — it decides *what* to do. This layer provides reliable *how*: atomic browser actions with postcondition verification, automatic retries, session persistence, and full observability.
+
+```
+┌─────────────────────────────────────────────────┐
+│  OpenClaw Agent (clawbot)                       │
+│  - Receives user intent via any channel         │
+│  - Decides what browser actions to take         │
+│  - Calls browser tools exposed by this skill    │
+└──────────────┬──────────────────────────────────┘
+               │ tool calls
+┌──────────────▼──────────────────────────────────┐
+│  claw-browser-automation (this project)         │
+│                                                 │
+│  Tool Layer → Action Engine → Browser Pool      │
+│                    │                            │
+│         State & Artifacts (SQLite)              │
+└──────────────┬──────────────────────────────────┘
+               │
+    ┌──────────▼──────────┐
+    │  Chromium (managed)  │
+    └─────────────────────┘
+```
+
+## Prerequisites
+
+- **Node.js** >= 22.12.0
+- **Bun** (package manager)
+- **OpenClaw** >= 2026.2.9 installed globally
+- **Playwright browsers** installed (`npx playwright install chromium`)
+
+## Quick start
+
+### 1. Install as an OpenClaw plugin
+
+```bash
+openclaw plugins install claw-browser-automation
+```
+
+### 2. Install Playwright browsers (first time only)
+
+```bash
+npx playwright install chromium
+```
+
+### 3. Configure (optional)
+
+All configuration has sensible defaults. To customize, edit `~/.openclaw/openclaw.json`:
+
+```jsonc
+{
+  "skills": {
+    "entries": {
+      "browser-automation": {
+        "enabled": true,
+        "config": {
+          "maxContexts": 4,
+          "headless": true
+        }
+      }
+    }
+  }
+}
+```
+
+### 4. Start OpenClaw
+
+```bash
+openclaw start
+```
+
+The browser automation plugin loads automatically. The agent now has access to 19 browser tools and can perform any browser task you ask for via Telegram, the CLI, or any other configured channel.
+
+### Alternative: install from source
+
+If you prefer to work from a local checkout instead of the published package:
+
+```bash
+git clone https://github.com/ametel01/claw-browser-automation
+cd claw-browser-automation
+bun install
+bun run build
+```
+
+Then point OpenClaw at the source tree in `~/.openclaw/openclaw.json`:
+
+```jsonc
+{
+  "skills": {
+    "load": {
+      "extraDirs": ["/path/to/claw-browser-automation"]
+    }
+  }
+}
+```
+
+### Programmatic usage
+
+You can also use the library directly without OpenClaw:
+
+```typescript
+import { createSkill } from "claw-browser-automation";
+
+const skill = await createSkill({
+  maxContexts: 4,
+  headless: true,
+});
+
+// skill.tools — array of 19 ToolDefinition objects
+// skill.context — internal state (pool, store, trace, etc.)
+// skill.shutdown() — graceful shutdown
+```
+
+## How it works with OpenClaw
+
+When you send a message like "go to example.com and extract the main heading", the flow is:
+
+1. **You** send a message via Telegram / CLI / API
+2. **OpenClaw agent** receives the intent and plans a tool sequence
+3. **Agent calls** `browser_open` → `browser_navigate` → `browser_extract_text` → `browser_close`
+4. **This skill** executes each tool against a managed Playwright browser
+5. **Agent returns** the extracted data to you
+
+The agent composes tools into arbitrary workflows. This layer doesn't hardcode any specific task — it provides primitives the agent chains together.
+
+## Available tools
+
+The skill exposes 19 tools to the agent, grouped by function:
+
+### Session management
+
+| Tool | Description |
+|------|-------------|
+| `browser_open` | Open a new browser session, optionally with a URL or named profile |
+| `browser_close` | Close session and save a snapshot for later restore |
+| `browser_list` | List all active sessions with URLs and health status |
+| `browser_restore` | Restore a previously suspended session from its snapshot |
+| `browser_state` | Get current page state (URL, title, loading status) |
+
+### Page actions
+
+| Tool | Description |
+|------|-------------|
+| `browser_navigate` | Navigate to a URL and wait for load |
+| `browser_click` | Click an element by CSS selector |
+| `browser_type` | Type text into an input field |
+| `browser_select` | Select a dropdown option |
+| `browser_fill_form` | Fill multiple form fields at once |
+| `browser_wait` | Wait for an element state or a JS condition |
+
+### Data extraction
+
+| Tool | Description |
+|------|-------------|
+| `browser_extract_text` | Extract text content from a single element |
+| `browser_extract_all` | Extract data from all matching elements (lists, tables) |
+| `browser_get_content` | Get cleaned page text (scripts/styles removed) |
+
+### Page utilities
+
+| Tool | Description |
+|------|-------------|
+| `browser_screenshot` | Capture a screenshot and save as artifact |
+| `browser_evaluate` | Execute arbitrary JavaScript in the page |
+| `browser_scroll` | Scroll the page in a direction |
+| `browser_session_trace` | Get the full action trace for a session |
+
+### Safety
+
+| Tool | Description |
+|------|-------------|
+| `browser_request_approval` | Pause and ask the human for confirmation before proceeding |
+
+## Configuration
+
+All configuration is optional. Defaults work out of the box.
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `maxContexts` | `4` | Maximum concurrent browser sessions |
+| `headless` | `true` | Run browsers without a visible window |
+| `dbPath` | `~/.openclaw/browser-automation/store.db` | SQLite database for session persistence |
+| `artifactsDir` | `~/.openclaw/workspace/browser-automation/artifacts` | Screenshot and DOM snapshot storage |
+| `logLevel` | `info` | Log level (`debug`, `info`, `warn`, `error`) |
+
+Pass these via the `config` key in your `openclaw.json` skill entry, or programmatically via `createSkill()` (see [Quick start](#quick-start)).
+
+## Reliability features
+
+These are the mechanisms that make this layer production-grade compared to an extension relay:
+
+- **3-tier timeouts** — short (5s), medium (15s), long (45s) per action type
+- **Exponential backoff retries** with jitter on every action
+- **DOM stability checks** before reads and clicks (MutationObserver-based)
+- **Automatic popup/cookie banner dismissal** — recognizes 13 common patterns
+- **Health probes with circuit breaker** — detects browser crashes, auto-restarts
+- **Session snapshots** — URL, cookies, localStorage checkpointed to SQLite
+- **Pre/postcondition verification** per action
+- **Layered selector resolution** — CSS, ARIA, text, label, test ID, XPath with fallback chains
+
+## Data persistence
+
+All session state survives process restarts:
+
+```
+~/.openclaw/browser-automation/
+├── store.db              # SQLite: sessions, action log, schema
+└── ...
+
+~/.openclaw/workspace/browser-automation/
+├── artifacts/
+│   └── {sessionId}/      # Screenshots and DOM snapshots per session
+└── logs/
+    └── browser-automation-YYYY-MM-DD.log
+```
+
+The agent can suspend a session, shut down, restart hours later, and resume exactly where it left off — same URL, same cookies, same localStorage.
+
+## Development
+
+### Scripts
+
+```bash
+bun run build        # Compile TypeScript to dist/
+bun run test         # Run all tests (183 tests across 12 files)
+bun run test:watch   # Watch mode
+bun run check        # Biome lint + format check
+bun run check:fix    # Auto-fix lint/format issues
+bun run typecheck    # TypeScript strict mode check
+```
+
+### Running integration tests
+
+The integration tests prove end-to-end reliability across 9 scenarios: pool lifecycle, DOM extraction, crash recovery, popup dismissal, form filling, concurrent sessions, action retry, full tool chain, and session suspend/restore.
+
+```bash
+# Single run
+bun run test -- tests/integration/integration.test.ts
+
+# Reliability check (10 consecutive passes required)
+for i in {1..10}; do bun run test -- tests/integration/integration.test.ts || exit 1; done
+```
+
+### Project structure
+
+```
+src/
+├── index.ts                # Library entry point — createSkill()
+├── plugin.ts               # OpenClaw plugin adapter — register(api)
+├── pool/
+│   ├── browser-pool.ts     # Session lifecycle, max-context enforcement
+│   └── health.ts           # Health probes, circuit breaker recovery
+├── session/
+│   ├── session.ts          # BrowserSession with snapshot/restore
+│   ├── snapshot.ts         # SessionSnapshot type (URL, cookies, localStorage)
+│   └── profiles.ts         # Named profile persistence
+├── actions/
+│   ├── action.ts           # executeAction framework (retries, timeouts, tracing)
+│   ├── interact.ts         # click, type, fill, select, check, hover, drag
+│   ├── extract.ts          # getText, getAll, getPageContent
+│   ├── navigate.ts         # navigate, reload, goBack, goForward
+│   ├── wait.ts             # waitForSelector, waitForCondition, waitForNetworkIdle
+│   ├── page.ts             # screenshot, evaluate, scroll, getPageState
+│   └── resilience.ts       # PopupDismisser, waitForDomStability
+├── selectors/
+│   └── strategy.ts         # Layered selector resolution (CSS/ARIA/text/label/xpath)
+├── store/
+│   ├── db.ts               # SQLite with auto-migrations
+│   ├── sessions.ts         # SessionStore (CRUD + suspend/restore)
+│   ├── action-log.ts       # Every action logged with timing and result
+│   └── artifacts.ts        # Screenshot/snapshot storage with retention
+├── observe/
+│   ├── logger.ts           # Pino structured logging (stdout + file)
+│   └── trace.ts            # Per-session action traces with p50/p95 stats
+└── tools/
+    ├── context.ts          # SkillContext type, helper functions
+    ├── session-tools.ts    # browser_open, close, list, restore, state
+    ├── action-tools.ts     # browser_navigate, click, type, fill, extract, wait
+    ├── page-tools.ts       # browser_screenshot, evaluate, scroll, trace
+    └── approval-tools.ts   # browser_request_approval
+```
+
+## License
+
+MIT

package/dist/actions/action.d.ts

@@ -0,0 +1,50 @@
+import type { Page } from "playwright-core";
+import type { Logger } from "../observe/logger.js";
+import type { ActionTrace, SelectorResolutionTrace } from "../observe/trace.js";
+export interface StructuredError {
+    code: string;
+    message: string;
+    recoveryHint: string;
+}
+export interface ActionResult<T = unknown> {
+    ok: boolean;
+    data?: T;
+    error?: string;
+    structuredError?: StructuredError;
+    retries: number;
+    durationMs: number;
+    screenshot?: string;
+}
+export declare function toStructuredError(err: unknown): string | StructuredError;
+export type TimeoutTier = "short" | "medium" | "long";
+export declare function resolveTimeout(timeout: TimeoutTier | number | undefined): number;
+export interface TraceMetadata {
+    selectorResolved?: SelectorResolutionTrace;
+    eventsDispatched?: string[];
+    waitsPerformed?: string[];
+    assertionsChecked?: string[];
+}
+export interface ActionContext {
+    page: Page;
+    logger: Logger;
+    screenshotDir?: string;
+    sessionId?: string;
+    trace?: ActionTrace;
+    _traceMeta?: TraceMetadata;
+    _retryState?: RetryState;
+}
+export interface RetryState {
+    lastClickSelector?: string;
+    lastClickTime?: number;
+}
+export interface ActionOptions {
+    timeout?: TimeoutTier | number;
+    retries?: number;
+    screenshotOnFailure?: boolean;
+    precondition?: (ctx: ActionContext) => Promise<boolean>;
+    postcondition?: (ctx: ActionContext) => Promise<boolean>;
+    /** Internal: mutable array of selector strategies for rotation on retry. */
+    _selectorStrategies?: unknown[];
+}
+export declare function executeAction<T>(ctx: ActionContext, name: string, opts: ActionOptions, fn: (ctx: ActionContext, timeoutMs: number) => Promise<T>): Promise<ActionResult<T>>;
+//# sourceMappingURL=action.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"action.d.ts","sourceRoot":"","sources":["../../src/actions/action.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAM5C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,KAAK,EAAE,WAAW,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAGhF,MAAM,WAAW,eAAe;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,YAAY,CAAC,CAAC,GAAG,OAAO;IACxC,EAAE,EAAE,OAAO,CAAC;IACZ,IAAI,CAAC,EAAE,CAAC,CAAC;IACT,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,eAAe,CAQxE;AAED,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAC;AAQtD,wBAAgB,cAAc,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,CAQhF;AAED,MAAM,WAAW,aAAa;IAC7B,gBAAgB,CAAC,EAAE,uBAAuB,CAAC;IAC3C,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;CAC7B;AAED,MAAM,WAAW,aAAa;IAC7B,IAAI,EAAE,IAAI,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,UAAU,CAAC,EAAE,aAAa,CAAC;IAC3B,WAAW,CAAC,EAAE,UAAU,CAAC;CACzB;AAED,MAAM,WAAW,UAAU;IAC1B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,aAAa,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,aAAa;IAC7B,OAAO,CAAC,EAAE,WAAW,GAAG,MAAM,CAAC;IAC/B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,aAAa,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACxD,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,aAAa,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACzD,4EAA4E;IAC5E,mBAAmB,CAAC,EAAE,OAAO,EAAE,CAAC;CAChC;AAgHD,wBAAsB,aAAa,CAAC,CAAC,EACpC,GAAG,EAAE,aAAa,EAClB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,aAAa,EACnB,EAAE,EAAE,CAAC,GAAG,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,GACvD,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CA8C1B"}

package/dist/actions/action.js

@@ -0,0 +1,189 @@
+import { BrowserAutomationError, NavigationInterruptedError, TargetNotFoundError, } from "../errors.js";
+import { PopupDismisser } from "./resilience.js";
+export function toStructuredError(err) {
+    if (err instanceof BrowserAutomationError) {
+        return { code: err.code, message: err.message, recoveryHint: err.recoveryHint };
+    }
+    if (err instanceof Error) {
+        return err.message;
+    }
+    return String(err);
+}
+const TIMEOUT_VALUES = {
+    short: 5_000,
+    medium: 15_000,
+    long: 45_000,
+};
+export function resolveTimeout(timeout) {
+    if (timeout === undefined) {
+        return TIMEOUT_VALUES.medium;
+    }
+    if (typeof timeout === "number") {
+        return timeout;
+    }
+    return TIMEOUT_VALUES[timeout];
+}
+const DEFAULT_RETRIES = 3;
+async function runAttempt(ctx, opts, fn, timeoutMs) {
+    if (opts.precondition && !(await opts.precondition(ctx))) {
+        return { tag: "retry", error: "precondition failed" };
+    }
+    const data = await fn(ctx, timeoutMs);
+    if (opts.postcondition && !(await opts.postcondition(ctx))) {
+        return { tag: "retry", error: "postcondition failed" };
+    }
+    return { tag: "success", data };
+}
+async function retryLoop(ctx, name, opts, fn, timeoutMs, maxRetries, startUrl, popupDismisser) {
+    let lastError = "";
+    let lastCaughtError;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        lastCaughtError = undefined;
+        const navCheck = checkNavigationGuard(attempt, ctx, startUrl);
+        if (navCheck) {
+            return { tag: "exhausted", lastError: navCheck.message, lastCaughtError: navCheck };
+        }
+        try {
+            await popupDismisser.dismissOnce();
+            const outcome = await runAttempt(ctx, opts, fn, timeoutMs);
+            if (outcome.tag === "success") {
+                return { tag: "success", data: outcome.data, attempt };
+            }
+            lastError = outcome.error;
+            ctx.logger.warn({ action: name, attempt }, lastError);
+        }
+        catch (err) {
+            lastCaughtError = err;
+            lastError = err instanceof Error ? err.message : String(err);
+            ctx.logger.warn({ action: name, attempt, error: lastError }, "action attempt failed");
+            handleRetryError(err, opts, ctx, name);
+        }
+        if (attempt < maxRetries) {
+            await backoff(attempt);
+        }
+    }
+    return { tag: "exhausted", lastError, lastCaughtError };
+}
+function checkNavigationGuard(attempt, ctx, startUrl) {
+    if (attempt === 0) {
+        return undefined;
+    }
+    const currentUrl = ctx.page.url();
+    if (currentUrl !== startUrl) {
+        return new NavigationInterruptedError(`page navigated from ${startUrl} to ${currentUrl} during retry`);
+    }
+    return undefined;
+}
+function handleRetryError(err, opts, ctx, name) {
+    if (err instanceof TargetNotFoundError && opts._selectorStrategies) {
+        rotateStrategies(opts._selectorStrategies);
+        ctx.logger.debug({ action: name }, "rotated selector strategies for retry");
+    }
+}
+function rotateStrategies(strategies) {
+    if (strategies.length <= 1) {
+        return;
+    }
+    const first = strategies.shift();
+    if (first !== undefined) {
+        strategies.push(first);
+    }
+}
+export async function executeAction(ctx, name, opts, fn) {
+    const maxRetries = opts.retries ?? DEFAULT_RETRIES;
+    const timeoutMs = resolveTimeout(opts.timeout);
+    const startedAt = performance.now();
+    const popupDismisser = new PopupDismisser(ctx.page, ctx.logger);
+    popupDismisser.start();
+    ctx._traceMeta = {};
+    ctx._retryState = {};
+    const startUrl = ctx.page.url();
+    try {
+        const loopResult = await retryLoop(ctx, name, opts, fn, timeoutMs, maxRetries, startUrl, popupDismisser);
+        if (loopResult.tag === "success") {
+            const durationMs = Math.round(performance.now() - startedAt);
+            recordTraceEntry(ctx, name, {
+                timestamp: Date.now(),
+                durationMs,
+                ok: true,
+                retries: loopResult.attempt,
+            });
+            return { ok: true, data: loopResult.data, retries: loopResult.attempt, durationMs };
+        }
+        return buildFailureResult(ctx, name, loopResult.lastError, loopResult.lastCaughtError, maxRetries, startedAt, opts);
+    }
+    finally {
+        popupDismisser.stop();
+    }
+}
+async function buildFailureResult(ctx, name, lastError, lastCaughtError, maxRetries, startedAt, opts) {
+    const structured = toStructuredError(lastCaughtError ?? lastError);
+    const result = {
+        ok: false,
+        error: lastError,
+        retries: maxRetries,
+        durationMs: Math.round(performance.now() - startedAt),
+    };
+    if (typeof structured === "object") {
+        result.structuredError = structured;
+    }
+    if (opts.screenshotOnFailure !== false) {
+        try {
+            const screenshotPath = await captureFailureScreenshot(ctx, name);
+            if (screenshotPath) {
+                result.screenshot = screenshotPath;
+            }
+        }
+        catch {
+            ctx.logger.debug("failed to capture failure screenshot");
+        }
+    }
+    ctx.logger.error({ action: name, error: lastError, retries: maxRetries }, "action failed");
+    recordTraceEntry(ctx, name, {
+        timestamp: Date.now(),
+        durationMs: result.durationMs,
+        ok: false,
+        ...(result.error ? { error: result.error } : {}),
+        retries: result.retries,
+    });
+    return result;
+}
+function recordTraceEntry(ctx, action, entry) {
+    if (!(ctx.trace && ctx.sessionId)) {
+        return;
+    }
+    const meta = ctx._traceMeta;
+    ctx.trace.record(ctx.sessionId, {
+        action,
+        timestamp: entry.timestamp,
+        durationMs: entry.durationMs,
+        ok: entry.ok,
+        ...(entry.error ? { error: entry.error } : {}),
+        retries: entry.retries,
+        ...(meta?.selectorResolved ? { selectorResolved: meta.selectorResolved } : {}),
+        ...(meta?.eventsDispatched?.length ? { eventsDispatched: meta.eventsDispatched } : {}),
+        ...(meta?.waitsPerformed?.length ? { waitsPerformed: meta.waitsPerformed } : {}),
+        ...(meta?.assertionsChecked?.length ? { assertionsChecked: meta.assertionsChecked } : {}),
+    });
+}
+async function backoff(attempt) {
+    const base = Math.min(100 * 2 ** attempt, 2000);
+    const jitter = Math.floor(Math.random() * 500);
+    await new Promise((resolve) => {
+        setTimeout(resolve, base + jitter);
+    });
+}
+async function captureFailureScreenshot(ctx, actionName) {
+    if (!ctx.screenshotDir) {
+        return undefined;
+    }
+    const { mkdirSync, writeFileSync } = await import("node:fs");
+    const { join } = await import("node:path");
+    mkdirSync(ctx.screenshotDir, { recursive: true });
+    const filename = `${Date.now()}-${actionName}-failure.png`;
+    const filepath = join(ctx.screenshotDir, filename);
+    const buffer = await ctx.page.screenshot();
+    writeFileSync(filepath, buffer);
+    return filepath;
+}
+//# sourceMappingURL=action.js.map

package/dist/actions/action.js.map

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

package/dist/actions/assertions.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Declarative postcondition assertion factories.
+ *
+ * Each function returns a `(ctx: ActionContext) => Promise<boolean>` compatible
+ * with ActionOptions.postcondition. Compose with `allOf()` for multiple checks.
+ */
+import type { Selector } from "../selectors/strategy.js";
+import type { ActionContext } from "./action.js";
+export type AssertionCheck = (ctx: ActionContext) => Promise<boolean>;
+export declare function assertUrlContains(substring: string): AssertionCheck;
+export declare function assertElementVisible(selector: Selector): AssertionCheck;
+export declare function assertElementText(selector: Selector, expected: string | RegExp): AssertionCheck;
+export declare function assertElementGone(selector: Selector): AssertionCheck;
+export declare function allOf(...checks: AssertionCheck[]): AssertionCheck;
+//# sourceMappingURL=assertions.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"assertions.d.ts","sourceRoot":"","sources":["../../src/actions/assertions.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAEzD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,MAAM,MAAM,cAAc,GAAG,CAAC,GAAG,EAAE,aAAa,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAYtE,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc,CAKnE;AAED,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,QAAQ,GAAG,cAAc,CAUvE;AAED,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,cAAc,CAiB/F;AAED,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,QAAQ,GAAG,cAAc,CAYpE;AAED,wBAAgB,KAAK,CAAC,GAAG,MAAM,EAAE,cAAc,EAAE,GAAG,cAAc,CASjE"}

package/dist/actions/assertions.js

@@ -0,0 +1,75 @@
+/**
+ * Declarative postcondition assertion factories.
+ *
+ * Each function returns a `(ctx: ActionContext) => Promise<boolean>` compatible
+ * with ActionOptions.postcondition. Compose with `allOf()` for multiple checks.
+ */
+import { resolveSelector } from "../selectors/strategy.js";
+function recordAssertion(ctx, label) {
+    if (!ctx._traceMeta) {
+        ctx._traceMeta = {};
+    }
+    if (!ctx._traceMeta.assertionsChecked) {
+        ctx._traceMeta.assertionsChecked = [];
+    }
+    ctx._traceMeta.assertionsChecked.push(label);
+}
+export function assertUrlContains(substring) {
+    return async (ctx) => {
+        recordAssertion(ctx, `urlContains:${substring}`);
+        return ctx.page.url().includes(substring);
+    };
+}
+export function assertElementVisible(selector) {
+    return async (ctx) => {
+        recordAssertion(ctx, "elementVisible");
+        try {
+            const locator = resolveSelector(ctx.page, selector).first();
+            return await locator.isVisible({ timeout: 2000 });
+        }
+        catch {
+            return false;
+        }
+    };
+}
+export function assertElementText(selector, expected) {
+    return async (ctx) => {
+        recordAssertion(ctx, typeof expected === "string" ? `elementText:${expected}` : `elementText:${expected.source}`);
+        try {
+            const locator = resolveSelector(ctx.page, selector).first();
+            const text = await locator.innerText({ timeout: 2000 });
+            if (typeof expected === "string") {
+                return text.trim() === expected;
+            }
+            return expected.test(text.trim());
+        }
+        catch {
+            return false;
+        }
+    };
+}
+export function assertElementGone(selector) {
+    return async (ctx) => {
+        recordAssertion(ctx, "elementGone");
+        try {
+            const locator = resolveSelector(ctx.page, selector).first();
+            const visible = await locator.isVisible({ timeout: 2000 });
+            return !visible;
+        }
+        catch {
+            // Element not found at all → gone
+            return true;
+        }
+    };
+}
+export function allOf(...checks) {
+    return async (ctx) => {
+        for (const check of checks) {
+            if (!(await check(ctx))) {
+                return false;
+            }
+        }
+        return true;
+    };
+}
+//# sourceMappingURL=assertions.js.map

package/dist/actions/assertions.js.map

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

package/dist/actions/extract-structured.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Schema-based structured extraction with provenance tracking.
+ *
+ * Uses TypeBox schemas to define the expected shape. Each extracted item
+ * includes provenance metadata showing which DOM node produced it.
+ */
+import type { TObject, TProperties } from "@sinclair/typebox";
+import type { Selector } from "../selectors/strategy.js";
+import type { ActionContext, ActionOptions, ActionResult } from "./action.js";
+export interface ItemProvenance {
+    index: number;
+    tagName: string;
+    id: string;
+    className: string;
+    strategy: string;
+}
+export interface ExtractionResult<T> {
+    data: T[];
+    provenance: ItemProvenance[];
+}
+export interface ExtractStructuredOptions extends ActionOptions {
+    /** Maximum number of items to extract. Default: unlimited. */
+    limit?: number;
+}
+export declare function extractStructured<P extends TProperties>(ctx: ActionContext, selector: Selector, schema: TObject<P>, opts?: ExtractStructuredOptions): Promise<ActionResult<ExtractionResult<Record<string, unknown>>>>;
+//# sourceMappingURL=extract-structured.d.ts.map