sentience-ts 0.10.3 → 0.10.5

package/README.md

@@ -2,12 +2,11 @@
 
 **📜 License**: Apache License 2.0
 
-TypeScript SDK for Sentience AI Agent Browser Automation.
+TypeScript/JavaScript SDK for Sentience AI Agent Browser Automation. Build intelligent web automation agents that can see, understand, and interact with web pages like humans do.
 
 ## Installation
 
 ```bash
-cd sdk-ts
 npm install
 npm run build
 
@@ -21,20 +20,20 @@ npx playwright install chromium
 import { SentienceBrowser, snapshot, find, click } from './src';
 
 async function main() {
-  const browser = new SentienceBrowser(undefined, undefined, false);
-  
+  const browser = new SentienceBrowser();
+
   try {
     await browser.start();
-    
-    await browser.getPage().goto('https://example.com');
+
+    await browser.goto('https://example.com');
     await browser.getPage().waitForLoadState('networkidle');
-    
-    // Take snapshot
+
+    // Take snapshot - captures all interactive elements
     const snap = await snapshot(browser);
     console.log(`Found ${snap.elements.length} elements`);
-    
-    // Find and click a link
-    const link = find(snap, 'role=link');
+
+    // Find and click a link using semantic selectors
+    const link = find(snap, 'role=link text~"More information"');
     if (link) {
       const result = await click(browser, link.id);
       console.log(`Click success: ${result.success}`);
@@ -43,131 +42,259 @@ async function main() {
     await browser.close();
   }
 }
+
+main();
 ```
 
+## Real-World Example: Amazon Shopping Bot
+
+This example demonstrates navigating Amazon, finding products, and adding items to cart:
+
+```typescript
+import { SentienceBrowser, snapshot, find, click } from './src';
+
+async function main() {
+  const browser = new SentienceBrowser(undefined, undefined, false);
+
+  try {
+    await browser.start();
+
+    // Navigate to Amazon Best Sellers
+    await browser.goto('https://www.amazon.com/gp/bestsellers/');
+    await browser.getPage().waitForLoadState('networkidle');
+    await new Promise(resolve => setTimeout(resolve, 2000));
+
+    // Take snapshot and find products
+    const snap = await snapshot(browser);
+    console.log(`Found ${snap.elements.length} elements`);
+
+    // Find first product in viewport using spatial filtering
+    const products = snap.elements
+      .filter(el =>
+        el.role === 'link' &&
+        el.visual_cues.is_clickable &&
+        el.in_viewport &&
+        !el.is_occluded &&
+        el.bbox.y < 600  // First row
+      );
+
+    if (products.length > 0) {
+      // Sort by position (left to right, top to bottom)
+      products.sort((a, b) => a.bbox.y - b.bbox.y || a.bbox.x - b.bbox.x);
+      const firstProduct = products[0];
+
+      console.log(`Clicking: ${firstProduct.text}`);
+      const result = await click(browser, firstProduct.id);
+
+      // Wait for product page
+      await browser.getPage().waitForLoadState('networkidle');
+      await new Promise(resolve => setTimeout(resolve, 2000));
+
+      // Find and click "Add to Cart" button
+      const productSnap = await snapshot(browser);
+      const addToCart = find(productSnap, 'role=button text~"add to cart"');
+
+      if (addToCart) {
+        const cartResult = await click(browser, addToCart.id);
+        console.log(`Added to cart: ${cartResult.success}`);
+      }
+    }
+  } finally {
+    await browser.close();
+  }
+}
+
+main();
+```
+
+**See the complete tutorial**: [Amazon Shopping Guide](../docs/AMAZON_SHOPPING_GUIDE.md)
+
 ## Running Examples
 
 **⚠️ Important**: You cannot use `node` directly to run TypeScript files. Use one of these methods:
 
-**Option 1: Using npm scripts (recommended)**
+### Option 1: Using npm scripts (recommended)
 ```bash
 npm run example:hello
 npm run example:basic
+npm run example:query
+npm run example:wait
 ```
 
-**Option 2: Using ts-node directly**
+### Option 2: Using ts-node directly
 ```bash
 npx ts-node examples/hello.ts
 # or if ts-node is installed globally:
 ts-node examples/hello.ts
 ```
 
-**Option 3: Compile then run (not recommended for examples)**
+### Option 3: Compile then run
 ```bash
 npm run build
-# Examples would need to be compiled separately
+# Then use compiled JavaScript from dist/
 ```
 
-## Features
+## Core Features
 
-### Day 2: Browser Harness
-- `SentienceBrowser` - Launch Playwright with extension loaded
-- Automatic extension loading and verification
+### Browser Control
+- **`SentienceBrowser`** - Playwright browser with Sentience extension pre-loaded
+- **`browser.goto(url)`** - Navigate with automatic extension readiness checks
+- Automatic bot evasion and stealth mode
+- Configurable headless/headed mode
 
-### Day 3: Snapshot
-- `snapshot(browser, options)` - Capture page state
+### Snapshot - Intelligent Page Analysis
+- **`snapshot(browser, options?)`** - Capture page state with AI-ranked elements
+- Returns semantic elements with roles, text, importance scores, and bounding boxes
+- Optional screenshot capture (PNG/JPEG)
 - TypeScript types for type safety
 
-### Content Reading & Screenshots
-- `read(browser, options)` - Read page content as text or markdown
-  - Enhanced markdown conversion using `turndown` (better than extension's lightweight conversion)
-  - Supports `enhance_markdown` option to use improved conversion
-- `screenshot(browser, options)` - Capture standalone screenshot
-  - Returns base64-encoded data URL
-  - Supports PNG and JPEG formats with quality control
-
-### Day 4: Query Engine
-- `query(snapshot, selector)` - Find elements matching selector
-- `find(snapshot, selector)` - Find single best match
-- String DSL: `"role=button text~'Sign in'"`
-- **📖 [Complete DSL Query Guide](docs/QUERY_DSL.md)** - Comprehensive documentation with all operators, fields, and examples
-
-### Day 5: Actions
-- `click(browser, elementId)` - Click element
-- `typeText(browser, elementId, text)` - Type into element
-- `press(browser, key)` - Press keyboard key
-
-### Day 6: Wait & Assert
-- `waitFor(browser, selector, timeout)` - Wait for element
-- `expect(browser, selector)` - Assertion helper
-  - `.toExist()`
-  - `.toBeVisible()`
-  - `.toHaveText(text)`
-  - `.toHaveCount(n)`
+**Example:**
+```typescript
+const snap = await snapshot(browser, { screenshot: true });
 
-### Content Reading
-- `read(browser, options)` - Read page content
-  - **Default format: `"raw"`** - Returns HTML suitable for Turndown
-  - `format: "raw"` - Get cleaned HTML
-  - `format: "markdown"` - Get high-quality markdown (uses Turndown internally)
-  - `format: "text"` - Get plain text
-  
-  **Examples:**
-  ```typescript
-  import { read } from './src';
-  
-  // Get raw HTML (default)
-  const result = await read(browser);
-  const html = result.content;
-  
-  // Get high-quality markdown (uses Turndown automatically)
-  const result = await read(browser, { format: 'markdown' });
-  const markdown = result.content;
-  ```
-  
-  See `examples/read-markdown.ts` for complete examples.
+// Access structured data
+console.log(`URL: ${snap.url}`);
+console.log(`Viewport: ${snap.viewport.width}x${snap.viewport.height}`);
+console.log(`Elements: ${snap.elements.length}`);
 
-## Examples
+// Iterate over elements
+for (const element of snap.elements) {
+  console.log(`${element.role}: ${element.text} (importance: ${element.importance})`);
+}
+```
 
-See `examples/` directory:
-- `hello.ts` - Extension bridge verification
-- `basic-agent.ts` - Basic snapshot
-- `query-demo.ts` - Query engine
-- `wait-and-click.ts` - Wait and actions
-- `read-markdown.ts` - Reading page content and converting to markdown
+### Query Engine - Semantic Element Selection
+- **`query(snapshot, selector)`** - Find all matching elements
+- **`find(snapshot, selector)`** - Find single best match (by importance)
+- Powerful query DSL with multiple operators
 
-### Content Reading Example
+**Query Examples:**
+```typescript
+// Find by role and text
+const button = find(snap, 'role=button text="Sign in"');
+
+// Substring match (case-insensitive)
+const link = find(snap, 'role=link text~"more info"');
+
+// Spatial filtering
+const topLeft = find(snap, 'bbox.x<=100 bbox.y<=200');
+
+// Multiple conditions (AND logic)
+const primaryBtn = find(snap, 'role=button clickable=true visible=true importance>800');
+
+// Prefix/suffix matching
+const startsWith = find(snap, 'text^="Add"');
+const endsWith = find(snap, 'text$="Cart"');
+
+// Numeric comparisons
+const important = query(snap, 'importance>=700');
+const firstRow = query(snap, 'bbox.y<600');
+```
+
+**📖 [Complete Query DSL Guide](docs/QUERY_DSL.md)** - All operators, fields, and advanced patterns
+
+### Actions - Interact with Elements
+- **`click(browser, elementId)`** - Click element by ID
+- **`clickRect(browser, rect)`** - Click at center of rectangle (coordinate-based)
+- **`typeText(browser, elementId, text)`** - Type into input fields
+- **`press(browser, key)`** - Press keyboard keys (Enter, Escape, Tab, etc.)
+
+All actions return `ActionResult` with success status, timing, and outcome:
 
 ```typescript
-import { SentienceBrowser, read } from './src';
+const result = await click(browser, element.id);
 
-const browser = new SentienceBrowser();
-await browser.start();
+console.log(`Success: ${result.success}`);
+console.log(`Outcome: ${result.outcome}`);  // "navigated", "dom_updated", "error"
+console.log(`Duration: ${result.duration_ms}ms`);
+console.log(`URL changed: ${result.url_changed}`);
+```
 
-await browser.getPage().goto('https://example.com');
-await browser.getPage().waitForLoadState('networkidle');
+**Coordinate-based clicking:**
+```typescript
+import { clickRect } from './src';
+
+// Click at center of rectangle (x, y, width, height)
+await clickRect(browser, { x: 100, y: 200, w: 50, h: 30 });
+
+// With visual highlight (default: red border for 2 seconds)
+await clickRect(browser, { x: 100, y: 200, w: 50, h: 30 }, true, 2.0);
+
+// Using element's bounding box
+const snap = await snapshot(browser);
+const element = find(snap, 'role=button');
+if (element) {
+  await clickRect(browser, {
+    x: element.bbox.x,
+    y: element.bbox.y,
+    w: element.bbox.width,
+    h: element.bbox.height
+  });
+}
+```
 
-// Read as enhanced markdown (better quality)
-const result = await read(browser, { 
-  format: 'markdown', 
-  enhance_markdown: true 
-});
-console.log(result.content);  // High-quality markdown
+### Wait & Assertions
+- **`waitFor(browser, selector, timeout?, interval?, useApi?)`** - Wait for element to appear
+- **`expect(browser, selector)`** - Assertion helper with fluent API
 
-await browser.close();
+**Examples:**
+```typescript
+// Wait for element (auto-detects optimal interval based on API usage)
+const result = await waitFor(browser, 'role=button text="Submit"', 10000);
+if (result.found) {
+  console.log(`Found after ${result.duration_ms}ms`);
+}
+
+// Use local extension with fast polling (250ms interval)
+const result = await waitFor(browser, 'role=button', 5000, undefined, false);
+
+// Use remote API with network-friendly polling (1500ms interval)
+const result = await waitFor(browser, 'role=button', 5000, undefined, true);
+
+// Custom interval override
+const result = await waitFor(browser, 'role=button', 5000, 500, false);
+
+// Semantic wait conditions
+await waitFor(browser, 'clickable=true', 5000);  // Wait for clickable element
+await waitFor(browser, 'importance>100', 5000);  // Wait for important element
+await waitFor(browser, 'role=link visible=true', 5000);  // Wait for visible link
+
+// Assertions
+await expect(browser, 'role=button text="Submit"').toExist(5000);
+await expect(browser, 'role=heading').toBeVisible();
+await expect(browser, 'role=button').toHaveText('Submit');
+await expect(browser, 'role=link').toHaveCount(10);
 ```
 
-### Screenshot Example
+### Content Reading
+- **`read(browser, options?)`** - Extract page content
+  - `format: "text"` - Plain text extraction
+  - `format: "markdown"` - High-quality markdown conversion (uses Turndown)
+  - `format: "raw"` - Cleaned HTML (default)
 
+**Example:**
 ```typescript
-import { SentienceBrowser, screenshot } from './src';
-import { writeFileSync } from 'fs';
+import { read } from './src';
 
-const browser = new SentienceBrowser();
-await browser.start();
+// Get markdown content
+const result = await read(browser, { format: 'markdown' });
+console.log(result.content);  // Markdown text
 
-await browser.getPage().goto('https://example.com');
-await browser.getPage().waitForLoadState('networkidle');
+// Get plain text
+const result = await read(browser, { format: 'text' });
+console.log(result.content);  // Plain text
+```
+
+### Screenshots
+- **`screenshot(browser, options?)`** - Standalone screenshot capture
+  - Returns base64-encoded data URL
+  - PNG or JPEG format
+  - Quality control for JPEG (1-100)
+
+**Example:**
+```typescript
+import { screenshot } from './src';
+import { writeFileSync } from 'fs';
 
 // Capture PNG screenshot
 const dataUrl = await screenshot(browser, { format: 'png' });
@@ -177,17 +304,196 @@ const base64Data = dataUrl.split(',')[1];
 const imageData = Buffer.from(base64Data, 'base64');
 writeFileSync('screenshot.png', imageData);
 
-await browser.close();
+// JPEG with quality control (smaller file size)
+const dataUrl = await screenshot(browser, { format: 'jpeg', quality: 85 });
 ```
 
+## Element Properties
+
+Elements returned by `snapshot()` have the following properties:
+
+```typescript
+element.id              // Unique identifier for interactions
+element.role            // ARIA role (button, link, textbox, heading, etc.)
+element.text            // Visible text content
+element.importance      // AI importance score (0-1000)
+element.bbox            // Bounding box (x, y, width, height)
+element.visual_cues     // Visual analysis (is_primary, is_clickable, background_color)
+element.in_viewport     // Is element visible in current viewport?
+element.is_occluded     // Is element covered by other elements?
+element.z_index         // CSS stacking order
+```
+
+## Query DSL Reference
+
+### Basic Operators
+
+| Operator | Description | Example |
+|----------|-------------|---------|
+| `=` | Exact match | `role=button` |
+| `!=` | Exclusion | `role!=link` |
+| `~` | Substring (case-insensitive) | `text~"sign in"` |
+| `^=` | Prefix match | `text^="Add"` |
+| `$=` | Suffix match | `text$="Cart"` |
+| `>`, `>=` | Greater than | `importance>500` |
+| `<`, `<=` | Less than | `bbox.y<600` |
+
+### Supported Fields
+
+- **Role**: `role=button|link|textbox|heading|...`
+- **Text**: `text`, `text~`, `text^=`, `text$=`
+- **Visibility**: `clickable=true|false`, `visible=true|false`
+- **Importance**: `importance`, `importance>=N`, `importance<N`
+- **Position**: `bbox.x`, `bbox.y`, `bbox.width`, `bbox.height`
+- **Layering**: `z_index`
+
+## Examples
+
+See the `examples/` directory for complete working examples:
+
+- **`hello.ts`** - Extension bridge verification
+- **`basic-agent.ts`** - Basic snapshot and element inspection
+- **`query-demo.ts`** - Query engine demonstrations
+- **`wait-and-click.ts`** - Waiting for elements and performing actions
+- **`read-markdown.ts`** - Content extraction and markdown conversion
+
 ## Testing
 
 ```bash
+# Run all tests
 npm test
+
+# Run with coverage
+npm run test:coverage
+
+# Run specific test file
+npm test -- snapshot.test.ts
 ```
 
+## Configuration
+
+### Viewport Size
+
+Default viewport is **1280x800** pixels. You can customize it using Playwright's API:
+
+```typescript
+const browser = new SentienceBrowser();
+await browser.start();
+
+// Set custom viewport before navigating
+await browser.getPage().setViewportSize({ width: 1920, height: 1080 });
+
+await browser.goto('https://example.com');
+```
+
+### Headless Mode
+
+```typescript
+// Headed mode (shows browser window)
+const browser = new SentienceBrowser(undefined, undefined, false);
+
+// Headless mode
+const browser = new SentienceBrowser(undefined, undefined, true);
+
+// Auto-detect based on environment (default)
+const browser = new SentienceBrowser();  // headless=true if CI=true, else false
+```
+
+## Best Practices
+
+### 1. Wait for Dynamic Content
+```typescript
+await browser.goto('https://example.com');
+await browser.getPage().waitForLoadState('networkidle');
+await new Promise(resolve => setTimeout(resolve, 1000));  // Extra buffer
+```
+
+### 2. Use Multiple Strategies for Finding Elements
+```typescript
+// Try exact match first
+let btn = find(snap, 'role=button text="Add to Cart"');
+
+// Fallback to fuzzy match
+if (!btn) {
+  btn = find(snap, 'role=button text~"cart"');
+}
+```
+
+### 3. Check Element Visibility Before Clicking
+```typescript
+if (element.in_viewport && !element.is_occluded) {
+  await click(browser, element.id);
+}
+```
+
+### 4. Handle Navigation
+```typescript
+const result = await click(browser, linkId);
+if (result.url_changed) {
+  await browser.getPage().waitForLoadState('networkidle');
+}
+```
+
+### 5. Use Screenshots Sparingly
+```typescript
+// Fast - no screenshot (only element data)
+const snap = await snapshot(browser);
+
+// Slower - with screenshot (for debugging/verification)
+const snap = await snapshot(browser, { screenshot: true });
+```
+
+### 6. Always Close Browser
+```typescript
+const browser = new SentienceBrowser();
+
+try {
+  await browser.start();
+  // ... your automation code
+} finally {
+  await browser.close();  // Always clean up
+}
+```
+
+## Troubleshooting
+
+### "Extension failed to load"
+**Solution:** Build the extension first:
+```bash
+cd sentience-chrome
+./build.sh
+```
+
+### "Cannot use import statement outside a module"
+**Solution:** Don't use `node` directly. Use `ts-node` or npm scripts:
+```bash
+npx ts-node examples/hello.ts
+# or
+npm run example:hello
+```
+
+### "Element not found"
+**Solutions:**
+- Ensure page is loaded: `await browser.getPage().waitForLoadState('networkidle')`
+- Use `waitFor()`: `await waitFor(browser, 'role=button', 10000)`
+- Debug elements: `console.log(snap.elements.map(el => el.text))`
+
+### Button not clickable
+**Solutions:**
+- Check visibility: `element.in_viewport && !element.is_occluded`
+- Scroll to element: `await browser.getPage().evaluate(\`window.sentience_registry[${element.id}].scrollIntoView()\`)`
+
 ## Documentation
 
-- **📖 [Query DSL Guide](docs/QUERY_DSL.md)** - Complete guide to the semantic query language
-- API Contract: `../spec/SNAPSHOT_V1.md`
-- Type Definitions: `../spec/sdk-types.md`
+- **📖 [Amazon Shopping Guide](../docs/AMAZON_SHOPPING_GUIDE.md)** - Complete tutorial with real-world example
+- **📖 [Query DSL Guide](docs/QUERY_DSL.md)** - Advanced query patterns and operators
+- **📄 [API Contract](../spec/SNAPSHOT_V1.md)** - Snapshot API specification
+- **📄 [Type Definitions](../spec/sdk-types.md)** - TypeScript/Python type definitions
+
+## License
+
+**📜 License**
+
+This SDK is licensed under the Apache License 2.0.
+
+Note: The SDK communicates with proprietary Sentience services and browser components that are not open source. Access to those components is governed by Sentience's Terms of Service.

package/dist/actions.d.ts

@@ -2,8 +2,53 @@
  * Actions v1 - click, type, press
  */
 import { SentienceBrowser } from './browser';
-import { ActionResult } from './types';
-export declare function click(browser: SentienceBrowser, elementId: number, takeSnapshot?: boolean): Promise<ActionResult>;
+import { ActionResult, BBox } from './types';
+export interface ClickRect {
+    x: number;
+    y: number;
+    w?: number;
+    width?: number;
+    h?: number;
+    height?: number;
+}
+export declare function click(browser: SentienceBrowser, elementId: number, useMouse?: boolean, takeSnapshot?: boolean): Promise<ActionResult>;
 export declare function typeText(browser: SentienceBrowser, elementId: number, text: string, takeSnapshot?: boolean): Promise<ActionResult>;
 export declare function press(browser: SentienceBrowser, key: string, takeSnapshot?: boolean): Promise<ActionResult>;
+/**
+ * Click at the center of a rectangle using Playwright's native mouse simulation.
+ * This uses a hybrid approach: calculates center coordinates and uses mouse.click()
+ * for realistic event simulation (triggers hover, focus, mousedown, mouseup).
+ *
+ * @param browser - SentienceBrowser instance
+ * @param rect - Rectangle with x, y, w (or width), h (or height) keys, or BBox object
+ * @param highlight - Whether to show a red border highlight when clicking (default: true)
+ * @param highlightDuration - How long to show the highlight in seconds (default: 2.0)
+ * @param takeSnapshot - Whether to take snapshot after action
+ * @returns ActionResult
+ *
+ * @example
+ * ```typescript
+ * // Click using rect object
+ * await clickRect(browser, { x: 100, y: 200, w: 50, h: 30 });
+ *
+ * // Click using BBox from element
+ * const snap = await snapshot(browser);
+ * const element = find(snap, "role=button");
+ * if (element) {
+ *   await clickRect(browser, {
+ *     x: element.bbox.x,
+ *     y: element.bbox.y,
+ *     w: element.bbox.width,
+ *     h: element.bbox.height
+ *   });
+ * }
+ *
+ * // Without highlight
+ * await clickRect(browser, { x: 100, y: 200, w: 50, h: 30 }, false);
+ *
+ * // Custom highlight duration
+ * await clickRect(browser, { x: 100, y: 200, w: 50, h: 30 }, true, 3.0);
+ * ```
+ */
+export declare function clickRect(browser: SentienceBrowser, rect: ClickRect | BBox, highlight?: boolean, highlightDuration?: number, takeSnapshot?: boolean): Promise<ActionResult>;
 //# sourceMappingURL=actions.d.ts.map

package/dist/actions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAY,MAAM,SAAS,CAAC;AAGjD,wBAAsB,KAAK,CACzB,OAAO,EAAE,gBAAgB,EACzB,SAAS,EAAE,MAAM,EACjB,YAAY,GAAE,OAAe,GAC5B,OAAO,CAAC,YAAY,CAAC,CA2CvB;AAED,wBAAsB,QAAQ,CAC5B,OAAO,EAAE,gBAAgB,EACzB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,YAAY,GAAE,OAAe,GAC5B,OAAO,CAAC,YAAY,CAAC,CA6CvB;AAED,wBAAsB,KAAK,CACzB,OAAO,EAAE,gBAAgB,EACzB,GAAG,EAAE,MAAM,EACX,YAAY,GAAE,OAAe,GAC5B,OAAO,CAAC,YAAY,CAAC,CA6BvB"}
+{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAY,IAAI,EAAE,MAAM,SAAS,CAAC;AAGvD,MAAM,WAAW,SAAS;IACxB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AA4DD,wBAAsB,KAAK,CACzB,OAAO,EAAE,gBAAgB,EACzB,SAAS,EAAE,MAAM,EACjB,QAAQ,GAAE,OAAc,EACxB,YAAY,GAAE,OAAe,GAC5B,OAAO,CAAC,YAAY,CAAC,CAyGvB;AAED,wBAAsB,QAAQ,CAC5B,OAAO,EAAE,gBAAgB,EACzB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,YAAY,GAAE,OAAe,GAC5B,OAAO,CAAC,YAAY,CAAC,CA6CvB;AAED,wBAAsB,KAAK,CACzB,OAAO,EAAE,gBAAgB,EACzB,GAAG,EAAE,MAAM,EACX,YAAY,GAAE,OAAe,GAC5B,OAAO,CAAC,YAAY,CAAC,CA6BvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAsB,SAAS,CAC7B,OAAO,EAAE,gBAAgB,EACzB,IAAI,EAAE,SAAS,GAAG,IAAI,EACtB,SAAS,GAAE,OAAc,EACzB,iBAAiB,GAAE,MAAY,EAC/B,YAAY,GAAE,OAAe,GAC5B,OAAO,CAAC,YAAY,CAAC,CA2FvB"}

package/dist/actions.js

@@ -6,20 +6,130 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.click = click;
 exports.typeText = typeText;
 exports.press = press;
+exports.clickRect = clickRect;
 const snapshot_1 = require("./snapshot");
-async function click(browser, elementId, takeSnapshot = false) {
+/**
+ * Highlight a rectangle with a red border overlay
+ */
+async function highlightRect(browser, rect, durationSec = 2.0) {
+    const page = browser.getPage();
+    const highlightId = `sentience_highlight_${Date.now()}`;
+    // Combine all arguments into a single object for Playwright
+    const args = {
+        rect: {
+            x: rect.x,
+            y: rect.y,
+            w: rect.w || rect.width || 0,
+            h: rect.h || rect.height || 0,
+        },
+        highlightId,
+        durationSec,
+    };
+    await page.evaluate((args) => {
+        const { rect, highlightId, durationSec } = args;
+        // Create overlay div
+        const overlay = document.createElement('div');
+        overlay.id = highlightId;
+        overlay.style.position = 'fixed';
+        overlay.style.left = `${rect.x}px`;
+        overlay.style.top = `${rect.y}px`;
+        overlay.style.width = `${rect.w}px`;
+        overlay.style.height = `${rect.h}px`;
+        overlay.style.border = '3px solid red';
+        overlay.style.borderRadius = '2px';
+        overlay.style.boxSizing = 'border-box';
+        overlay.style.pointerEvents = 'none';
+        overlay.style.zIndex = '999999';
+        overlay.style.backgroundColor = 'rgba(255, 0, 0, 0.1)';
+        overlay.style.transition = 'opacity 0.3s ease-out';
+        document.body.appendChild(overlay);
+        // Remove after duration
+        setTimeout(() => {
+            overlay.style.opacity = '0';
+            setTimeout(() => {
+                if (overlay.parentNode) {
+                    overlay.parentNode.removeChild(overlay);
+                }
+            }, 300); // Wait for fade-out transition
+        }, durationSec * 1000);
+    }, args);
+}
+async function click(browser, elementId, useMouse = true, takeSnapshot = false) {
     const page = browser.getPage();
     const startTime = Date.now();
     const urlBefore = page.url();
-    // Call extension click method
-    const success = await page.evaluate((id) => {
-        return window.sentience.click(id);
-    }, elementId);
+    let success;
+    if (useMouse) {
+        // Hybrid approach: Get element bbox from snapshot, calculate center, use mouse.click()
+        try {
+            const snap = await (0, snapshot_1.snapshot)(browser);
+            const element = snap.elements.find((el) => el.id === elementId);
+            if (element) {
+                // Calculate center of element bbox
+                const centerX = element.bbox.x + element.bbox.width / 2;
+                const centerY = element.bbox.y + element.bbox.height / 2;
+                // Use Playwright's native mouse click for realistic simulation
+                await page.mouse.click(centerX, centerY);
+                success = true;
+            }
+            else {
+                // Fallback to JS click if element not found in snapshot
+                try {
+                    success = await page.evaluate((id) => {
+                        return window.sentience.click(id);
+                    }, elementId);
+                }
+                catch (error) {
+                    // Navigation might have destroyed context, assume success if URL changed
+                    success = true;
+                }
+            }
+        }
+        catch (error) {
+            // Fallback to JS click on error
+            try {
+                success = await page.evaluate((id) => {
+                    return window.sentience.click(id);
+                }, elementId);
+            }
+            catch (evalError) {
+                // Navigation might have destroyed context, assume success
+                success = true;
+            }
+        }
+    }
+    else {
+        // Legacy JS-based click
+        try {
+            success = await page.evaluate((id) => {
+                return window.sentience.click(id);
+            }, elementId);
+        }
+        catch (error) {
+            // Navigation might have destroyed context, assume success
+            success = true;
+        }
+    }
     // Wait a bit for navigation/DOM updates
-    await page.waitForTimeout(500);
+    try {
+        await page.waitForTimeout(500);
+    }
+    catch (error) {
+        // Navigation might have happened, context destroyed
+    }
     const durationMs = Date.now() - startTime;
-    const urlAfter = page.url();
-    const urlChanged = urlBefore !== urlAfter;
+    // Check if URL changed (handle navigation gracefully)
+    let urlAfter;
+    let urlChanged;
+    try {
+        urlAfter = page.url();
+        urlChanged = urlBefore !== urlAfter;
+    }
+    catch (error) {
+        // Context destroyed due to navigation - assume URL changed
+        urlAfter = urlBefore;
+        urlChanged = true;
+    }
     // Determine outcome
     let outcome;
     if (urlChanged) {
@@ -34,7 +144,12 @@ async function click(browser, elementId, takeSnapshot = false) {
     // Optional snapshot after
     let snapshotAfter;
     if (takeSnapshot) {
-        snapshotAfter = await (0, snapshot_1.snapshot)(browser);
+        try {
+            snapshotAfter = await (0, snapshot_1.snapshot)(browser);
+        }
+        catch (error) {
+            // Navigation might have destroyed context
+        }
     }
     return {
         success,
@@ -110,4 +225,125 @@ async function press(browser, key, takeSnapshot = false) {
         snapshot_after: snapshotAfter,
     };
 }
+/**
+ * Click at the center of a rectangle using Playwright's native mouse simulation.
+ * This uses a hybrid approach: calculates center coordinates and uses mouse.click()
+ * for realistic event simulation (triggers hover, focus, mousedown, mouseup).
+ *
+ * @param browser - SentienceBrowser instance
+ * @param rect - Rectangle with x, y, w (or width), h (or height) keys, or BBox object
+ * @param highlight - Whether to show a red border highlight when clicking (default: true)
+ * @param highlightDuration - How long to show the highlight in seconds (default: 2.0)
+ * @param takeSnapshot - Whether to take snapshot after action
+ * @returns ActionResult
+ *
+ * @example
+ * ```typescript
+ * // Click using rect object
+ * await clickRect(browser, { x: 100, y: 200, w: 50, h: 30 });
+ *
+ * // Click using BBox from element
+ * const snap = await snapshot(browser);
+ * const element = find(snap, "role=button");
+ * if (element) {
+ *   await clickRect(browser, {
+ *     x: element.bbox.x,
+ *     y: element.bbox.y,
+ *     w: element.bbox.width,
+ *     h: element.bbox.height
+ *   });
+ * }
+ *
+ * // Without highlight
+ * await clickRect(browser, { x: 100, y: 200, w: 50, h: 30 }, false);
+ *
+ * // Custom highlight duration
+ * await clickRect(browser, { x: 100, y: 200, w: 50, h: 30 }, true, 3.0);
+ * ```
+ */
+async function clickRect(browser, rect, highlight = true, highlightDuration = 2.0, takeSnapshot = false) {
+    const page = browser.getPage();
+    const startTime = Date.now();
+    const urlBefore = page.url();
+    // Handle BBox object or ClickRect dict
+    let x, y, w, h;
+    if ('width' in rect && 'height' in rect && !('w' in rect) && !('h' in rect)) {
+        // BBox object (width and height are required in BBox)
+        const bbox = rect;
+        x = bbox.x;
+        y = bbox.y;
+        w = bbox.width;
+        h = bbox.height;
+    }
+    else {
+        // ClickRect dict
+        const clickRect = rect;
+        x = clickRect.x;
+        y = clickRect.y;
+        w = clickRect.w || clickRect.width || 0;
+        h = clickRect.h || clickRect.height || 0;
+    }
+    if (w <= 0 || h <= 0) {
+        return {
+            success: false,
+            duration_ms: 0,
+            outcome: 'error',
+            error: {
+                code: 'invalid_rect',
+                reason: 'Rectangle width and height must be positive',
+            },
+        };
+    }
+    // Calculate center of rectangle
+    const centerX = x + w / 2;
+    const centerY = y + h / 2;
+    // Show highlight before clicking (if enabled)
+    if (highlight) {
+        await highlightRect(browser, { x, y, w, h }, highlightDuration);
+        // Small delay to ensure highlight is visible
+        await page.waitForTimeout(50);
+    }
+    // Use Playwright's native mouse click for realistic simulation
+    let success;
+    let errorMsg;
+    try {
+        await page.mouse.click(centerX, centerY);
+        success = true;
+    }
+    catch (error) {
+        success = false;
+        errorMsg = error instanceof Error ? error.message : String(error);
+    }
+    // Wait a bit for navigation/DOM updates
+    await page.waitForTimeout(500);
+    const durationMs = Date.now() - startTime;
+    const urlAfter = page.url();
+    const urlChanged = urlBefore !== urlAfter;
+    // Determine outcome
+    let outcome;
+    if (urlChanged) {
+        outcome = 'navigated';
+    }
+    else if (success) {
+        outcome = 'dom_updated';
+    }
+    else {
+        outcome = 'error';
+    }
+    // Optional snapshot after
+    let snapshotAfter;
+    if (takeSnapshot) {
+        snapshotAfter = await (0, snapshot_1.snapshot)(browser);
+    }
+    return {
+        success,
+        duration_ms: durationMs,
+        outcome,
+        url_changed: urlChanged,
+        snapshot_after: snapshotAfter,
+        error: success
+            ? undefined
+            : { code: 'click_failed', reason: errorMsg || 'Click failed' },
+    };
+}
 //# sourceMappingURL=actions.js.map

package/dist/actions.js.map

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

package/dist/index.d.ts

@@ -4,7 +4,7 @@
 export { SentienceBrowser } from './browser';
 export { snapshot, SnapshotOptions } from './snapshot';
 export { query, find, parseSelector } from './query';
-export { click, typeText, press } from './actions';
+export { click, typeText, press, clickRect, ClickRect } from './actions';
 export { waitFor } from './wait';
 export { expect, Expectation } from './expect';
 export { Inspector, inspect } from './inspector';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AACvD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACrD,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AACjC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAC/C,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAChE,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AACvD,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAC7D,cAAc,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AACvD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACrD,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACzE,OAAO,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AACjC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAC/C,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAChE,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AACvD,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAC7D,cAAc,SAAS,CAAC"}

package/dist/index.js

@@ -17,7 +17,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.screenshot = exports.read = exports.generate = exports.ScriptGenerator = exports.record = exports.Recorder = exports.inspect = exports.Inspector = exports.Expectation = exports.expect = exports.waitFor = exports.press = exports.typeText = exports.click = exports.parseSelector = exports.find = exports.query = exports.snapshot = exports.SentienceBrowser = void 0;
+exports.screenshot = exports.read = exports.generate = exports.ScriptGenerator = exports.record = exports.Recorder = exports.inspect = exports.Inspector = exports.Expectation = exports.expect = exports.waitFor = exports.clickRect = exports.press = exports.typeText = exports.click = exports.parseSelector = exports.find = exports.query = exports.snapshot = exports.SentienceBrowser = void 0;
 var browser_1 = require("./browser");
 Object.defineProperty(exports, "SentienceBrowser", { enumerable: true, get: function () { return browser_1.SentienceBrowser; } });
 var snapshot_1 = require("./snapshot");
@@ -30,6 +30,7 @@ var actions_1 = require("./actions");
 Object.defineProperty(exports, "click", { enumerable: true, get: function () { return actions_1.click; } });
 Object.defineProperty(exports, "typeText", { enumerable: true, get: function () { return actions_1.typeText; } });
 Object.defineProperty(exports, "press", { enumerable: true, get: function () { return actions_1.press; } });
+Object.defineProperty(exports, "clickRect", { enumerable: true, get: function () { return actions_1.clickRect; } });
 var wait_1 = require("./wait");
 Object.defineProperty(exports, "waitFor", { enumerable: true, get: function () { return wait_1.waitFor; } });
 var expect_1 = require("./expect");

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;GAEG;;;;;;;;;;;;;;;;;AAEH,qCAA6C;AAApC,2GAAA,gBAAgB,OAAA;AACzB,uCAAuD;AAA9C,oGAAA,QAAQ,OAAA;AACjB,iCAAqD;AAA5C,8FAAA,KAAK,OAAA;AAAE,6FAAA,IAAI,OAAA;AAAE,sGAAA,aAAa,OAAA;AACnC,qCAAmD;AAA1C,gGAAA,KAAK,OAAA;AAAE,mGAAA,QAAQ,OAAA;AAAE,gGAAA,KAAK,OAAA;AAC/B,+BAAiC;AAAxB,+FAAA,OAAO,OAAA;AAChB,mCAA+C;AAAtC,gGAAA,MAAM,OAAA;AAAE,qGAAA,WAAW,OAAA;AAC5B,yCAAiD;AAAxC,sGAAA,SAAS,OAAA;AAAE,oGAAA,OAAO,OAAA;AAC3B,uCAAgE;AAAvD,oGAAA,QAAQ,OAAA;AAAoB,kGAAA,MAAM,OAAA;AAC3C,yCAAwD;AAA/C,4GAAA,eAAe,OAAA;AAAE,qGAAA,QAAQ,OAAA;AAClC,+BAAuD;AAA9C,4FAAA,IAAI,OAAA;AACb,2CAA6D;AAApD,wGAAA,UAAU,OAAA;AACnB,0CAAwB"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;GAEG;;;;;;;;;;;;;;;;;AAEH,qCAA6C;AAApC,2GAAA,gBAAgB,OAAA;AACzB,uCAAuD;AAA9C,oGAAA,QAAQ,OAAA;AACjB,iCAAqD;AAA5C,8FAAA,KAAK,OAAA;AAAE,6FAAA,IAAI,OAAA;AAAE,sGAAA,aAAa,OAAA;AACnC,qCAAyE;AAAhE,gGAAA,KAAK,OAAA;AAAE,mGAAA,QAAQ,OAAA;AAAE,gGAAA,KAAK,OAAA;AAAE,oGAAA,SAAS,OAAA;AAC1C,+BAAiC;AAAxB,+FAAA,OAAO,OAAA;AAChB,mCAA+C;AAAtC,gGAAA,MAAM,OAAA;AAAE,qGAAA,WAAW,OAAA;AAC5B,yCAAiD;AAAxC,sGAAA,SAAS,OAAA;AAAE,oGAAA,OAAO,OAAA;AAC3B,uCAAgE;AAAvD,oGAAA,QAAQ,OAAA;AAAoB,kGAAA,MAAM,OAAA;AAC3C,yCAAwD;AAA/C,4GAAA,eAAe,OAAA;AAAE,qGAAA,QAAQ,OAAA;AAClC,+BAAuD;AAA9C,4FAAA,IAAI,OAAA;AACb,2CAA6D;AAApD,wGAAA,UAAU,OAAA;AACnB,0CAAwB"}

package/dist/wait.d.ts

@@ -3,5 +3,18 @@
  */
 import { SentienceBrowser } from './browser';
 import { WaitResult, QuerySelector } from './types';
-export declare function waitFor(browser: SentienceBrowser, selector: QuerySelector, timeout?: number, interval?: number): Promise<WaitResult>;
+/**
+ * Wait for element matching selector to appear
+ *
+ * @param browser - SentienceBrowser instance
+ * @param selector - String DSL or dict query
+ * @param timeout - Maximum time to wait (milliseconds). Default: 10000ms (10 seconds)
+ * @param interval - Polling interval (milliseconds). If undefined, auto-detects:
+ *                   - 250ms for local extension (useApi=false, fast)
+ *                   - 1500ms for remote API (useApi=true or default, network latency)
+ * @param useApi - Force use of server-side API if true, local extension if false.
+ *                 If undefined, uses API if apiKey is set, otherwise uses local extension.
+ * @returns WaitResult
+ */
+export declare function waitFor(browser: SentienceBrowser, selector: QuerySelector, timeout?: number, interval?: number, useApi?: boolean): Promise<WaitResult>;
 //# sourceMappingURL=wait.d.ts.map

package/dist/wait.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"wait.d.ts","sourceRoot":"","sources":["../src/wait.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAW,aAAa,EAAE,MAAM,SAAS,CAAC;AAI7D,wBAAsB,OAAO,CAC3B,OAAO,EAAE,gBAAgB,EACzB,QAAQ,EAAE,aAAa,EACvB,OAAO,GAAE,MAAc,EACvB,QAAQ,GAAE,MAAY,GACrB,OAAO,CAAC,UAAU,CAAC,CAgCrB"}
+{"version":3,"file":"wait.d.ts","sourceRoot":"","sources":["../src/wait.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAW,aAAa,EAAE,MAAM,SAAS,CAAC;AAI7D;;;;;;;;;;;;GAYG;AACH,wBAAsB,OAAO,CAC3B,OAAO,EAAE,gBAAgB,EACzB,QAAQ,EAAE,aAAa,EACvB,OAAO,GAAE,MAAc,EACvB,QAAQ,CAAC,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE,OAAO,GACf,OAAO,CAAC,UAAU,CAAC,CA6CrB"}

package/dist/wait.js

@@ -6,11 +6,37 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.waitFor = waitFor;
 const snapshot_1 = require("./snapshot");
 const query_1 = require("./query");
-async function waitFor(browser, selector, timeout = 10000, interval = 250) {
+/**
+ * Wait for element matching selector to appear
+ *
+ * @param browser - SentienceBrowser instance
+ * @param selector - String DSL or dict query
+ * @param timeout - Maximum time to wait (milliseconds). Default: 10000ms (10 seconds)
+ * @param interval - Polling interval (milliseconds). If undefined, auto-detects:
+ *                   - 250ms for local extension (useApi=false, fast)
+ *                   - 1500ms for remote API (useApi=true or default, network latency)
+ * @param useApi - Force use of server-side API if true, local extension if false.
+ *                 If undefined, uses API if apiKey is set, otherwise uses local extension.
+ * @returns WaitResult
+ */
+async function waitFor(browser, selector, timeout = 10000, interval, useApi) {
+    // Auto-detect optimal interval based on API usage
+    if (interval === undefined) {
+        // Determine if using API
+        const willUseApi = useApi !== undefined
+            ? useApi
+            : (browser.getApiKey() !== undefined);
+        if (willUseApi) {
+            interval = 1500; // Longer interval for API calls (network latency)
+        }
+        else {
+            interval = 250; // Shorter interval for local extension (fast)
+        }
+    }
     const startTime = Date.now();
     while (Date.now() - startTime < timeout) {
-        // Take snapshot
-        const snap = await (0, snapshot_1.snapshot)(browser);
+        // Take snapshot (may be local extension or remote API)
+        const snap = await (0, snapshot_1.snapshot)(browser, { use_api: useApi });
         // Try to find element
         const element = (0, query_1.find)(snap, selector);
         if (element) {

package/dist/wait.js.map

@@ -1 +1 @@
-{"version":3,"file":"wait.js","sourceRoot":"","sources":["../src/wait.ts"],"names":[],"mappings":";AAAA;;GAEG;;AAOH,0BAqCC;AAxCD,yCAAsC;AACtC,mCAA+B;AAExB,KAAK,UAAU,OAAO,CAC3B,OAAyB,EACzB,QAAuB,EACvB,UAAkB,KAAK,EACvB,WAAmB,GAAG;IAEtB,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAE7B,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,GAAG,OAAO,EAAE,CAAC;QACxC,gBAAgB;QAChB,MAAM,IAAI,GAAG,MAAM,IAAA,mBAAQ,EAAC,OAAO,CAAC,CAAC;QAErC,sBAAsB;QACtB,MAAM,OAAO,GAAG,IAAA,YAAI,EAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;QAErC,IAAI,OAAO,EAAE,CAAC;YACZ,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;YAC1C,OAAO;gBACL,KAAK,EAAE,IAAI;gBACX,OAAO;gBACP,WAAW,EAAE,UAAU;gBACvB,OAAO,EAAE,KAAK;aACf,CAAC;QACJ,CAAC;QAED,wBAAwB;QACxB,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC;IAChE,CAAC;IAED,UAAU;IACV,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;IAC1C,OAAO;QACL,KAAK,EAAE,KAAK;QACZ,OAAO,EAAE,SAAS;QAClB,WAAW,EAAE,UAAU;QACvB,OAAO,EAAE,IAAI;KACd,CAAC;AACJ,CAAC"}
+{"version":3,"file":"wait.js","sourceRoot":"","sources":["../src/wait.ts"],"names":[],"mappings":";AAAA;;GAEG;;AAoBH,0BAmDC;AAnED,yCAAsC;AACtC,mCAA+B;AAE/B;;;;;;;;;;;;GAYG;AACI,KAAK,UAAU,OAAO,CAC3B,OAAyB,EACzB,QAAuB,EACvB,UAAkB,KAAK,EACvB,QAAiB,EACjB,MAAgB;IAEhB,kDAAkD;IAClD,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,yBAAyB;QACzB,MAAM,UAAU,GAAG,MAAM,KAAK,SAAS;YACrC,CAAC,CAAC,MAAM;YACR,CAAC,CAAC,CAAC,OAAO,CAAC,SAAS,EAAE,KAAK,SAAS,CAAC,CAAC;QACxC,IAAI,UAAU,EAAE,CAAC;YACf,QAAQ,GAAG,IAAI,CAAC,CAAC,kDAAkD;QACrE,CAAC;aAAM,CAAC;YACN,QAAQ,GAAG,GAAG,CAAC,CAAC,8CAA8C;QAChE,CAAC;IACH,CAAC;IAED,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAE7B,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,GAAG,OAAO,EAAE,CAAC;QACxC,uDAAuD;QACvD,MAAM,IAAI,GAAG,MAAM,IAAA,mBAAQ,EAAC,OAAO,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;QAE1D,sBAAsB;QACtB,MAAM,OAAO,GAAG,IAAA,YAAI,EAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;QAErC,IAAI,OAAO,EAAE,CAAC;YACZ,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;YAC1C,OAAO;gBACL,KAAK,EAAE,IAAI;gBACX,OAAO;gBACP,WAAW,EAAE,UAAU;gBACvB,OAAO,EAAE,KAAK;aACf,CAAC;QACJ,CAAC;QAED,wBAAwB;QACxB,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC;IAChE,CAAC;IAED,UAAU;IACV,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;IAC1C,OAAO;QACL,KAAK,EAAE,KAAK;QACZ,OAAO,EAAE,SAAS;QAClB,WAAW,EAAE,UAAU;QACvB,OAAO,EAAE,IAAI;KACd,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sentience-ts",
-  "version": "0.10.3",
+  "version": "0.10.5",
   "description": "TypeScript SDK for Sentience AI Agent Browser Automation",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",