phase 2B completed

Author: rcholic

sentience/_extension_loader.py

@@ -38,4 +38,3 @@ def find_extension_path() -> Path:
             f"2. {dev_ext_path}\n"
             "Make sure the extension is built and 'sentience/extension' directory exists."
         )
-

sentience/async_api.py

@@ -21,38 +21,41 @@
     from sentience.actions import click_async
 """
 
+# ========== Actions (Phase 1) ==========
+# Re-export async action functions from actions.py
+from sentience.actions import click_async, click_rect_async, press_async, type_text_async
+
 # ========== Browser ==========
 # Re-export AsyncSentienceBrowser from browser.py (moved there for better organization)
 from sentience.browser import AsyncSentienceBrowser
 
-# ========== Snapshot (Phase 1) ==========
-# Re-export async snapshot functions from snapshot.py
-from sentience.snapshot import snapshot_async
+# Re-export async expect functions from expect.py
+from sentience.expect import ExpectationAsync, expect_async
 
-# ========== Actions (Phase 1) ==========
-# Re-export async action functions from actions.py
-from sentience.actions import (
-    click_async,
-    type_text_async,
-    press_async,
-    click_rect_async,
-)
+# Re-export async overlay functions from overlay.py
+from sentience.overlay import clear_overlay_async, show_overlay_async
 
-# ========== Phase 2A: Core Utilities ==========
-# Re-export async wait function from wait.py
-from sentience.wait import wait_for_async
+# ========== Query Functions (Pure Functions - No Async Needed) ==========
+# Re-export query functions (pure functions, no async needed)
+from sentience.query import find, query
+
+# ========== Phase 2B: Supporting Utilities ==========
+# Re-export async read function from read.py
+from sentience.read import read_async
 
 # Re-export async screenshot function from screenshot.py
 from sentience.screenshot import screenshot_async
 
+# ========== Snapshot (Phase 1) ==========
+# Re-export async snapshot functions from snapshot.py
+from sentience.snapshot import snapshot_async
+
 # Re-export async text search function from text_search.py
 from sentience.text_search import find_text_rect_async
 
-# ========== Phase 2B: Supporting Utilities (Future) ==========
-# TODO: Re-export when implemented
-# from sentience.read import read_async
-# from sentience.overlay import show_overlay_async, clear_overlay_async
-# from sentience.expect import expect_async, ExpectationAsync
+# ========== Phase 2A: Core Utilities ==========
+# Re-export async wait function from wait.py
+from sentience.wait import wait_for_async
 
 # ========== Phase 2C: Agent Layer (Future) ==========
 # TODO: Re-export when implemented
@@ -64,9 +67,6 @@
 # from sentience.recorder import RecorderAsync
 # from sentience.inspector import InspectorAsync
 
-# ========== Query Functions (Pure Functions - No Async Needed) ==========
-# Re-export query functions (pure functions, no async needed)
-from sentience.query import find, query
 
 __all__ = [
     # Browser
@@ -82,12 +82,12 @@
     "wait_for_async",  # Re-exported from wait.py
     "screenshot_async",  # Re-exported from screenshot.py
     "find_text_rect_async",  # Re-exported from text_search.py
-    # Phase 2B: Supporting Utilities (Future - uncomment when implemented)
-    # "read_async",
-    # "show_overlay_async",
-    # "clear_overlay_async",
-    # "expect_async",
-    # "ExpectationAsync",
+    # Phase 2B: Supporting Utilities
+    "read_async",  # Re-exported from read.py
+    "show_overlay_async",  # Re-exported from overlay.py
+    "clear_overlay_async",  # Re-exported from overlay.py
+    "expect_async",  # Re-exported from expect.py
+    "ExpectationAsync",  # Re-exported from expect.py
     # Phase 2C: Agent Layer (Future - uncomment when implemented)
     # "SentienceAgentAsync",
     # "BaseAgentAsync",

sentience/browser.py

@@ -10,7 +10,10 @@
 from pathlib import Path
 from urllib.parse import urlparse
 
-from playwright.async_api import BrowserContext as AsyncBrowserContext, Page as AsyncPage, Playwright as AsyncPlaywright, async_playwright
+from playwright.async_api import BrowserContext as AsyncBrowserContext
+from playwright.async_api import Page as AsyncPage
+from playwright.async_api import Playwright as AsyncPlaywright
+from playwright.async_api import async_playwright
 from playwright.sync_api import BrowserContext, Page, Playwright, sync_playwright
 
 from sentience._extension_loader import find_extension_path

sentience/expect.py

@@ -2,12 +2,13 @@
 Expect/Assert functionality
 """
 
+import asyncio
 import time
 
-from .browser import SentienceBrowser
+from .browser import AsyncSentienceBrowser, SentienceBrowser
 from .models import Element
 from .query import query
-from .wait import wait_for
+from .wait import wait_for, wait_for_async
 
 
 class Expectation:
@@ -90,3 +91,98 @@ def expect(browser: SentienceBrowser, selector: str | dict) -> Expectation:
         Expectation helper
     """
     return Expectation(browser, selector)
+
+
+class ExpectationAsync:
+    """Assertion helper for element expectations (async)"""
+
+    def __init__(self, browser: AsyncSentienceBrowser, selector: str | dict):
+        self.browser = browser
+        self.selector = selector
+
+    async def to_be_visible(self, timeout: float = 10.0) -> Element:
+        """Assert element is visible (exists and in viewport)"""
+        result = await wait_for_async(self.browser, self.selector, timeout=timeout)
+
+        if not result.found:
+            raise AssertionError(f"Element not found: {self.selector} (timeout: {timeout}s)")
+
+        element = result.element
+        if not element.in_viewport:
+            raise AssertionError(f"Element found but not visible in viewport: {self.selector}")
+
+        return element
+
+    async def to_exist(self, timeout: float = 10.0) -> Element:
+        """Assert element exists"""
+        result = await wait_for_async(self.browser, self.selector, timeout=timeout)
+
+        if not result.found:
+            raise AssertionError(f"Element does not exist: {self.selector} (timeout: {timeout}s)")
+
+        return result.element
+
+    async def to_have_text(self, expected_text: str, timeout: float = 10.0) -> Element:
+        """Assert element has specific text"""
+        result = await wait_for_async(self.browser, self.selector, timeout=timeout)
+
+        if not result.found:
+            raise AssertionError(f"Element not found: {self.selector} (timeout: {timeout}s)")
+
+        element = result.element
+        if not element.text or expected_text not in element.text:
+            raise AssertionError(
+                f"Element text mismatch. Expected '{expected_text}', got '{element.text}'"
+            )
+
+        return element
+
+    async def to_have_count(self, expected_count: int, timeout: float = 10.0) -> None:
+        """Assert selector matches exactly N elements"""
+        from .snapshot import snapshot_async
+
+        start_time = time.time()
+        while time.time() - start_time < timeout:
+            snap = await snapshot_async(self.browser)
+            matches = query(snap, self.selector)
+
+            if len(matches) == expected_count:
+                return
+
+            await asyncio.sleep(0.25)
+
+        # Final check
+        snap = await snapshot_async(self.browser)
+        matches = query(snap, self.selector)
+        actual_count = len(matches)
+
+        raise AssertionError(
+            f"Element count mismatch. Expected {expected_count}, got {actual_count}"
+        )
+
+
+def expect_async(browser: AsyncSentienceBrowser, selector: str | dict) -> ExpectationAsync:
+    """
+    Create expectation helper for assertions (async)
+
+    Args:
+        browser: AsyncSentienceBrowser instance
+        selector: String DSL or dict query
+
+    Returns:
+        ExpectationAsync helper
+
+    Example:
+        # Assert element is visible
+        element = await expect_async(browser, "role=button").to_be_visible()
+
+        # Assert element has text
+        element = await expect_async(browser, "h1").to_have_text("Welcome")
+
+        # Assert element exists
+        element = await expect_async(browser, "role=link").to_exist()
+
+        # Assert count
+        await expect_async(browser, "role=button").to_have_count(5)
+    """
+    return ExpectationAsync(browser, selector)

sentience/overlay.py

@@ -4,7 +4,7 @@
 
 from typing import Any
 
-from .browser import SentienceBrowser
+from .browser import AsyncSentienceBrowser, SentienceBrowser
 from .models import Element, Snapshot
 
 
@@ -113,3 +113,110 @@ def clear_overlay(browser: SentienceBrowser) -> None:
         }
         """
     )
+
+
+async def show_overlay_async(
+    browser: AsyncSentienceBrowser,
+    elements: list[Element] | list[dict[str, Any]] | Snapshot,
+    target_element_id: int | None = None,
+) -> None:
+    """
+    Display visual overlay highlighting elements in the browser (async)
+
+    This function shows a Shadow DOM overlay with color-coded borders around
+    detected elements. Useful for debugging, learning, and validating element detection.
+
+    Args:
+        browser: AsyncSentienceBrowser instance
+        elements: Can be:
+            - List of Element objects (from snapshot.elements)
+            - List of raw element dicts (from snapshot result or API response)
+            - Snapshot object (will use snapshot.elements)
+        target_element_id: Optional ID of element to highlight in red (default: None)
+
+    Color Coding:
+        - Red: Target element (when target_element_id is specified)
+        - Blue: Primary elements (is_primary=true)
+        - Green: Regular interactive elements
+
+    Visual Indicators:
+        - Border thickness and opacity scale with importance score
+        - Semi-transparent fill for better visibility
+        - Importance badges showing scores
+        - Star icon for primary elements
+        - Target emoji for the target element
+
+    Auto-clear: Overlay automatically disappears after 5 seconds
+
+    Example:
+        # Show overlay from snapshot
+        snap = await snapshot_async(browser)
+        await show_overlay_async(browser, snap)
+
+        # Show overlay with custom elements
+        elements = [{"id": 1, "bbox": {"x": 100, "y": 100, "width": 200, "height": 50}, ...}]
+        await show_overlay_async(browser, elements)
+
+        # Show overlay with target element highlighted in red
+        await show_overlay_async(browser, snap, target_element_id=42)
+
+        # Clear overlay manually before 5 seconds
+        await clear_overlay_async(browser)
+    """
+    if not browser.page:
+        raise RuntimeError("Browser not started. Call await browser.start() first.")
+
+    # Handle different input types
+    if isinstance(elements, Snapshot):
+        # Extract elements from Snapshot object
+        elements_list = [el.model_dump() for el in elements.elements]
+    elif isinstance(elements, list) and len(elements) > 0:
+        # Check if it's a list of Element objects or dicts
+        if hasattr(elements[0], "model_dump"):
+            # List of Element objects
+            elements_list = [el.model_dump() for el in elements]
+        else:
+            # Already a list of dicts
+            elements_list = elements
+    else:
+        raise ValueError("elements must be a Snapshot, list of Element objects, or list of dicts")
+
+    # Call extension API
+    await browser.page.evaluate(
+        """
+        (args) => {
+            if (window.sentience && window.sentience.showOverlay) {
+                window.sentience.showOverlay(args.elements, args.targetId);
+            } else {
+                console.warn('[Sentience SDK] showOverlay not available - is extension loaded?');
+            }
+        }
+        """,
+        {"elements": elements_list, "targetId": target_element_id},
+    )
+
+
+async def clear_overlay_async(browser: AsyncSentienceBrowser) -> None:
+    """
+    Clear the visual overlay manually (before 5-second auto-clear) (async)
+
+    Args:
+        browser: AsyncSentienceBrowser instance
+
+    Example:
+        await show_overlay_async(browser, snap)
+        # ... inspect overlay ...
+        await clear_overlay_async(browser)  # Remove immediately
+    """
+    if not browser.page:
+        raise RuntimeError("Browser not started. Call await browser.start() first.")
+
+    await browser.page.evaluate(
+        """
+        () => {
+            if (window.sentience && window.sentience.clearOverlay) {
+                window.sentience.clearOverlay();
+            }
+        }
+        """
+    )