@predicatelabs/sdk 0.99.9

package/dist/asserts/index.js

@@ -0,0 +1,70 @@
+"use strict";
+/**
+ * Assertion DSL for Sentience SDK.
+ *
+ * This module provides a Playwright/Cypress-like assertion API for verifying
+ * browser state in agent verification loops.
+ *
+ * Main exports:
+ * - E: Element query builder (filters elements by role, text, href, etc.)
+ * - expect: Expectation builder (creates predicates from queries)
+ * - inDominantList: Query over dominant group elements (ordinal access)
+ *
+ * @example
+ * ```typescript
+ * import { E, expect, inDominantList } from '@anthropic/sentience-ts/asserts';
+ *
+ * // Basic presence assertions
+ * await runtime.assert(
+ *   expect(E({ role: "button", textContains: "Save" })).toExist(),
+ *   "save_button_visible"
+ * );
+ *
+ * // Visibility assertions
+ * await runtime.assert(
+ *   expect(E({ textContains: "Checkout" })).toBeVisible(),
+ *   "checkout_visible"
+ * );
+ *
+ * // Global text assertions
+ * await runtime.assert(
+ *   expect.textPresent("Welcome back"),
+ *   "user_logged_in"
+ * );
+ * await runtime.assert(
+ *   expect.noText("Error"),
+ *   "no_error_message"
+ * );
+ *
+ * // Ordinal assertions on dominant group
+ * await runtime.assert(
+ *   expect(inDominantList().nth(0)).toHaveTextContains("Show HN"),
+ *   "first_item_is_show_hn"
+ * );
+ *
+ * // Task completion
+ * await runtime.assertDone(
+ *   expect.textPresent("Order confirmed"),
+ *   "checkout_complete"
+ * );
+ * ```
+ *
+ * The DSL compiles to existing Predicate functions, so it works seamlessly
+ * with AgentRuntime.assert() and assertDone().
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withEventually = exports.EventuallyWrapper = exports.ExpectBuilder = exports.expect = exports.inDominantList = exports.MultiQuery = exports.ListQuery = exports.ElementQuery = exports.E = void 0;
+// Query builders
+var query_1 = require("./query");
+Object.defineProperty(exports, "E", { enumerable: true, get: function () { return query_1.E; } });
+Object.defineProperty(exports, "ElementQuery", { enumerable: true, get: function () { return query_1.ElementQuery; } });
+Object.defineProperty(exports, "ListQuery", { enumerable: true, get: function () { return query_1.ListQuery; } });
+Object.defineProperty(exports, "MultiQuery", { enumerable: true, get: function () { return query_1.MultiQuery; } });
+Object.defineProperty(exports, "inDominantList", { enumerable: true, get: function () { return query_1.inDominantList; } });
+// Expectation builders
+var expect_1 = require("./expect");
+Object.defineProperty(exports, "expect", { enumerable: true, get: function () { return expect_1.expect; } });
+Object.defineProperty(exports, "ExpectBuilder", { enumerable: true, get: function () { return expect_1.ExpectBuilder; } });
+Object.defineProperty(exports, "EventuallyWrapper", { enumerable: true, get: function () { return expect_1.EventuallyWrapper; } });
+Object.defineProperty(exports, "withEventually", { enumerable: true, get: function () { return expect_1.withEventually; } });
+//# sourceMappingURL=index.js.map

package/dist/asserts/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/asserts/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;;;AAEH,iBAAiB;AACjB,iCAAiF;AAAxE,0FAAA,CAAC,OAAA;AAAE,qGAAA,YAAY,OAAA;AAAE,kGAAA,SAAS,OAAA;AAAE,mGAAA,UAAU,OAAA;AAAE,uGAAA,cAAc,OAAA;AAG/D,uBAAuB;AACvB,mCAAoF;AAA3E,gGAAA,MAAM,OAAA;AAAE,uGAAA,aAAa,OAAA;AAAE,2GAAA,iBAAiB,OAAA;AAAE,wGAAA,cAAc,OAAA"}

package/dist/asserts/query.d.ts

@@ -0,0 +1,199 @@
+/**
+ * Element query builders for assertion DSL.
+ *
+ * This module provides the E() query builder and dominant-group list operations
+ * for creating element queries that compile to existing Predicates.
+ *
+ * Key classes:
+ * - ElementQuery: Pure data object for filtering elements (E())
+ * - ListQuery: Query over dominant-group elements (inDominantList())
+ * - MultiQuery: Represents multiple elements from ListQuery.top(n)
+ *
+ * All queries work with existing Snapshot fields only:
+ *     id, role, text, bbox, doc_y, group_key, group_index,
+ *     dominant_group_key, in_viewport, is_occluded, href
+ */
+import { Element, Snapshot } from '../types';
+/**
+ * Options for creating an ElementQuery via E().
+ */
+export interface EOptions {
+    /** ARIA role to match (e.g., "button", "textbox", "link") */
+    role?: string;
+    /** Text to match exactly (alias for text, best-effort) */
+    name?: string;
+    /** Exact text match */
+    text?: string;
+    /** Substring match against text (case-insensitive) */
+    textContains?: string;
+    /** Substring match against href (case-insensitive) */
+    hrefContains?: string;
+    /** Filter by viewport visibility */
+    inViewport?: boolean;
+    /** Filter by occlusion state */
+    occluded?: boolean;
+    /** Exact match against group_key */
+    group?: string;
+    /** True = must be in dominant group */
+    inDominantGroup?: boolean;
+}
+/**
+ * Pure query object for filtering elements.
+ *
+ * This is the data representation of an E() call. It does not execute
+ * anything - it just stores the filter criteria.
+ *
+ * @example
+ * E({ role: "button", textContains: "Save" })
+ * E({ role: "link", hrefContains: "/cart" })
+ * E({ inViewport: true, occluded: false })
+ */
+export declare class ElementQuery {
+    role?: string;
+    name?: string;
+    text?: string;
+    textContains?: string;
+    hrefContains?: string;
+    inViewport?: boolean;
+    occluded?: boolean;
+    group?: string;
+    inDominantGroup?: boolean;
+    _groupIndex?: number;
+    _fromDominantList: boolean;
+    constructor(options?: EOptions);
+    /**
+     * Check if element matches this query criteria.
+     *
+     * @param element - Element to check
+     * @param snapshot - Snapshot (needed for dominant_group_key comparison)
+     * @returns True if element matches all criteria
+     */
+    matches(element: Element, snapshot?: Snapshot | null): boolean;
+    /**
+     * Find all elements matching this query in the snapshot.
+     *
+     * @param snapshot - Snapshot to search
+     * @returns Array of matching elements, sorted by doc_y (top to bottom)
+     */
+    findAll(snapshot: Snapshot): Element[];
+    /**
+     * Find first matching element.
+     *
+     * @param snapshot - Snapshot to search
+     * @returns First matching element or null
+     */
+    findFirst(snapshot: Snapshot): Element | null;
+}
+/**
+ * Interface for the E function with static convenience methods.
+ */
+interface EFunction {
+    (options?: EOptions): ElementQuery;
+    /** Query for submit-like buttons */
+    submit: () => ElementQuery;
+    /** Query for search input boxes */
+    searchBox: () => ElementQuery;
+    /** Query for links with optional text filter */
+    link: (options?: {
+        textContains?: string;
+    }) => ElementQuery;
+}
+/**
+ * Create an element query.
+ *
+ * This is the main entry point for building element queries.
+ * It returns a pure data object that can be used with expect().
+ *
+ * @param options - Query filter options
+ * @returns ElementQuery object
+ *
+ * @example
+ * E({ role: "button", textContains: "Save" })
+ * E({ role: "link", hrefContains: "/checkout" })
+ * E({ inViewport: true, occluded: false })
+ */
+export declare const E: EFunction;
+/**
+ * Internal predicate for MultiQuery text checks.
+ * Used by expect() to evaluate multi-element text assertions.
+ */
+export interface MultiTextPredicate {
+    multiQuery: MultiQuery;
+    text: string;
+    checkType: 'any_contains';
+}
+/**
+ * Represents multiple elements from a dominant list query.
+ *
+ * Created by ListQuery.top(n) to represent the first n elements
+ * in a dominant group.
+ *
+ * @example
+ * inDominantList().top(5) // First 5 items in dominant group
+ */
+export declare class MultiQuery {
+    limit: number;
+    _parentListQuery?: ListQuery;
+    constructor(limit: number, parentListQuery?: ListQuery);
+    /**
+     * Create a predicate that checks if any element's text contains the substring.
+     *
+     * @param text - Substring to search for
+     * @returns Predicate that can be used with expect()
+     */
+    anyTextContains(text: string): MultiTextPredicate;
+}
+/**
+ * Query over elements in the dominant group.
+ *
+ * Provides ordinal access to dominant-group elements via .nth(k)
+ * and range access via .top(n).
+ *
+ * Created by inDominantList().
+ *
+ * @example
+ * inDominantList().nth(0)   // First item in dominant group
+ * inDominantList().top(5)   // First 5 items
+ */
+export declare class ListQuery {
+    /**
+     * Select element at specific index in the dominant group.
+     *
+     * @param index - 0-based index in the dominant group
+     * @returns ElementQuery targeting the element at that position
+     *
+     * @example
+     * inDominantList().nth(0)  // First item
+     * inDominantList().nth(2)  // Third item
+     */
+    nth(index: number): ElementQuery;
+    /**
+     * Select the first n elements in the dominant group.
+     *
+     * @param n - Number of elements to select
+     * @returns MultiQuery representing the first n elements
+     *
+     * @example
+     * inDominantList().top(5) // First 5 items
+     */
+    top(n: number): MultiQuery;
+}
+/**
+ * Create a query over elements in the dominant group.
+ *
+ * The dominant group is the most common group_key in the snapshot,
+ * typically representing the main content list (search results,
+ * news feed items, product listings, etc.).
+ *
+ * @returns ListQuery for chaining .nth(k) or .top(n)
+ *
+ * @example
+ * inDominantList().nth(0)     // First item in dominant group
+ * inDominantList().top(5)     // First 5 items
+ *
+ * // With expect():
+ * expect(inDominantList().nth(0)).toHaveTextContains("Show HN")
+ */
+export declare function inDominantList(): ListQuery;
+export {};
+//# sourceMappingURL=query.d.ts.map

package/dist/asserts/query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../src/asserts/query.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAE7C;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,6DAA6D;IAC7D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0DAA0D;IAC1D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uBAAuB;IACvB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,sDAAsD;IACtD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,sDAAsD;IACtD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oCAAoC;IACpC,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,gCAAgC;IAChC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,oCAAoC;IACpC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,uCAAuC;IACvC,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED;;;;;;;;;;GAUG;AACH,qBAAa,YAAY;IACvB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,eAAe,CAAC,EAAE,OAAO,CAAC;IAG1B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iBAAiB,EAAE,OAAO,CAAS;gBAEvB,OAAO,GAAE,QAAa;IAYlC;;;;;;OAMG;IACH,OAAO,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,QAAQ,GAAG,IAAI,GAAG,OAAO;IA4F9D;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,EAAE;IAOtC;;;;;OAKG;IACH,SAAS,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,GAAG,IAAI;CAI9C;AAED;;GAEG;AACH,UAAU,SAAS;IACjB,CAAC,OAAO,CAAC,EAAE,QAAQ,GAAG,YAAY,CAAC;IACnC,oCAAoC;IACpC,MAAM,EAAE,MAAM,YAAY,CAAC;IAC3B,mCAAmC;IACnC,SAAS,EAAE,MAAM,YAAY,CAAC;IAC9B,gDAAgD;IAChD,IAAI,EAAE,CAAC,OAAO,CAAC,EAAE;QAAE,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,YAAY,CAAC;CAC7D;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,CAAC,EAAE,SA8Bf,CAAC;AAEF;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,UAAU,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,cAAc,CAAC;CAC3B;AAED;;;;;;;;GAQG;AACH,qBAAa,UAAU;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,gBAAgB,CAAC,EAAE,SAAS,CAAC;gBAEjB,KAAK,EAAE,MAAM,EAAE,eAAe,CAAC,EAAE,SAAS;IAKtD;;;;;OAKG;IACH,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB;CAOlD;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,SAAS;IACpB;;;;;;;;;OASG;IACH,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY;IAOhC;;;;;;;;OAQG;IACH,GAAG,CAAC,CAAC,EAAE,MAAM,GAAG,UAAU;CAG3B;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,cAAc,IAAI,SAAS,CAE1C"}

package/dist/asserts/query.js

@@ -0,0 +1,288 @@
+"use strict";
+/**
+ * Element query builders for assertion DSL.
+ *
+ * This module provides the E() query builder and dominant-group list operations
+ * for creating element queries that compile to existing Predicates.
+ *
+ * Key classes:
+ * - ElementQuery: Pure data object for filtering elements (E())
+ * - ListQuery: Query over dominant-group elements (inDominantList())
+ * - MultiQuery: Represents multiple elements from ListQuery.top(n)
+ *
+ * All queries work with existing Snapshot fields only:
+ *     id, role, text, bbox, doc_y, group_key, group_index,
+ *     dominant_group_key, in_viewport, is_occluded, href
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ListQuery = exports.MultiQuery = exports.E = exports.ElementQuery = void 0;
+exports.inDominantList = inDominantList;
+/**
+ * Pure query object for filtering elements.
+ *
+ * This is the data representation of an E() call. It does not execute
+ * anything - it just stores the filter criteria.
+ *
+ * @example
+ * E({ role: "button", textContains: "Save" })
+ * E({ role: "link", hrefContains: "/cart" })
+ * E({ inViewport: true, occluded: false })
+ */
+class ElementQuery {
+    constructor(options = {}) {
+        this._fromDominantList = false;
+        this.role = options.role;
+        this.name = options.name;
+        this.text = options.text;
+        this.textContains = options.textContains;
+        this.hrefContains = options.hrefContains;
+        this.inViewport = options.inViewport;
+        this.occluded = options.occluded;
+        this.group = options.group;
+        this.inDominantGroup = options.inDominantGroup;
+    }
+    /**
+     * Check if element matches this query criteria.
+     *
+     * @param element - Element to check
+     * @param snapshot - Snapshot (needed for dominant_group_key comparison)
+     * @returns True if element matches all criteria
+     */
+    matches(element, snapshot) {
+        // Role filter
+        if (this.role !== undefined) {
+            if (element.role !== this.role) {
+                return false;
+            }
+        }
+        // Text exact match (name is alias for text)
+        const textToMatch = this.text ?? this.name;
+        if (textToMatch !== undefined) {
+            const elementText = element.text || '';
+            if (elementText !== textToMatch) {
+                return false;
+            }
+        }
+        // Text contains (substring, case-insensitive)
+        if (this.textContains !== undefined) {
+            const elementText = element.text || '';
+            if (!elementText.toLowerCase().includes(this.textContains.toLowerCase())) {
+                return false;
+            }
+        }
+        // Href contains (substring)
+        if (this.hrefContains !== undefined) {
+            const elementHref = element.href || '';
+            if (!elementHref.toLowerCase().includes(this.hrefContains.toLowerCase())) {
+                return false;
+            }
+        }
+        // In viewport filter
+        if (this.inViewport !== undefined) {
+            if (element.in_viewport !== this.inViewport) {
+                return false;
+            }
+        }
+        // Occluded filter
+        if (this.occluded !== undefined) {
+            if (element.is_occluded !== this.occluded) {
+                return false;
+            }
+        }
+        // Group key exact match
+        if (this.group !== undefined) {
+            if (element.group_key !== this.group) {
+                return false;
+            }
+        }
+        // In dominant group check
+        if (this.inDominantGroup !== undefined) {
+            if (this.inDominantGroup) {
+                // Element must be in dominant group
+                if (!snapshot) {
+                    return false;
+                }
+                if (element.group_key !== snapshot.dominant_group_key) {
+                    return false;
+                }
+            }
+            else {
+                // Element must NOT be in dominant group
+                if (snapshot && element.group_key === snapshot.dominant_group_key) {
+                    return false;
+                }
+            }
+        }
+        // Group index filter (from ListQuery.nth())
+        if (this._groupIndex !== undefined) {
+            if (element.group_index !== this._groupIndex) {
+                return false;
+            }
+        }
+        // Dominant list filter (from inDominantList())
+        if (this._fromDominantList) {
+            if (!snapshot) {
+                return false;
+            }
+            if (element.group_key !== snapshot.dominant_group_key) {
+                return false;
+            }
+        }
+        return true;
+    }
+    /**
+     * Find all elements matching this query in the snapshot.
+     *
+     * @param snapshot - Snapshot to search
+     * @returns Array of matching elements, sorted by doc_y (top to bottom)
+     */
+    findAll(snapshot) {
+        const matches = snapshot.elements.filter(el => this.matches(el, snapshot));
+        // Sort by doc_y for consistent ordering (top to bottom)
+        matches.sort((a, b) => (a.doc_y ?? a.bbox.y) - (b.doc_y ?? b.bbox.y));
+        return matches;
+    }
+    /**
+     * Find first matching element.
+     *
+     * @param snapshot - Snapshot to search
+     * @returns First matching element or null
+     */
+    findFirst(snapshot) {
+        const matches = this.findAll(snapshot);
+        return matches.length > 0 ? matches[0] : null;
+    }
+}
+exports.ElementQuery = ElementQuery;
+/**
+ * Create an element query.
+ *
+ * This is the main entry point for building element queries.
+ * It returns a pure data object that can be used with expect().
+ *
+ * @param options - Query filter options
+ * @returns ElementQuery object
+ *
+ * @example
+ * E({ role: "button", textContains: "Save" })
+ * E({ role: "link", hrefContains: "/checkout" })
+ * E({ inViewport: true, occluded: false })
+ */
+exports.E = Object.assign(function (options = {}) {
+    return new ElementQuery(options);
+}, {
+    /**
+     * Query for submit-like buttons.
+     * Matches buttons with text like "Submit", "Save", "Continue", etc.
+     */
+    submit: function () {
+        return new ElementQuery({ role: 'button', textContains: 'submit' });
+    },
+    /**
+     * Query for search input boxes.
+     * Matches textbox/combobox with search-related names.
+     */
+    searchBox: function () {
+        return new ElementQuery({ role: 'textbox', name: 'search' });
+    },
+    /**
+     * Query for links with optional text filter.
+     *
+     * @param options - Optional text filter
+     */
+    link: function (options) {
+        return new ElementQuery({ role: 'link', textContains: options?.textContains });
+    },
+});
+/**
+ * Represents multiple elements from a dominant list query.
+ *
+ * Created by ListQuery.top(n) to represent the first n elements
+ * in a dominant group.
+ *
+ * @example
+ * inDominantList().top(5) // First 5 items in dominant group
+ */
+class MultiQuery {
+    constructor(limit, parentListQuery) {
+        this.limit = limit;
+        this._parentListQuery = parentListQuery;
+    }
+    /**
+     * Create a predicate that checks if any element's text contains the substring.
+     *
+     * @param text - Substring to search for
+     * @returns Predicate that can be used with expect()
+     */
+    anyTextContains(text) {
+        return {
+            multiQuery: this,
+            text,
+            checkType: 'any_contains',
+        };
+    }
+}
+exports.MultiQuery = MultiQuery;
+/**
+ * Query over elements in the dominant group.
+ *
+ * Provides ordinal access to dominant-group elements via .nth(k)
+ * and range access via .top(n).
+ *
+ * Created by inDominantList().
+ *
+ * @example
+ * inDominantList().nth(0)   // First item in dominant group
+ * inDominantList().top(5)   // First 5 items
+ */
+class ListQuery {
+    /**
+     * Select element at specific index in the dominant group.
+     *
+     * @param index - 0-based index in the dominant group
+     * @returns ElementQuery targeting the element at that position
+     *
+     * @example
+     * inDominantList().nth(0)  // First item
+     * inDominantList().nth(2)  // Third item
+     */
+    nth(index) {
+        const query = new ElementQuery();
+        query._groupIndex = index;
+        query._fromDominantList = true;
+        return query;
+    }
+    /**
+     * Select the first n elements in the dominant group.
+     *
+     * @param n - Number of elements to select
+     * @returns MultiQuery representing the first n elements
+     *
+     * @example
+     * inDominantList().top(5) // First 5 items
+     */
+    top(n) {
+        return new MultiQuery(n, this);
+    }
+}
+exports.ListQuery = ListQuery;
+/**
+ * Create a query over elements in the dominant group.
+ *
+ * The dominant group is the most common group_key in the snapshot,
+ * typically representing the main content list (search results,
+ * news feed items, product listings, etc.).
+ *
+ * @returns ListQuery for chaining .nth(k) or .top(n)
+ *
+ * @example
+ * inDominantList().nth(0)     // First item in dominant group
+ * inDominantList().top(5)     // First 5 items
+ *
+ * // With expect():
+ * expect(inDominantList().nth(0)).toHaveTextContains("Show HN")
+ */
+function inDominantList() {
+    return new ListQuery();
+}
+//# sourceMappingURL=query.js.map

package/dist/asserts/query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.js","sourceRoot":"","sources":["../../src/asserts/query.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;GAcG;;;AAgWH,wCAEC;AAtUD;;;;;;;;;;GAUG;AACH,MAAa,YAAY;IAevB,YAAY,UAAoB,EAAE;QAFlC,sBAAiB,GAAY,KAAK,CAAC;QAGjC,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;QACzB,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;QACzB,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;QACzB,IAAI,CAAC,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;QACzC,IAAI,CAAC,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;QACzC,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;QACrC,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;QACjC,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;QAC3B,IAAI,CAAC,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC;IACjD,CAAC;IAED;;;;;;OAMG;IACH,OAAO,CAAC,OAAgB,EAAE,QAA0B;QAClD,cAAc;QACd,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;YAC5B,IAAI,OAAO,CAAC,IAAI,KAAK,IAAI,CAAC,IAAI,EAAE,CAAC;gBAC/B,OAAO,KAAK,CAAC;YACf,CAAC;QACH,CAAC;QAED,4CAA4C;QAC5C,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,CAAC;QAC3C,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;YAC9B,MAAM,WAAW,GAAG,OAAO,CAAC,IAAI,IAAI,EAAE,CAAC;YACvC,IAAI,WAAW,KAAK,WAAW,EAAE,CAAC;gBAChC,OAAO,KAAK,CAAC;YACf,CAAC;QACH,CAAC;QAED,8CAA8C;QAC9C,IAAI,IAAI,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;YACpC,MAAM,WAAW,GAAG,OAAO,CAAC,IAAI,IAAI,EAAE,CAAC;YACvC,IAAI,CAAC,WAAW,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,YAAY,CAAC,WAAW,EAAE,CAAC,EAAE,CAAC;gBACzE,OAAO,KAAK,CAAC;YACf,CAAC;QACH,CAAC;QAED,4BAA4B;QAC5B,IAAI,IAAI,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;YACpC,MAAM,WAAW,GAAG,OAAO,CAAC,IAAI,IAAI,EAAE,CAAC;YACvC,IAAI,CAAC,WAAW,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,YAAY,CAAC,WAAW,EAAE,CAAC,EAAE,CAAC;gBACzE,OAAO,KAAK,CAAC;YACf,CAAC;QACH,CAAC;QAED,qBAAqB;QACrB,IAAI,IAAI,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;YAClC,IAAI,OAAO,CAAC,WAAW,KAAK,IAAI,CAAC,UAAU,EAAE,CAAC;gBAC5C,OAAO,KAAK,CAAC;YACf,CAAC;QACH,CAAC;QAED,kBAAkB;QAClB,IAAI,IAAI,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;YAChC,IAAI,OAAO,CAAC,WAAW,KAAK,IAAI,CAAC,QAAQ,EAAE,CAAC;gBAC1C,OAAO,KAAK,CAAC;YACf,CAAC;QACH,CAAC;QAED,wBAAwB;QACxB,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;YAC7B,IAAI,OAAO,CAAC,SAAS,KAAK,IAAI,CAAC,KAAK,EAAE,CAAC;gBACrC,OAAO,KAAK,CAAC;YACf,CAAC;QACH,CAAC;QAED,0BAA0B;QAC1B,IAAI,IAAI,CAAC,eAAe,KAAK,SAAS,EAAE,CAAC;YACvC,IAAI,IAAI,CAAC,eAAe,EAAE,CAAC;gBACzB,oCAAoC;gBACpC,IAAI,CAAC,QAAQ,EAAE,CAAC;oBACd,OAAO,KAAK,CAAC;gBACf,CAAC;gBACD,IAAI,OAAO,CAAC,SAAS,KAAK,QAAQ,CAAC,kBAAkB,EAAE,CAAC;oBACtD,OAAO,KAAK,CAAC;gBACf,CAAC;YACH,CAAC;iBAAM,CAAC;gBACN,wCAAwC;gBACxC,IAAI,QAAQ,IAAI,OAAO,CAAC,SAAS,KAAK,QAAQ,CAAC,kBAAkB,EAAE,CAAC;oBAClE,OAAO,KAAK,CAAC;gBACf,CAAC;YACH,CAAC;QACH,CAAC;QAED,4CAA4C;QAC5C,IAAI,IAAI,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;YACnC,IAAI,OAAO,CAAC,WAAW,KAAK,IAAI,CAAC,WAAW,EAAE,CAAC;gBAC7C,OAAO,KAAK,CAAC;YACf,CAAC;QACH,CAAC;QAED,+CAA+C;QAC/C,IAAI,IAAI,CAAC,iBAAiB,EAAE,CAAC;YAC3B,IAAI,CAAC,QAAQ,EAAE,CAAC;gBACd,OAAO,KAAK,CAAC;YACf,CAAC;YACD,IAAI,OAAO,CAAC,SAAS,KAAK,QAAQ,CAAC,kBAAkB,EAAE,CAAC;gBACtD,OAAO,KAAK,CAAC;YACf,CAAC;QACH,CAAC;QAED,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;OAKG;IACH,OAAO,CAAC,QAAkB;QACxB,MAAM,OAAO,GAAG,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,EAAE,QAAQ,CAAC,CAAC,CAAC;QAC3E,wDAAwD;QACxD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;QACtE,OAAO,OAAO,CAAC;IACjB,CAAC;IAED;;;;;OAKG;IACH,SAAS,CAAC,QAAkB;QAC1B,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QACvC,OAAO,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAChD,CAAC;CACF;AArJD,oCAqJC;AAeD;;;;;;;;;;;;;GAaG;AACU,QAAA,CAAC,GAAc,MAAM,CAAC,MAAM,CACvC,UAAU,UAAoB,EAAE;IAC9B,OAAO,IAAI,YAAY,CAAC,OAAO,CAAC,CAAC;AACnC,CAAC,EACD;IACE;;;OAGG;IACH,MAAM,EAAE;QACN,OAAO,IAAI,YAAY,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,YAAY,EAAE,QAAQ,EAAE,CAAC,CAAC;IACtE,CAAC;IAED;;;OAGG;IACH,SAAS,EAAE;QACT,OAAO,IAAI,YAAY,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC;IAC/D,CAAC;IAED;;;;OAIG;IACH,IAAI,EAAE,UAAU,OAAmC;QACjD,OAAO,IAAI,YAAY,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,OAAO,EAAE,YAAY,EAAE,CAAC,CAAC;IACjF,CAAC;CACF,CACF,CAAC;AAYF;;;;;;;;GAQG;AACH,MAAa,UAAU;IAIrB,YAAY,KAAa,EAAE,eAA2B;QACpD,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,gBAAgB,GAAG,eAAe,CAAC;IAC1C,CAAC;IAED;;;;;OAKG;IACH,eAAe,CAAC,IAAY;QAC1B,OAAO;YACL,UAAU,EAAE,IAAI;YAChB,IAAI;YACJ,SAAS,EAAE,cAAc;SAC1B,CAAC;IACJ,CAAC;CACF;AAtBD,gCAsBC;AAED;;;;;;;;;;;GAWG;AACH,MAAa,SAAS;IACpB;;;;;;;;;OASG;IACH,GAAG,CAAC,KAAa;QACf,MAAM,KAAK,GAAG,IAAI,YAAY,EAAE,CAAC;QACjC,KAAK,CAAC,WAAW,GAAG,KAAK,CAAC;QAC1B,KAAK,CAAC,iBAAiB,GAAG,IAAI,CAAC;QAC/B,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;;;;;;;OAQG;IACH,GAAG,CAAC,CAAS;QACX,OAAO,IAAI,UAAU,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;IACjC,CAAC;CACF;AA9BD,8BA8BC;AAED;;;;;;;;;;;;;;;GAeG;AACH,SAAgB,cAAc;IAC5B,OAAO,IAAI,SAAS,EAAE,CAAC;AACzB,CAAC"}

package/dist/backends/actions.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Backend-agnostic actions for browser-use integration.
+ *
+ * These actions work with any BrowserBackend implementation,
+ * enabling Sentience grounding with browser-use or other frameworks.
+ *
+ * Usage with browser-use:
+ *   import { BrowserUseAdapter } from './backends/browser-use-adapter';
+ *   import { click, typeText, scroll } from './backends/actions';
+ *
+ *   const adapter = new BrowserUseAdapter(session);
+ *   const backend = await adapter.createBackend();
+ *
+ *   // Take snapshot and click element
+ *   const snap = await snapshot(backend);
+ *   const element = find(snap, 'role=button[name="Submit"]');
+ *   await click(backend, element.bbox);
+ */
+import type { ActionResult, BBox } from '../types';
+import type { BrowserBackend, MouseButton } from './protocol';
+import type { CursorPolicy } from '../cursor-policy';
+/**
+ * Target type for coordinate resolution.
+ * Can be a BBox (clicks center), {x, y} object, or [x, y] tuple.
+ */
+export type ClickTarget = BBox | {
+    x: number;
+    y: number;
+    width?: number;
+    height?: number;
+} | [number, number];
+/**
+ * Scroll behavior for scrollToElement.
+ */
+export type ScrollBehavior = 'smooth' | 'instant' | 'auto';
+/**
+ * Vertical alignment for scrollToElement.
+ */
+export type ScrollBlock = 'start' | 'center' | 'end' | 'nearest';
+/**
+ * Click at coordinates using the backend.
+ *
+ * @param backend - BrowserBackend implementation
+ * @param target - Click target - BBox (clicks center), dict with x/y, or (x, y) tuple
+ * @param button - Mouse button to click
+ * @param clickCount - Number of clicks (1=single, 2=double)
+ * @param moveFirst - Whether to move mouse to position before clicking
+ * @returns ActionResult with success status
+ *
+ * @example
+ *   // Click at coordinates
+ *   await click(backend, [100, 200]);
+ *
+ *   // Click element bbox center
+ *   await click(backend, element.bbox);
+ *
+ *   // Double-click
+ *   await click(backend, element.bbox, 'left', 2);
+ */
+export declare function click(backend: BrowserBackend, target: ClickTarget, button?: MouseButton, clickCount?: number, moveFirst?: boolean, cursorPolicy?: CursorPolicy): Promise<ActionResult>;
+/**
+ * Type text, optionally clicking a target first.
+ *
+ * @param backend - BrowserBackend implementation
+ * @param text - Text to type
+ * @param target - Optional click target before typing (BBox, dict, or tuple)
+ * @param clearFirst - If true, select all and delete before typing
+ * @returns ActionResult with success status
+ *
+ * @example
+ *   // Type into focused element
+ *   await typeText(backend, 'Hello World');
+ *
+ *   // Click input then type
+ *   await typeText(backend, 'search query', searchBox.bbox);
+ *
+ *   // Clear and type
+ *   await typeText(backend, 'new value', input.bbox, true);
+ */
+export declare function typeText(backend: BrowserBackend, text: string, target?: ClickTarget, clearFirst?: boolean): Promise<ActionResult>;
+/**
+ * Scroll the page or element.
+ *
+ * @param backend - BrowserBackend implementation
+ * @param deltaY - Scroll amount (positive=down, negative=up)
+ * @param target - Optional position for scroll (defaults to viewport center)
+ * @returns ActionResult with success status
+ *
+ * @example
+ *   // Scroll down 300px
+ *   await scroll(backend, 300);
+ *
+ *   // Scroll up 500px
+ *   await scroll(backend, -500);
+ *
+ *   // Scroll at specific position
+ *   await scroll(backend, 200, [500, 300]);
+ */
+export declare function scroll(backend: BrowserBackend, deltaY?: number, target?: ClickTarget): Promise<ActionResult>;
+/**
+ * Scroll element into view using JavaScript scrollIntoView.
+ *
+ * @param backend - BrowserBackend implementation
+ * @param elementId - Element ID from snapshot (requires sentience_registry)
+ * @param behavior - Scroll behavior
+ * @param block - Vertical alignment
+ * @returns ActionResult with success status
+ */
+export declare function scrollToElement(backend: BrowserBackend, elementId: number, behavior?: ScrollBehavior, block?: ScrollBlock): Promise<ActionResult>;
+/**
+ * Wait for page to reach stable state.
+ *
+ * @param backend - BrowserBackend implementation
+ * @param state - Target document.readyState
+ * @param timeoutMs - Maximum wait time
+ * @returns ActionResult with success status
+ */
+export declare function waitForStable(backend: BrowserBackend, state?: 'interactive' | 'complete', timeoutMs?: number): Promise<ActionResult>;
+//# sourceMappingURL=actions.d.ts.map