btcp-browser-agent 0.1.4 → 0.1.7

package/dist/index.d.ts

@@ -25,10 +25,10 @@
  * ```typescript
  * import { createContentAgent } from '@btcp/browser-agent';
  * const agent = createContentAgent();
- * await agent.execute({ id: '1', action: 'snapshot' });
+ * await agent.execute({ action: 'snapshot' });
  * ```
  */
 export { createContentAgent, type ContentAgent, DOMActions, createSnapshot, createRefMap, createSimpleRefMap, type Command, type Response, type SnapshotData, type BoundingBox, type RefMap, type Modifier, } from '../packages/core/dist/index.js';
 export type { ExtensionMessage, ExtensionResponse, TabInfo, ChromeTab, ExtensionCommand, } from '../packages/extension/dist/index.js';
-export { BackgroundAgent, getBackgroundAgent, setupMessageListener, createClient, type Client, } from '../packages/extension/dist/index.js';
+export { BackgroundAgent, getBackgroundAgent, setupMessageListener, createClient, generateCommandId, type Client, BrowserAgent, getBrowserAgent, } from '../packages/extension/dist/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -25,11 +25,13 @@
  * ```typescript
  * import { createContentAgent } from '@btcp/browser-agent';
  * const agent = createContentAgent();
- * await agent.execute({ id: '1', action: 'snapshot' });
+ * await agent.execute({ action: 'snapshot' });
  * ```
  */
 // Re-export everything from core (for standalone usage)
 export { createContentAgent, DOMActions, createSnapshot, createRefMap, createSimpleRefMap, } from '../packages/core/dist/index.js';
 // Re-export extension functions
-export { BackgroundAgent, getBackgroundAgent, setupMessageListener, createClient, } from '../packages/extension/dist/index.js';
+export { BackgroundAgent, getBackgroundAgent, setupMessageListener, createClient, generateCommandId, 
+// Deprecated aliases for backwards compatibility
+BrowserAgent, getBrowserAgent, } from '../packages/extension/dist/index.js';
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,69 +1,69 @@
-{
-  "name": "btcp-browser-agent",
-  "version": "0.1.4",
-  "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.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"
+  }
+}

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

@@ -4,6 +4,10 @@
  * Element interaction handlers using native browser APIs.
  */
 import type { Command, Response, RefMap } from './types.js';
+/**
+ * Generate a unique command ID
+ */
+export declare function generateCommandId(): string;
 /**
  * DOM Actions executor
  */
@@ -18,6 +22,8 @@ export declare class DOMActions {
     constructor(doc: Document, win: Window, refMap: RefMap);
     /**
      * Execute a command and return a response
+     *
+     * The command ID is auto-generated internally - users don't need to provide it.
      */
     execute(command: Command): Promise<Response>;
     private dispatch;

package/packages/core/dist/actions.js

@@ -5,6 +5,14 @@
  */
 import { createSnapshot } from './snapshot.js';
 import { DetailedError, createElementNotFoundError, createElementNotCompatibleError, createTimeoutError, createInvalidParametersError, } from './errors.js';
+// Command ID counter for auto-generated IDs
+let commandIdCounter = 0;
+/**
+ * Generate a unique command ID
+ */
+export function generateCommandId() {
+    return `cmd_${Date.now()}_${commandIdCounter++}`;
+}
 /**
  * DOM Actions executor
  */
@@ -23,18 +31,22 @@ export class DOMActions {
     }
     /**
      * Execute a command and return a response
+     *
+     * The command ID is auto-generated internally - users don't need to provide it.
      */
     async execute(command) {
+        // Auto-generate ID if not provided
+        const id = command.id || generateCommandId();
         try {
             const data = await this.dispatch(command);
-            return { id: command.id, success: true, data };
+            return { id, success: true, data };
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
             // Include structured error data if available
             if (error instanceof DetailedError) {
                 return {
-                    id: command.id,
+                    id,
                     success: false,
                     error: message,
                     errorCode: error.code,
@@ -42,7 +54,7 @@ export class DOMActions {
                     suggestions: error.suggestions,
                 };
             }
-            return { id: command.id, success: false, error: message };
+            return { id, success: false, error: message };
         }
     }
     async dispatch(command) {
@@ -90,11 +102,13 @@ export class DOMActions {
                     selector: command.selector,
                     maxDepth: command.maxDepth,
                     includeHidden: command.includeHidden,
-                    interactive: command.interactive,
                     compact: command.compact,
-                    all: command.all,
+                    mode: command.mode,
                     format: command.format,
                     grep: command.grep,
+                    maxLength: command.maxLength,
+                    includeLinks: command.includeLinks,
+                    includeImages: command.includeImages,
                 });
             case 'querySelector':
                 return this.querySelector(command.selector);
@@ -482,11 +496,13 @@ export class DOMActions {
             root,
             maxDepth: options.maxDepth,
             includeHidden: options.includeHidden,
-            interactive: options.interactive,
             compact: options.compact,
-            all: options.all,
+            mode: options.mode,
             format: options.format,
             grep: options.grep,
+            maxLength: options.maxLength,
+            includeLinks: options.includeLinks,
+            includeImages: options.includeImages,
         });
         // Store snapshot data for highlight command (preserve refs internally)
         this.lastSnapshotData = snapshotData;
@@ -749,15 +765,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
@@ -778,17 +794,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');
@@ -796,21 +812,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);

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

@@ -11,17 +11,10 @@
  * const agent = createContentAgent(document, window);
  *
  * // Take a snapshot
- * const snapshot = await agent.execute({
- *   id: '1',
- *   action: 'snapshot'
- * });
+ * const snapshot = await agent.execute({ action: 'snapshot' });
  *
  * // Click an element
- * await agent.execute({
- *   id: '2',
- *   action: 'click',
- *   selector: '@ref:5'  // From snapshot
- * });
+ * await agent.execute({ action: 'click', selector: '@ref:5' });
  * ```
  */
 import type { Command, Response, RefMap } from './types.js';
@@ -29,7 +22,7 @@ export * from './types.js';
 export * from './errors.js';
 export { createSnapshot } from './snapshot.js';
 export { createRefMap, createSimpleRefMap } from './ref-map.js';
-export { DOMActions } from './actions.js';
+export { DOMActions, generateCommandId } from './actions.js';
 /**
  * ContentAgent - DOM automation agent that runs in content script context
  *
@@ -83,10 +76,10 @@ export interface ContentAgent {
  * const agent = createContentAgent();
  *
  * // Take a snapshot of the page
- * const { data } = await agent.execute({ id: '1', action: 'snapshot' });
+ * const { data } = await agent.execute({ action: 'snapshot' });
  *
  * // Click an element using ref from snapshot
- * await agent.execute({ id: '2', action: 'click', selector: '@ref:5' });
+ * await agent.execute({ action: 'click', selector: '@ref:5' });
  * ```
  */
 export declare function createContentAgent(doc?: Document, win?: Window): ContentAgent;

package/packages/core/dist/index.js

@@ -11,17 +11,10 @@
  * const agent = createContentAgent(document, window);
  *
  * // Take a snapshot
- * const snapshot = await agent.execute({
- *   id: '1',
- *   action: 'snapshot'
- * });
+ * const snapshot = await agent.execute({ action: 'snapshot' });
  *
  * // Click an element
- * await agent.execute({
- *   id: '2',
- *   action: 'click',
- *   selector: '@ref:5'  // From snapshot
- * });
+ * await agent.execute({ action: 'click', selector: '@ref:5' });
  * ```
  */
 import { DOMActions } from './actions.js';
@@ -30,7 +23,7 @@ export * from './types.js';
 export * from './errors.js';
 export { createSnapshot } from './snapshot.js';
 export { createRefMap, createSimpleRefMap } from './ref-map.js';
-export { DOMActions } from './actions.js';
+export { DOMActions, generateCommandId } from './actions.js';
 /**
  * Create a ContentAgent for DOM automation
  *
@@ -44,10 +37,10 @@ export { DOMActions } from './actions.js';
  * const agent = createContentAgent();
  *
  * // Take a snapshot of the page
- * const { data } = await agent.execute({ id: '1', action: 'snapshot' });
+ * const { data } = await agent.execute({ action: 'snapshot' });
  *
  * // Click an element using ref from snapshot
- * await agent.execute({ id: '2', action: 'click', selector: '@ref:5' });
+ * await agent.execute({ action: 'click', selector: '@ref:5' });
  * ```
  */
 export function createContentAgent(doc = document, win = window) {

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

@@ -3,8 +3,13 @@
  *
  * Generates a flat accessibility snapshot of the DOM.
  * Produces a compact, AI-friendly list of interactive elements.
+ *
+ * Supports three modes:
+ * - 'interactive': Find clickable elements (default)
+ * - 'outline': Understand page structure with xpaths + metadata
+ * - 'content': Extract text content from sections
  */
-import type { SnapshotData, RefMap } from './types.js';
+import type { SnapshotData, RefMap, SnapshotMode, SnapshotFormat } from './types.js';
 /**
  * Grep options (mirrors Unix grep flags)
  */
@@ -22,15 +27,37 @@ interface SnapshotOptions {
     root?: Element;
     maxDepth?: number;
     includeHidden?: boolean;
-    interactive?: boolean;
     compact?: boolean;
-    all?: boolean;
-    format?: 'tree' | 'html';
+    /**
+     * Snapshot mode:
+     * - 'interactive': Find clickable elements (default)
+     * - 'outline': Understand page structure with xpaths + metadata
+     * - 'content': Extract text content from sections
+     */
+    mode?: SnapshotMode;
+    /**
+     * Output format:
+     * - 'tree': Flat accessibility tree (default)
+     * - 'html': Raw HTML
+     * - 'markdown': Markdown formatted content
+     */
+    format?: SnapshotFormat;
     /** Grep filter - string pattern or options object */
     grep?: string | GrepOptions;
+    /** Max chars per section in content mode */
+    maxLength?: number;
+    /** Include links as [text](url) in markdown format */
+    includeLinks?: boolean;
+    /** Include images as ![alt](src) in markdown format */
+    includeImages?: boolean;
 }
 /**
  * Generate flat snapshot of the DOM
+ *
+ * Supports three modes:
+ * - 'interactive' (default): Find clickable elements with @ref markers
+ * - 'outline': Structural overview with xpaths and metadata
+ * - 'content': Extract text content from sections
  */
 export declare function createSnapshot(document: Document, refMap: RefMap, options?: SnapshotOptions): SnapshotData;
 export {};