sentienceapi 0.95.0__py3-none-any.whl

sentience/expect.py

@@ -0,0 +1,188 @@
+"""
+Expect/Assert functionality
+"""
+
+import asyncio
+import time
+
+from .browser import AsyncSentienceBrowser, SentienceBrowser
+from .models import Element
+from .query import query
+from .wait import wait_for, wait_for_async
+
+
+class Expectation:
+    """Assertion helper for element expectations"""
+
+    def __init__(self, browser: SentienceBrowser, selector: str | dict):
+        self.browser = browser
+        self.selector = selector
+
+    def to_be_visible(self, timeout: float = 10.0) -> Element:
+        """Assert element is visible (exists and in viewport)"""
+        result = wait_for(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
+
+    def to_exist(self, timeout: float = 10.0) -> Element:
+        """Assert element exists"""
+        result = wait_for(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
+
+    def to_have_text(self, expected_text: str, timeout: float = 10.0) -> Element:
+        """Assert element has specific text"""
+        result = wait_for(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
+
+    def to_have_count(self, expected_count: int, timeout: float = 10.0) -> None:
+        """Assert selector matches exactly N elements"""
+        from .snapshot import snapshot
+
+        start_time = time.time()
+        while time.time() - start_time < timeout:
+            snap = snapshot(self.browser)
+            matches = query(snap, self.selector)
+
+            if len(matches) == expected_count:
+                return
+
+            time.sleep(0.25)
+
+        # Final check
+        snap = snapshot(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(browser: SentienceBrowser, selector: str | dict) -> Expectation:
+    """
+    Create expectation helper for assertions
+
+    Args:
+        browser: SentienceBrowser instance
+        selector: String DSL or dict query
+
+    Returns:
+        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/extension/background.js

@@ -0,0 +1,104 @@
+import init, { analyze_page_with_options, analyze_page, prune_for_api } from "../pkg/sentience_core.js";
+
+let wasmReady = !1, wasmInitPromise = null;
+
+async function initWASM() {
+    if (!wasmReady) return wasmInitPromise || (wasmInitPromise = (async () => {
+        try {
+            globalThis.js_click_element = () => {}, await init(), wasmReady = !0;
+        } catch (error) {
+            throw error;
+        }
+    })(), wasmInitPromise);
+}
+
+async function handleScreenshotCapture(_tabId, options = {}) {
+    try {
+        const {format: format = "png", quality: quality = 90} = options;
+        return await chrome.tabs.captureVisibleTab(null, {
+            format: format,
+            quality: quality
+        });
+    } catch (error) {
+        throw new Error(`Failed to capture screenshot: ${error.message}`);
+    }
+}
+
+async function handleSnapshotProcessing(rawData, options = {}) {
+    const startTime = performance.now();
+    try {
+        if (!Array.isArray(rawData)) throw new Error("rawData must be an array");
+        if (rawData.length > 1e4 && (rawData = rawData.slice(0, 1e4)), await initWASM(), 
+        !wasmReady) throw new Error("WASM module not initialized");
+        let analyzedElements, prunedRawData;
+        try {
+            const wasmPromise = new Promise((resolve, reject) => {
+                try {
+                    let result;
+                    result = options.limit || options.filter ? analyze_page_with_options(rawData, options) : analyze_page(rawData), 
+                    resolve(result);
+                } catch (e) {
+                    reject(e);
+                }
+            });
+            analyzedElements = await Promise.race([ wasmPromise, new Promise((_, reject) => setTimeout(() => reject(new Error("WASM processing timeout (>18s)")), 18e3)) ]);
+        } catch (e) {
+            const errorMsg = e.message || "Unknown WASM error";
+            throw new Error(`WASM analyze_page failed: ${errorMsg}`);
+        }
+        try {
+            prunedRawData = prune_for_api(rawData);
+        } catch (e) {
+            prunedRawData = rawData;
+        }
+        performance.now();
+        return {
+            elements: analyzedElements,
+            raw_elements: prunedRawData
+        };
+    } catch (error) {
+        performance.now();
+        throw error;
+    }
+}
+
+initWASM().catch(err => {}), chrome.runtime.onMessage.addListener((request, sender, sendResponse) => {
+    try {
+        return "captureScreenshot" === request.action ? (handleScreenshotCapture(sender.tab.id, request.options).then(screenshot => {
+            sendResponse({
+                success: !0,
+                screenshot: screenshot
+            });
+        }).catch(error => {
+            sendResponse({
+                success: !1,
+                error: error.message || "Screenshot capture failed"
+            });
+        }), !0) : "processSnapshot" === request.action ? (handleSnapshotProcessing(request.rawData, request.options).then(result => {
+            sendResponse({
+                success: !0,
+                result: result
+            });
+        }).catch(error => {
+            sendResponse({
+                success: !1,
+                error: error.message || "Snapshot processing failed"
+            });
+        }), !0) : (sendResponse({
+            success: !1,
+            error: "Unknown action"
+        }), !1);
+    } catch (error) {
+        try {
+            sendResponse({
+                success: !1,
+                error: `Fatal error: ${error.message || "Unknown error"}`
+            });
+        } catch (e) {}
+        return !1;
+    }
+}), self.addEventListener("error", event => {
+    event.preventDefault();
+}), self.addEventListener("unhandledrejection", event => {
+    event.preventDefault();
+});

sentience/extension/content.js

@@ -0,0 +1,161 @@
+!function() {
+    "use strict";
+    window, window.top;
+    document.documentElement.dataset.sentienceExtensionId = chrome.runtime.id, window.addEventListener("message", event => {
+        var data;
+        if (event.source === window) switch (event.data.type) {
+          case "SENTIENCE_SCREENSHOT_REQUEST":
+            data = event.data, chrome.runtime.sendMessage({
+                action: "captureScreenshot",
+                options: data.options
+            }, response => {
+                window.postMessage({
+                    type: "SENTIENCE_SCREENSHOT_RESULT",
+                    requestId: data.requestId,
+                    screenshot: response?.success ? response.screenshot : null,
+                    error: response?.error
+                }, "*");
+            });
+            break;
+
+          case "SENTIENCE_SNAPSHOT_REQUEST":
+            !function(data) {
+                const startTime = performance.now();
+                let responded = !1;
+                const timeoutId = setTimeout(() => {
+                    if (!responded) {
+                        responded = !0;
+                        const duration = performance.now() - startTime;
+                        window.postMessage({
+                            type: "SENTIENCE_SNAPSHOT_RESULT",
+                            requestId: data.requestId,
+                            error: "WASM processing timeout - background script may be unresponsive",
+                            duration: duration
+                        }, "*");
+                    }
+                }, 2e4);
+                try {
+                    chrome.runtime.sendMessage({
+                        action: "processSnapshot",
+                        rawData: data.rawData,
+                        options: data.options
+                    }, response => {
+                        if (responded) return;
+                        responded = !0, clearTimeout(timeoutId);
+                        const duration = performance.now() - startTime;
+                        chrome.runtime.lastError ? window.postMessage({
+                            type: "SENTIENCE_SNAPSHOT_RESULT",
+                            requestId: data.requestId,
+                            error: `Chrome runtime error: ${chrome.runtime.lastError.message}`,
+                            duration: duration
+                        }, "*") : response?.success ? window.postMessage({
+                            type: "SENTIENCE_SNAPSHOT_RESULT",
+                            requestId: data.requestId,
+                            elements: response.result.elements,
+                            raw_elements: response.result.raw_elements,
+                            duration: duration
+                        }, "*") : window.postMessage({
+                            type: "SENTIENCE_SNAPSHOT_RESULT",
+                            requestId: data.requestId,
+                            error: response?.error || "Processing failed",
+                            duration: duration
+                        }, "*");
+                    });
+                } catch (error) {
+                    if (!responded) {
+                        responded = !0, clearTimeout(timeoutId);
+                        const duration = performance.now() - startTime;
+                        window.postMessage({
+                            type: "SENTIENCE_SNAPSHOT_RESULT",
+                            requestId: data.requestId,
+                            error: `Failed to send message: ${error.message}`,
+                            duration: duration
+                        }, "*");
+                    }
+                }
+            }(event.data);
+            break;
+
+          case "SENTIENCE_SHOW_OVERLAY":
+            !function(data) {
+                const {elements: elements, targetElementId: targetElementId} = data;
+                if (!elements || !Array.isArray(elements)) return;
+                removeOverlay();
+                const host = document.createElement("div");
+                host.id = OVERLAY_HOST_ID, host.style.cssText = "\n        position: fixed !important;\n        top: 0 !important;\n        left: 0 !important;\n        width: 100vw !important;\n        height: 100vh !important;\n        pointer-events: none !important;\n        z-index: 2147483647 !important;\n        margin: 0 !important;\n        padding: 0 !important;\n    ", 
+                document.body.appendChild(host);
+                const shadow = host.attachShadow({
+                    mode: "closed"
+                }), maxImportance = Math.max(...elements.map(e => e.importance || 0), 1);
+                elements.forEach(element => {
+                    const bbox = element.bbox;
+                    if (!bbox) return;
+                    const isTarget = element.id === targetElementId, isPrimary = element.visual_cues?.is_primary || !1, importance = element.importance || 0;
+                    let color;
+                    color = isTarget ? "#FF0000" : isPrimary ? "#0066FF" : "#00FF00";
+                    const importanceRatio = maxImportance > 0 ? importance / maxImportance : .5, borderOpacity = isTarget ? 1 : isPrimary ? .9 : Math.max(.4, .5 + .5 * importanceRatio), fillOpacity = .2 * borderOpacity, borderWidth = isTarget ? 2 : isPrimary ? 1.5 : Math.max(.5, Math.round(2 * importanceRatio)), hexOpacity = Math.round(255 * fillOpacity).toString(16).padStart(2, "0"), box = document.createElement("div");
+                    if (box.style.cssText = `\n            position: absolute;\n            left: ${bbox.x}px;\n            top: ${bbox.y}px;\n            width: ${bbox.width}px;\n            height: ${bbox.height}px;\n            border: ${borderWidth}px solid ${color};\n            background-color: ${color}${hexOpacity};\n            box-sizing: border-box;\n            opacity: ${borderOpacity};\n            pointer-events: none;\n        `, 
+                    importance > 0 || isPrimary) {
+                        const badge = document.createElement("span");
+                        badge.textContent = isPrimary ? `⭐${importance}` : `${importance}`, badge.style.cssText = `\n                position: absolute;\n                top: -18px;\n                left: 0;\n                background: ${color};\n                color: white;\n                font-size: 11px;\n                font-weight: bold;\n                padding: 2px 6px;\n                font-family: Arial, sans-serif;\n                border-radius: 3px;\n                opacity: 0.95;\n                white-space: nowrap;\n                pointer-events: none;\n            `, 
+                        box.appendChild(badge);
+                    }
+                    if (isTarget) {
+                        const targetIndicator = document.createElement("span");
+                        targetIndicator.textContent = "🎯", targetIndicator.style.cssText = "\n                position: absolute;\n                top: -18px;\n                right: 0;\n                font-size: 16px;\n                pointer-events: none;\n            ", 
+                        box.appendChild(targetIndicator);
+                    }
+                    shadow.appendChild(box);
+                }), overlayTimeout = setTimeout(() => {
+                    removeOverlay();
+                }, 5e3);
+            }(event.data);
+            break;
+
+          case "SENTIENCE_CLEAR_OVERLAY":
+            removeOverlay();
+            break;
+
+          case "SENTIENCE_SHOW_GRID_OVERLAY":
+            !function(data) {
+                const {grids: grids, targetGridId: targetGridId} = data;
+                if (!grids || !Array.isArray(grids)) return;
+                removeOverlay();
+                const host = document.createElement("div");
+                host.id = OVERLAY_HOST_ID, host.style.cssText = "\n        position: fixed !important;\n        top: 0 !important;\n        left: 0 !important;\n        width: 100vw !important;\n        height: 100vh !important;\n        pointer-events: none !important;\n        z-index: 2147483647 !important;\n        margin: 0 !important;\n        padding: 0 !important;\n    ", 
+                document.body.appendChild(host);
+                const shadow = host.attachShadow({
+                    mode: "closed"
+                });
+                grids.forEach(grid => {
+                    const bbox = grid.bbox;
+                    if (!bbox) return;
+                    const isTarget = grid.grid_id === targetGridId, isDominant = !0 === grid.is_dominant;
+                    let color = "#9B59B6";
+                    isTarget ? color = "#FF0000" : isDominant && (color = "#FF8C00");
+                    const borderStyle = isTarget ? "solid" : "dashed", borderWidth = isTarget ? 3 : isDominant ? 2.5 : 2, opacity = isTarget ? 1 : isDominant ? .9 : .8, fillOpacity = .1 * opacity, hexOpacity = Math.round(255 * fillOpacity).toString(16).padStart(2, "0"), box = document.createElement("div");
+                    box.style.cssText = `\n            position: absolute;\n            left: ${bbox.x}px;\n            top: ${bbox.y}px;\n            width: ${bbox.width}px;\n            height: ${bbox.height}px;\n            border: ${borderWidth}px ${borderStyle} ${color};\n            background-color: ${color}${hexOpacity};\n            box-sizing: border-box;\n            opacity: ${opacity};\n            pointer-events: none;\n        `;
+                    let labelText = grid.label ? `Grid ${grid.grid_id}: ${grid.label}` : `Grid ${grid.grid_id}`;
+                    grid.is_dominant && (labelText = `⭐ ${labelText} (dominant)`);
+                    const badge = document.createElement("span");
+                    if (badge.textContent = labelText, badge.style.cssText = `\n                position: absolute;\n                top: -18px;\n                left: 0;\n                background: ${color};\n                color: white;\n                font-size: 11px;\n                font-weight: bold;\n                padding: 2px 6px;\n                font-family: Arial, sans-serif;\n                border-radius: 3px;\n                opacity: 0.95;\n                white-space: nowrap;\n                pointer-events: none;\n            `, 
+                    box.appendChild(badge), isTarget) {
+                        const targetIndicator = document.createElement("span");
+                        targetIndicator.textContent = "🎯", targetIndicator.style.cssText = "\n                position: absolute;\n                top: -18px;\n                right: 0;\n                font-size: 16px;\n                pointer-events: none;\n            ", 
+                        box.appendChild(targetIndicator);
+                    }
+                    shadow.appendChild(box);
+                }), overlayTimeout = setTimeout(() => {
+                    removeOverlay();
+                }, 5e3);
+            }(event.data);
+        }
+    });
+    const OVERLAY_HOST_ID = "sentience-overlay-host";
+    let overlayTimeout = null;
+    function removeOverlay() {
+        const existing = document.getElementById(OVERLAY_HOST_ID);
+        existing && existing.remove(), overlayTimeout && (clearTimeout(overlayTimeout), 
+        overlayTimeout = null);
+    }
+}();