btcp-browser-agent 0.1.7 → 0.1.8

package/package.json

@@ -1,69 +1,69 @@
-{
-  "name": "btcp-browser-agent",
-  "version": "0.1.7",
-  "description": "Give AI agents the power to control browsers. A foundation for building agentic systems with smart DOM snapshots and stable element references.",
-  "type": "module",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "default": "./dist/index.js"
-    },
-    "./core": {
-      "types": "./packages/core/dist/index.d.ts",
-      "import": "./packages/core/dist/index.js",
-      "default": "./packages/core/dist/index.js"
-    },
-    "./extension": {
-      "types": "./packages/extension/dist/index.d.ts",
-      "import": "./packages/extension/dist/index.js",
-      "default": "./packages/extension/dist/index.js"
-    },
-    "./extension/content": {
-      "types": "./packages/extension/dist/content.d.ts",
-      "import": "./packages/extension/dist/content.js",
-      "default": "./packages/extension/dist/content.js"
-    },
-    "./extension/background": {
-      "types": "./packages/extension/dist/background.d.ts",
-      "import": "./packages/extension/dist/background.js",
-      "default": "./packages/extension/dist/background.js"
-    }
-  },
-  "scripts": {
-    "build": "npm run build:packages && tsc -p tsconfig.build.json",
-    "build:packages": "tsc -p packages/core/tsconfig.json && tsc -p packages/extension/tsconfig.json && tsc -p packages/cli/tsconfig.json",
-    "clean": "rm -rf dist packages/*/dist",
-    "prepare": "npm run build",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "typecheck": "tsc --noEmit"
-  },
-  "workspaces": [
-    "packages/core",
-    "packages/extension",
-    "packages/cli"
-  ],
-  "files": [
-    "dist",
-    "packages/core/dist",
-    "packages/extension/dist",
-    "!**/__tests__",
-    "!**/*.map"
-  ],
-  "license": "Apache-2.0",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/browser-tool-calling-protocol/btcp-browser-agent.git"
-  },
-  "dependencies": {},
-  "devDependencies": {
-    "@types/chrome": "^0.0.268",
-    "@types/node": "^20.10.0",
-    "jsdom": "^24.0.0",
-    "typescript": "^5.3.0",
-    "vitest": "^2.0.0"
-  }
-}
+{
+  "name": "btcp-browser-agent",
+  "version": "0.1.8",
+  "description": "Give AI agents the power to control browsers. A foundation for building agentic systems with smart DOM snapshots and stable element references.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./core": {
+      "types": "./packages/core/dist/index.d.ts",
+      "import": "./packages/core/dist/index.js",
+      "default": "./packages/core/dist/index.js"
+    },
+    "./extension": {
+      "types": "./packages/extension/dist/index.d.ts",
+      "import": "./packages/extension/dist/index.js",
+      "default": "./packages/extension/dist/index.js"
+    },
+    "./extension/content": {
+      "types": "./packages/extension/dist/content.d.ts",
+      "import": "./packages/extension/dist/content.js",
+      "default": "./packages/extension/dist/content.js"
+    },
+    "./extension/background": {
+      "types": "./packages/extension/dist/background.d.ts",
+      "import": "./packages/extension/dist/background.js",
+      "default": "./packages/extension/dist/background.js"
+    }
+  },
+  "scripts": {
+    "build": "npm run build:packages && tsc -p tsconfig.build.json",
+    "build:packages": "tsc -p packages/core/tsconfig.json && tsc -p packages/extension/tsconfig.json && tsc -p packages/cli/tsconfig.json",
+    "clean": "rm -rf dist packages/*/dist",
+    "prepare": "npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "workspaces": [
+    "packages/core",
+    "packages/extension",
+    "packages/cli"
+  ],
+  "files": [
+    "dist",
+    "packages/core/dist",
+    "packages/extension/dist",
+    "!**/__tests__",
+    "!**/*.map"
+  ],
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/browser-tool-calling-protocol/btcp-browser-agent.git"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@types/chrome": "^0.0.268",
+    "@types/node": "^20.10.0",
+    "jsdom": "^24.0.0",
+    "typescript": "^5.3.0",
+    "vitest": "^2.0.0"
+  }
+}

package/packages/core/dist/actions.js

@@ -4,7 +4,8 @@
  * Element interaction handlers using native browser APIs.
  */
 import { createSnapshot } from './snapshot.js';
-import { DetailedError, createElementNotFoundError, createElementNotCompatibleError, createTimeoutError, createInvalidParametersError, } from './errors.js';
+import { DetailedError, createElementNotFoundError, createElementNotCompatibleError, createTimeoutError, createInvalidParametersError, createVerificationError, } from './errors.js';
+import { assertConnected, assertValueContains, assertValueEquals, assertChecked, assertSelected, waitForAssertion, } from './assertions.js';
 // Command ID counter for auto-generated IDs
 let commandIdCounter = 0;
 /**
@@ -336,12 +337,15 @@ export class DOMActions {
             element.dispatchEvent(new MouseEvent('mouseup', eventInit));
             element.dispatchEvent(new MouseEvent('click', eventInit));
         }
-        return { clicked: true };
+        // Check if element is still connected (graceful - doesn't throw)
+        // Element may be intentionally removed by click handlers (e.g., modal close, navigation)
+        const connectionResult = assertConnected(element);
+        return { success: true, error: null, connected: connectionResult.success };
     }
     async dblclick(selector) {
         const element = this.getElement(selector);
         element.dispatchEvent(new MouseEvent('dblclick', { bubbles: true, cancelable: true }));
-        return { clicked: true };
+        return { success: true, error: null };
     }
     async type(selector, text, options = {}) {
         const element = this.getElement(selector);
@@ -366,7 +370,12 @@ export class DOMActions {
             }
         }
         element.dispatchEvent(new Event('change', { bubbles: true }));
-        return { typed: true };
+        // Wait for verification that value contains typed text
+        const result = await waitForAssertion(() => assertValueContains(element, text), { timeout: 1000, interval: 50 });
+        if (!result.success) {
+            throw createVerificationError('type', result, selector);
+        }
+        return { success: true, error: null };
     }
     async fill(selector, value) {
         const element = this.getElement(selector);
@@ -379,7 +388,12 @@ export class DOMActions {
         element.value = value;
         element.dispatchEvent(new Event('input', { bubbles: true }));
         element.dispatchEvent(new Event('change', { bubbles: true }));
-        return { filled: true };
+        // Wait for verification that value equals expected
+        const result = await waitForAssertion(() => assertValueEquals(element, value), { timeout: 1000, interval: 50 });
+        if (!result.success) {
+            throw createVerificationError('fill', result, selector);
+        }
+        return { success: true, error: null };
     }
     async clear(selector) {
         const element = this.getElement(selector);
@@ -388,7 +402,7 @@ export class DOMActions {
             element.dispatchEvent(new Event('input', { bubbles: true }));
             element.dispatchEvent(new Event('change', { bubbles: true }));
         }
-        return { cleared: true };
+        return { success: true, error: null };
     }
     async check(selector) {
         const element = this.getElement(selector);
@@ -400,7 +414,12 @@ export class DOMActions {
         if (!element.checked) {
             element.click();
         }
-        return { checked: true };
+        // Wait for verification that element is checked
+        const result = await waitForAssertion(() => assertChecked(element, true), { timeout: 1000, interval: 50 });
+        if (!result.success) {
+            throw createVerificationError('check', result, selector);
+        }
+        return { success: true, error: null };
     }
     async uncheck(selector) {
         const element = this.getElement(selector);
@@ -412,7 +431,12 @@ export class DOMActions {
         if (element.checked) {
             element.click();
         }
-        return { unchecked: true };
+        // Wait for verification that element is unchecked
+        const result = await waitForAssertion(() => assertChecked(element, false), { timeout: 1000, interval: 50 });
+        if (!result.success) {
+            throw createVerificationError('uncheck', result, selector);
+        }
+        return { success: true, error: null };
     }
     async select(selector, values) {
         const element = this.getElement(selector);
@@ -426,27 +450,32 @@ export class DOMActions {
             option.selected = valueArray.includes(option.value);
         }
         element.dispatchEvent(new Event('change', { bubbles: true }));
-        return { selected: valueArray };
+        // Wait for verification that expected options are selected
+        const result = await waitForAssertion(() => assertSelected(element, valueArray), { timeout: 1000, interval: 50 });
+        if (!result.success) {
+            throw createVerificationError('select', result, selector);
+        }
+        return { success: true, error: null, values: valueArray };
     }
     async focus(selector) {
         const element = this.getElement(selector);
         if (element instanceof HTMLElement) {
             element.focus();
         }
-        return { focused: true };
+        return { success: true, error: null };
     }
     async blur(selector) {
         const element = this.getElement(selector);
         if (element instanceof HTMLElement) {
             element.blur();
         }
-        return { blurred: true };
+        return { success: true, error: null };
     }
     async hover(selector) {
         const element = this.getElement(selector);
         element.dispatchEvent(new MouseEvent('mouseenter', { bubbles: true }));
         element.dispatchEvent(new MouseEvent('mouseover', { bubbles: true }));
-        return { hovered: true };
+        return { success: true, error: null };
     }
     async scroll(selector, options) {
         // Validate parameter combinations
@@ -481,12 +510,12 @@ export class DOMActions {
         else {
             this.window.scrollBy(deltaX, deltaY);
         }
-        return { scrolled: true };
+        return { success: true, error: null };
     }
     async scrollIntoView(selector, block = 'center') {
         const element = this.getElement(selector);
         element.scrollIntoView({ behavior: 'smooth', block });
-        return { scrolled: true };
+        return { success: true, error: null };
     }
     async snapshot(options) {
         const root = options.selector
@@ -512,32 +541,34 @@ export class DOMActions {
     async querySelector(selector) {
         const element = this.queryElement(selector);
         if (!element) {
-            return { found: false };
+            return { success: false, error: `Element not found: ${selector}` };
         }
         const ref = this.refMap.generateRef(element);
-        return { found: true, ref };
+        return { success: true, error: null, ref };
     }
     async querySelectorAll(selector) {
         const elements = this.queryElements(selector);
         const refs = elements.map((el) => this.refMap.generateRef(el));
-        return { count: elements.length, refs };
+        return { success: true, error: null, count: elements.length, refs };
     }
     async getText(selector) {
         const element = this.getElement(selector);
-        return { text: element.textContent };
+        return { success: true, error: null, text: element.textContent };
     }
     async getAttribute(selector, attribute) {
         const element = this.getElement(selector);
-        return { value: element.getAttribute(attribute) };
+        return { success: true, error: null, value: element.getAttribute(attribute) };
     }
     async getProperty(selector, property) {
         const element = this.getElement(selector);
-        return { value: element[property] };
+        return { success: true, error: null, value: element[property] };
     }
     async getBoundingBox(selector) {
         const element = this.getElement(selector);
         const rect = element.getBoundingClientRect();
         return {
+            success: true,
+            error: null,
             box: {
                 x: rect.x,
                 y: rect.y,
@@ -549,23 +580,23 @@ export class DOMActions {
     async isVisible(selector) {
         const element = this.queryElement(selector);
         if (!element || !(element instanceof HTMLElement)) {
-            return { visible: false };
+            return { success: true, error: null, visible: false };
         }
         const style = this.window.getComputedStyle(element);
         const visible = style.display !== 'none' &&
             style.visibility !== 'hidden' &&
             style.opacity !== '0';
-        return { visible };
+        return { success: true, error: null, visible };
     }
     async isEnabled(selector) {
         const element = this.getElement(selector);
         const enabled = !element.disabled;
-        return { enabled };
+        return { success: true, error: null, enabled };
     }
     async isChecked(selector) {
         const element = this.getElement(selector);
         const checked = element.checked ?? false;
-        return { checked };
+        return { success: true, error: null, checked };
     }
     async press(key, selector, modifiers = []) {
         const target = selector
@@ -584,23 +615,23 @@ export class DOMActions {
         target.dispatchEvent(new KeyboardEvent('keydown', eventInit));
         target.dispatchEvent(new KeyboardEvent('keypress', eventInit));
         target.dispatchEvent(new KeyboardEvent('keyup', eventInit));
-        return { pressed: true };
+        return { success: true, error: null };
     }
     async keyDown(key) {
         const target = this.document.activeElement || this.document.body;
         target.dispatchEvent(new KeyboardEvent('keydown', { key, bubbles: true }));
-        return { down: true };
+        return { success: true, error: null };
     }
     async keyUp(key) {
         const target = this.document.activeElement || this.document.body;
         target.dispatchEvent(new KeyboardEvent('keyup', { key, bubbles: true }));
-        return { up: true };
+        return { success: true, error: null };
     }
     async wait(selector, options = {}) {
         const { state = 'visible', timeout = 5000 } = options;
         if (!selector) {
             await this.sleep(timeout);
-            return { waited: true };
+            return { success: true, error: null };
         }
         const startTime = Date.now();
         let lastState;
@@ -649,7 +680,7 @@ export class DOMActions {
                     break;
             }
             if (conditionMet) {
-                return { waited: true };
+                return { success: true, error: null };
             }
             await this.sleep(100);
         }
@@ -659,7 +690,7 @@ export class DOMActions {
     async evaluate(script, args) {
         const fn = new Function(...(args?.map((_, i) => `arg${i}`) || []), `return (${script})`);
         const result = fn.call(this.window, ...(args || []));
-        return { result };
+        return { success: true, error: null, result };
     }
     /**
      * Validate element capabilities before attempting an action
@@ -765,15 +796,15 @@ export class DOMActions {
         // Create overlay container with absolute positioning covering entire document
         this.overlayContainer = this.document.createElement('div');
         this.overlayContainer.id = 'btcp-highlight-overlay';
-        this.overlayContainer.style.cssText = `
-      position: absolute;
-      top: 0;
-      left: 0;
-      width: ${this.document.documentElement.scrollWidth}px;
-      height: ${this.document.documentElement.scrollHeight}px;
-      pointer-events: none;
-      z-index: 999999;
-      contain: layout style paint;
+        this.overlayContainer.style.cssText = `
+      position: absolute;
+      top: 0;
+      left: 0;
+      width: ${this.document.documentElement.scrollWidth}px;
+      height: ${this.document.documentElement.scrollHeight}px;
+      pointer-events: none;
+      z-index: 999999;
+      contain: layout style paint;
     `;
         let highlightedCount = 0;
         // Create border overlays and labels for each ref
@@ -794,17 +825,17 @@ export class DOMActions {
                 const border = this.document.createElement('div');
                 border.className = 'btcp-ref-border';
                 border.dataset.ref = ref;
-                border.style.cssText = `
-          position: absolute;
-          width: ${bbox.width}px;
-          height: ${bbox.height}px;
-          transform: translate3d(${bbox.left + this.window.scrollX}px, ${bbox.top + this.window.scrollY}px, 0);
-          border: 2px solid rgba(59, 130, 246, 0.8);
-          border-radius: 2px;
-          box-shadow: 0 0 0 1px rgba(59, 130, 246, 0.2);
-          pointer-events: none;
-          will-change: transform;
-          contain: layout style paint;
+                border.style.cssText = `
+          position: absolute;
+          width: ${bbox.width}px;
+          height: ${bbox.height}px;
+          transform: translate3d(${bbox.left + this.window.scrollX}px, ${bbox.top + this.window.scrollY}px, 0);
+          border: 2px solid rgba(59, 130, 246, 0.8);
+          border-radius: 2px;
+          box-shadow: 0 0 0 1px rgba(59, 130, 246, 0.2);
+          pointer-events: none;
+          will-change: transform;
+          contain: layout style paint;
         `;
                 // Create label
                 const label = this.document.createElement('div');
@@ -812,21 +843,21 @@ export class DOMActions {
                 label.dataset.ref = ref;
                 // Extract number from ref (e.g., "@ref:5" -> "5")
                 label.textContent = ref.replace('@ref:', '');
-                label.style.cssText = `
-          position: absolute;
-          transform: translate3d(${bbox.left + this.window.scrollX}px, ${bbox.top + this.window.scrollY}px, 0);
-          background: rgba(59, 130, 246, 0.9);
-          color: white;
-          padding: 2px 6px;
-          border-radius: 3px;
-          font-family: monospace;
-          font-size: 11px;
-          font-weight: bold;
-          box-shadow: 0 2px 4px rgba(0,0,0,0.3);
-          pointer-events: none;
-          white-space: nowrap;
-          will-change: transform;
-          contain: layout style paint;
+                label.style.cssText = `
+          position: absolute;
+          transform: translate3d(${bbox.left + this.window.scrollX}px, ${bbox.top + this.window.scrollY}px, 0);
+          background: rgba(59, 130, 246, 0.9);
+          color: white;
+          padding: 2px 6px;
+          border-radius: 3px;
+          font-family: monospace;
+          font-size: 11px;
+          font-weight: bold;
+          box-shadow: 0 2px 4px rgba(0,0,0,0.3);
+          pointer-events: none;
+          white-space: nowrap;
+          will-change: transform;
+          contain: layout style paint;
         `;
                 this.overlayContainer.appendChild(border);
                 this.overlayContainer.appendChild(label);
@@ -852,7 +883,7 @@ export class DOMActions {
         };
         // Use passive listener for better scroll performance
         this.window.addEventListener('scroll', this.scrollListener, { passive: true });
-        return { highlighted: highlightedCount };
+        return { success: true, error: null, count: highlightedCount };
     }
     /**
      * Invalidate snapshot data (called on navigation or manual clear)
@@ -921,7 +952,7 @@ export class DOMActions {
      */
     async clearHighlight() {
         this.clearExistingOverlay();
-        return { cleared: true };
+        return { success: true, error: null };
     }
     /**
      * Remove existing overlay if it exists

package/packages/core/dist/assertions.d.ts

@@ -0,0 +1,118 @@
+/**
+ * @btcp/core - Assertions Module
+ *
+ * Provides verification utilities for DOM actions with async waiting support.
+ * Returns structured results for consistent error handling.
+ */
+/**
+ * Base interface for all action results
+ * Provides unified success/error pattern across all DOM operations
+ *
+ * Use intersection types to add action-specific data:
+ * @example
+ * ```typescript
+ * type ClickResult = ActionResult & { connected: boolean };
+ * type GetTextResult = ActionResult & { text: string | null };
+ * ```
+ */
+export interface ActionResult {
+    /** Whether the action succeeded */
+    success: boolean;
+    /** Error message if action failed, null otherwise */
+    error: string | null;
+}
+/**
+ * Result of a single assertion check
+ */
+export interface AssertionResult {
+    /** Whether the assertion succeeded */
+    success: boolean;
+    /** Error message if assertion failed, null otherwise */
+    error: string | null;
+    /** Human-readable description of what was checked */
+    description: string;
+    /** The expected value */
+    expected: unknown;
+    /** The actual value found */
+    actual: unknown;
+    /** Additional context information */
+    context?: Record<string, unknown>;
+}
+/**
+ * Options for waiting on an assertion
+ */
+export interface WaitForAssertionOptions {
+    /** Maximum time to wait in milliseconds (default: 1000) */
+    timeout?: number;
+    /** Interval between checks in milliseconds (default: 50) */
+    interval?: number;
+}
+/**
+ * Result of waiting for an assertion
+ */
+export interface WaitResult {
+    /** Whether the assertion passed within the timeout */
+    success: boolean;
+    /** Total time elapsed in milliseconds */
+    elapsed: number;
+    /** Number of attempts made */
+    attempts: number;
+    /** The final assertion result */
+    result: AssertionResult;
+}
+/**
+ * Assert that an element is still connected to the DOM
+ */
+export declare function assertConnected(element: Element): AssertionResult;
+/**
+ * Assert that an input/textarea value contains the expected text
+ */
+export declare function assertValueContains(element: HTMLInputElement | HTMLTextAreaElement, text: string): AssertionResult;
+/**
+ * Assert that an input/textarea value equals the expected value exactly
+ */
+export declare function assertValueEquals(element: HTMLInputElement | HTMLTextAreaElement, value: string): AssertionResult;
+/**
+ * Assert that a checkbox/radio is in the expected checked state
+ */
+export declare function assertChecked(element: HTMLInputElement, expected: boolean): AssertionResult;
+/**
+ * Assert that a select element has the expected values selected
+ */
+export declare function assertSelected(element: HTMLSelectElement, values: string[]): AssertionResult;
+/**
+ * Assert that a URL matches the expected origin
+ */
+export declare function assertUrlOrigin(actualUrl: string, expectedUrl: string): AssertionResult;
+/**
+ * Assert that an element is visible (or hidden)
+ */
+export declare function assertVisible(element: HTMLElement, win: Window, expected?: boolean): AssertionResult;
+/**
+ * Assert that an element is enabled (or disabled)
+ */
+export declare function assertEnabled(element: HTMLElement, expected?: boolean): AssertionResult;
+/**
+ * Wait for an assertion to pass within a timeout period
+ *
+ * Polls the assertion function at regular intervals until it passes
+ * or the timeout is reached.
+ *
+ * @param assertFn - Function that returns an AssertionResult
+ * @param options - Timeout and interval options
+ * @returns WaitResult with success status and timing information
+ *
+ * @example
+ * ```typescript
+ * const result = await waitForAssertion(
+ *   () => assertValueEquals(input, 'hello'),
+ *   { timeout: 1000, interval: 50 }
+ * );
+ *
+ * if (!result.success) {
+ *   throw createVerificationError('fill', result, selector);
+ * }
+ * ```
+ */
+export declare function waitForAssertion(assertFn: () => AssertionResult, options?: WaitForAssertionOptions): Promise<WaitResult>;
+//# sourceMappingURL=assertions.d.ts.map