@predicatelabs/sdk 0.99.9

package/dist/utils/browser-evaluator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-evaluator.d.ts","sourceRoot":"","sources":["../../src/utils/browser-evaluator.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAElC,MAAM,WAAW,iBAAiB;IAChC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CAClC;AAED;;GAEG;AACH,qBAAa,gBAAgB;IAC3B;;;;;;;;;;;;;;;;;OAiBG;WACU,QAAQ,CAAC,CAAC,EACrB,IAAI,EAAE,IAAI,EACV,MAAM,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,EACrC,IAAI,CAAC,EAAE,GAAG,EACV,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,CAAC,CAAC;IA0Cb;;;;;;;;;;;;;;;;;;;OAmBG;WACU,8BAA8B,CAAC,CAAC,EAC3C,IAAI,EAAE,IAAI,EACV,MAAM,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,EACrC,IAAI,CAAC,EAAE,GAAG,EACV,aAAa,CAAC,EAAE,CAAC,GAChB,OAAO,CAAC,CAAC,CAAC;IAab;;;;;;;;;;;;;;;;OAgBG;WACU,gBAAgB,CAC3B,IAAI,EAAE,IAAI,EACV,SAAS,EAAE,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,EAC3C,OAAO,GAAE,MAAa,GACrB,OAAO,CAAC,IAAI,CAAC;CAqBjB"}

package/dist/utils/browser-evaluator.js

@@ -0,0 +1,130 @@
+"use strict";
+/**
+ * BrowserEvaluator - Common browser evaluation patterns with standardized error handling
+ *
+ * This utility class extracts common page.evaluate() patterns to reduce code duplication
+ * and provide consistent error handling across snapshot, actions, wait, and read modules.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BrowserEvaluator = void 0;
+/**
+ * BrowserEvaluator provides static methods for common browser evaluation patterns
+ */
+class BrowserEvaluator {
+    /**
+     * Execute a browser evaluation script with standardized error handling
+     *
+     * @param page - Playwright Page instance
+     * @param script - Function to execute in browser context
+     * @param args - Arguments to pass to the script
+     * @param options - Evaluation options (timeout, retries, error handler)
+     * @returns Promise resolving to the evaluation result
+     *
+     * @example
+     * ```typescript
+     * const result = await BrowserEvaluator.evaluate(
+     *   page,
+     *   (opts) => (window as any).sentience.snapshot(opts),
+     *   { limit: 50 }
+     * );
+     * ```
+     */
+    static async evaluate(page, script, args, options = {}) {
+        const { timeout, retries = 0, onError } = options;
+        let lastError;
+        for (let attempt = 0; attempt <= retries; attempt++) {
+            try {
+                if (timeout) {
+                    return await Promise.race([
+                        page.evaluate(script, args),
+                        new Promise((_, reject) => setTimeout(() => reject(new Error(`Evaluation timeout after ${timeout}ms`)), timeout)),
+                    ]);
+                }
+                return await page.evaluate(script, args);
+            }
+            catch (error) {
+                lastError = error instanceof Error ? error : new Error(String(error));
+                // Call custom error handler if provided
+                if (onError) {
+                    onError(lastError);
+                }
+                // If this was the last retry, throw the error
+                if (attempt === retries) {
+                    throw new Error(`Browser evaluation failed after ${retries + 1} attempt(s): ${lastError.message}`);
+                }
+                // Wait before retry (exponential backoff)
+                if (attempt < retries) {
+                    await new Promise(resolve => setTimeout(resolve, Math.pow(2, attempt) * 100));
+                }
+            }
+        }
+        // This should never be reached, but TypeScript needs it
+        throw lastError || new Error('Browser evaluation failed');
+    }
+    /**
+     * Execute a browser evaluation with navigation-aware error handling
+     * Navigation may destroy the context, so we handle that gracefully
+     *
+     * @param page - Playwright Page instance
+     * @param script - Function to execute in browser context
+     * @param args - Arguments to pass to the script
+     * @param fallbackValue - Value to return if evaluation fails due to navigation
+     * @returns Promise resolving to the evaluation result or fallback value
+     *
+     * @example
+     * ```typescript
+     * const success = await BrowserEvaluator.evaluateWithNavigationFallback(
+     *   page,
+     *   (id) => (window as any).sentience.click(id),
+     *   elementId,
+     *   true // Assume success if navigation destroyed context
+     * );
+     * ```
+     */
+    static async evaluateWithNavigationFallback(page, script, args, fallbackValue) {
+        try {
+            return await page.evaluate(script, args);
+        }
+        catch (error) {
+            // Navigation might have destroyed context, return fallback if provided
+            if (fallbackValue !== undefined) {
+                return fallbackValue;
+            }
+            // Otherwise rethrow
+            throw error;
+        }
+    }
+    /**
+     * Wait for a condition in the browser context with timeout
+     *
+     * @param page - Playwright Page instance
+     * @param condition - Function that returns a truthy value when condition is met
+     * @param timeout - Maximum time to wait in milliseconds
+     * @returns Promise resolving when condition is met
+     *
+     * @example
+     * ```typescript
+     * await BrowserEvaluator.waitForCondition(
+     *   page,
+     *   () => typeof (window as any).sentience !== 'undefined',
+     *   5000
+     * );
+     * ```
+     */
+    static async waitForCondition(page, condition, timeout = 5000) {
+        try {
+            await page.waitForFunction(condition, { timeout });
+        }
+        catch (error) {
+            // Gather diagnostics if wait fails
+            const diag = await this.evaluateWithNavigationFallback(page, () => ({
+                sentience_defined: typeof window.sentience !== 'undefined',
+                extension_id: document.documentElement.dataset.sentienceExtensionId || 'not set',
+                url: window.location.href,
+            }), undefined, { sentience_defined: false, extension_id: 'not set', url: 'unknown' });
+            throw new Error(`Condition wait failed after ${timeout}ms. ` + `Diagnostics: ${JSON.stringify(diag)}`);
+        }
+    }
+}
+exports.BrowserEvaluator = BrowserEvaluator;
+//# sourceMappingURL=browser-evaluator.js.map

package/dist/utils/browser-evaluator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-evaluator.js","sourceRoot":"","sources":["../../src/utils/browser-evaluator.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAUH;;GAEG;AACH,MAAa,gBAAgB;IAC3B;;;;;;;;;;;;;;;;;OAiBG;IACH,MAAM,CAAC,KAAK,CAAC,QAAQ,CACnB,IAAU,EACV,MAAqC,EACrC,IAAU,EACV,UAA6B,EAAE;QAE/B,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;QAElD,IAAI,SAA4B,CAAC;QAEjC,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,OAAO,EAAE,OAAO,EAAE,EAAE,CAAC;YACpD,IAAI,CAAC;gBACH,IAAI,OAAO,EAAE,CAAC;oBACZ,OAAO,MAAM,OAAO,CAAC,IAAI,CAAC;wBACxB,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC;wBAC3B,IAAI,OAAO,CAAI,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAC3B,UAAU,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,4BAA4B,OAAO,IAAI,CAAC,CAAC,EAAE,OAAO,CAAC,CACtF;qBACF,CAAC,CAAC;gBACL,CAAC;gBACD,OAAO,MAAM,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;YAC3C,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,SAAS,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;gBAEtE,wCAAwC;gBACxC,IAAI,OAAO,EAAE,CAAC;oBACZ,OAAO,CAAC,SAAS,CAAC,CAAC;gBACrB,CAAC;gBAED,8CAA8C;gBAC9C,IAAI,OAAO,KAAK,OAAO,EAAE,CAAC;oBACxB,MAAM,IAAI,KAAK,CACb,mCAAmC,OAAO,GAAG,CAAC,gBAAgB,SAAS,CAAC,OAAO,EAAE,CAClF,CAAC;gBACJ,CAAC;gBAED,0CAA0C;gBAC1C,IAAI,OAAO,GAAG,OAAO,EAAE,CAAC;oBACtB,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC;gBAChF,CAAC;YACH,CAAC;QACH,CAAC;QAED,wDAAwD;QACxD,MAAM,SAAS,IAAI,IAAI,KAAK,CAAC,2BAA2B,CAAC,CAAC;IAC5D,CAAC;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,MAAM,CAAC,KAAK,CAAC,8BAA8B,CACzC,IAAU,EACV,MAAqC,EACrC,IAAU,EACV,aAAiB;QAEjB,IAAI,CAAC;YACH,OAAO,MAAM,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;QAC3C,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,uEAAuE;YACvE,IAAI,aAAa,KAAK,SAAS,EAAE,CAAC;gBAChC,OAAO,aAAa,CAAC;YACvB,CAAC;YACD,oBAAoB;YACpB,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,KAAK,CAAC,gBAAgB,CAC3B,IAAU,EACV,SAA2C,EAC3C,UAAkB,IAAI;QAEtB,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,eAAe,CAAC,SAAS,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;QACrD,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,mCAAmC;YACnC,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,8BAA8B,CACpD,IAAI,EACJ,GAAG,EAAE,CAAC,CAAC;gBACL,iBAAiB,EAAE,OAAQ,MAAc,CAAC,SAAS,KAAK,WAAW;gBACnE,YAAY,EAAE,QAAQ,CAAC,eAAe,CAAC,OAAO,CAAC,oBAAoB,IAAI,SAAS;gBAChF,GAAG,EAAE,MAAM,CAAC,QAAQ,CAAC,IAAI;aAC1B,CAAC,EACF,SAAS,EACT,EAAE,iBAAiB,EAAE,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,GAAG,EAAE,SAAS,EAAE,CACtE,CAAC;YAEF,MAAM,IAAI,KAAK,CACb,+BAA+B,OAAO,MAAM,GAAG,gBAAgB,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CACtF,CAAC;QACJ,CAAC;IACH,CAAC;CACF;AAlJD,4CAkJC"}

package/dist/utils/browser.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Browser-related utility functions
+ */
+import { BrowserContext } from 'playwright';
+/**
+ * Save current browser storage state (cookies + localStorage) to a file.
+ *
+ * This is useful for capturing a logged-in session to reuse later.
+ *
+ * @param context - Playwright BrowserContext
+ * @param filePath - Path to save the storage state JSON file
+ *
+ * @example
+ * ```typescript
+ * import { SentienceBrowser } from 'sentience-ts';
+ * import { saveStorageState } from 'sentience-ts/utils/browser';
+ *
+ * const browser = new SentienceBrowser();
+ * await browser.start();
+ *
+ * // User logs in manually or via agent
+ * await browser.getPage().goto('https://example.com');
+ * // ... login happens ...
+ *
+ * // Save session for later
+ * await saveStorageState(browser.getContext(), 'auth.json');
+ * ```
+ */
+export declare function saveStorageState(context: BrowserContext, filePath: string): Promise<void>;
+//# sourceMappingURL=browser.d.ts.map

package/dist/utils/browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../../src/utils/browser.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAI5C;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAQ/F"}

package/dist/utils/browser.js

@@ -0,0 +1,75 @@
+"use strict";
+/**
+ * Browser-related utility functions
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.saveStorageState = saveStorageState;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+/**
+ * Save current browser storage state (cookies + localStorage) to a file.
+ *
+ * This is useful for capturing a logged-in session to reuse later.
+ *
+ * @param context - Playwright BrowserContext
+ * @param filePath - Path to save the storage state JSON file
+ *
+ * @example
+ * ```typescript
+ * import { SentienceBrowser } from 'sentience-ts';
+ * import { saveStorageState } from 'sentience-ts/utils/browser';
+ *
+ * const browser = new SentienceBrowser();
+ * await browser.start();
+ *
+ * // User logs in manually or via agent
+ * await browser.getPage().goto('https://example.com');
+ * // ... login happens ...
+ *
+ * // Save session for later
+ * await saveStorageState(browser.getContext(), 'auth.json');
+ * ```
+ */
+async function saveStorageState(context, filePath) {
+    const storageState = await context.storageState();
+    const dir = path.dirname(filePath);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    fs.writeFileSync(filePath, JSON.stringify(storageState, null, 2));
+    console.log(`✅ [Sentience] Saved storage state to ${filePath}`);
+}
+//# sourceMappingURL=browser.js.map

package/dist/utils/browser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.js","sourceRoot":"","sources":["../../src/utils/browser.ts"],"names":[],"mappings":";AAAA;;GAEG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8BH,4CAQC;AAnCD,uCAAyB;AACzB,2CAA6B;AAE7B;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACI,KAAK,UAAU,gBAAgB,CAAC,OAAuB,EAAE,QAAgB;IAC9E,MAAM,YAAY,GAAG,MAAM,OAAO,CAAC,YAAY,EAAE,CAAC;IAClD,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACnC,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QACxB,EAAE,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACzC,CAAC;IACD,EAAE,CAAC,aAAa,CAAC,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC,YAAY,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IAClE,OAAO,CAAC,GAAG,CAAC,wCAAwC,QAAQ,EAAE,CAAC,CAAC;AAClE,CAAC"}

package/dist/utils/element-filter.d.ts

@@ -0,0 +1,76 @@
+/**
+ * ElementFilter - Consolidates element filtering logic
+ *
+ * This utility class extracts common element filtering patterns from agent.ts and query.ts
+ * to reduce code duplication and improve maintainability.
+ */
+import { Snapshot, Element } from '../types';
+export interface FilterOptions {
+    maxElements?: number;
+    minImportance?: number;
+    maxImportance?: number;
+    inViewportOnly?: boolean;
+    clickableOnly?: boolean;
+}
+/**
+ * ElementFilter provides static methods for filtering elements from snapshots
+ */
+export declare class ElementFilter {
+    /**
+     * Filter elements by importance score
+     *
+     * @param snapshot - Snapshot containing elements
+     * @param maxElements - Maximum number of elements to return (default: 50)
+     * @returns Filtered and sorted array of elements
+     *
+     * @example
+     * ```typescript
+     * const filtered = ElementFilter.filterByImportance(snap, 50);
+     * ```
+     */
+    static filterByImportance(snapshot: Snapshot, maxElements?: number): Element[];
+    /**
+     * Filter elements relevant to a goal using keyword matching
+     * Applies goal-based keyword matching to boost relevant elements
+     *
+     * @param snapshot - Snapshot containing elements
+     * @param goal - Goal/task description to match against
+     * @param maxElements - Maximum number of elements to return (default: 50)
+     * @returns Filtered and scored array of elements
+     *
+     * @example
+     * ```typescript
+     * const filtered = ElementFilter.filterByGoal(snap, "Click the search box", 50);
+     * ```
+     */
+    static filterByGoal(snapshot: Snapshot, goal: string, maxElements?: number): Element[];
+    /**
+     * Filter elements using multiple criteria
+     *
+     * @param snapshot - Snapshot containing elements
+     * @param options - Filter options
+     * @returns Filtered array of elements
+     *
+     * @example
+     * ```typescript
+     * const filtered = ElementFilter.filter(snap, {
+     *   maxElements: 50,
+     *   minImportance: 0.5,
+     *   inViewportOnly: true,
+     *   clickableOnly: false
+     * });
+     * ```
+     */
+    static filter(snapshot: Snapshot, options?: FilterOptions): Element[];
+    /**
+     * Extract keywords from a goal string
+     * Removes common stop words and returns meaningful keywords
+     *
+     * @param goal - Goal string to extract keywords from
+     * @returns Array of keywords
+     *
+     * @private
+     */
+    private static extractKeywords;
+}
+//# sourceMappingURL=element-filter.d.ts.map

package/dist/utils/element-filter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"element-filter.d.ts","sourceRoot":"","sources":["../../src/utils/element-filter.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAE7C,MAAM,WAAW,aAAa;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;GAEG;AACH,qBAAa,aAAa;IACxB;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,kBAAkB,CAAC,QAAQ,EAAE,QAAQ,EAAE,WAAW,GAAE,MAAW,GAAG,OAAO,EAAE;IAWlF;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,YAAY,CAAC,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,GAAE,MAAW,GAAG,OAAO,EAAE;IA6C1F;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,QAAQ,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,EAAE;IAgCzE;;;;;;;;OAQG;IACH,OAAO,CAAC,MAAM,CAAC,eAAe;CA8D/B"}

package/dist/utils/element-filter.js

@@ -0,0 +1,195 @@
+"use strict";
+/**
+ * ElementFilter - Consolidates element filtering logic
+ *
+ * This utility class extracts common element filtering patterns from agent.ts and query.ts
+ * to reduce code duplication and improve maintainability.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ElementFilter = void 0;
+/**
+ * ElementFilter provides static methods for filtering elements from snapshots
+ */
+class ElementFilter {
+    /**
+     * Filter elements by importance score
+     *
+     * @param snapshot - Snapshot containing elements
+     * @param maxElements - Maximum number of elements to return (default: 50)
+     * @returns Filtered and sorted array of elements
+     *
+     * @example
+     * ```typescript
+     * const filtered = ElementFilter.filterByImportance(snap, 50);
+     * ```
+     */
+    static filterByImportance(snapshot, maxElements = 50) {
+        // Filter out REMOVED elements - they're not actionable and shouldn't be in LLM context
+        const elements = snapshot.elements.filter(el => el.diff_status !== 'REMOVED');
+        // Sort by importance (descending)
+        elements.sort((a, b) => b.importance - a.importance);
+        // Return top N elements
+        return elements.slice(0, maxElements);
+    }
+    /**
+     * Filter elements relevant to a goal using keyword matching
+     * Applies goal-based keyword matching to boost relevant elements
+     *
+     * @param snapshot - Snapshot containing elements
+     * @param goal - Goal/task description to match against
+     * @param maxElements - Maximum number of elements to return (default: 50)
+     * @returns Filtered and scored array of elements
+     *
+     * @example
+     * ```typescript
+     * const filtered = ElementFilter.filterByGoal(snap, "Click the search box", 50);
+     * ```
+     */
+    static filterByGoal(snapshot, goal, maxElements = 50) {
+        if (!goal) {
+            return this.filterByImportance(snapshot, maxElements);
+        }
+        // Filter out REMOVED elements - they're not actionable and shouldn't be in LLM context
+        const elements = snapshot.elements.filter(el => el.diff_status !== 'REMOVED');
+        const goalLower = goal.toLowerCase();
+        const keywords = this.extractKeywords(goalLower);
+        // Score elements based on keyword matches
+        const scoredElements = [];
+        for (const element of elements) {
+            let score = element.importance; // Start with base importance
+            // Boost score for keyword matches in text
+            if (element.text) {
+                const textLower = element.text.toLowerCase();
+                for (const keyword of keywords) {
+                    if (textLower.includes(keyword)) {
+                        score += 0.5; // Boost for keyword match
+                    }
+                }
+            }
+            // Boost score for keyword matches in role
+            const roleLower = element.role.toLowerCase();
+            for (const keyword of keywords) {
+                if (roleLower.includes(keyword)) {
+                    score += 0.3; // Smaller boost for role match
+                }
+            }
+            scoredElements.push([score, element]);
+        }
+        // Sort by score (descending)
+        scoredElements.sort((a, b) => b[0] - a[0]);
+        // Return top N elements
+        return scoredElements.slice(0, maxElements).map(([_, element]) => element);
+    }
+    /**
+     * Filter elements using multiple criteria
+     *
+     * @param snapshot - Snapshot containing elements
+     * @param options - Filter options
+     * @returns Filtered array of elements
+     *
+     * @example
+     * ```typescript
+     * const filtered = ElementFilter.filter(snap, {
+     *   maxElements: 50,
+     *   minImportance: 0.5,
+     *   inViewportOnly: true,
+     *   clickableOnly: false
+     * });
+     * ```
+     */
+    static filter(snapshot, options = {}) {
+        // Filter out REMOVED elements - they're not actionable and shouldn't be in LLM context
+        let elements = snapshot.elements.filter(el => el.diff_status !== 'REMOVED');
+        // Apply filters
+        if (options.minImportance !== undefined) {
+            elements = elements.filter(el => el.importance >= options.minImportance);
+        }
+        if (options.maxImportance !== undefined) {
+            elements = elements.filter(el => el.importance <= options.maxImportance);
+        }
+        if (options.inViewportOnly) {
+            elements = elements.filter(el => el.in_viewport);
+        }
+        if (options.clickableOnly) {
+            elements = elements.filter(el => el.visual_cues.is_clickable);
+        }
+        // Sort by importance (descending)
+        elements.sort((a, b) => b.importance - a.importance);
+        // Apply max elements limit
+        if (options.maxElements !== undefined) {
+            elements = elements.slice(0, options.maxElements);
+        }
+        return elements;
+    }
+    /**
+     * Extract keywords from a goal string
+     * Removes common stop words and returns meaningful keywords
+     *
+     * @param goal - Goal string to extract keywords from
+     * @returns Array of keywords
+     *
+     * @private
+     */
+    static extractKeywords(goal) {
+        // Common stop words to filter out
+        const stopWords = new Set([
+            'the',
+            'a',
+            'an',
+            'and',
+            'or',
+            'but',
+            'in',
+            'on',
+            'at',
+            'to',
+            'for',
+            'of',
+            'with',
+            'by',
+            'from',
+            'as',
+            'is',
+            'was',
+            'are',
+            'were',
+            'be',
+            'been',
+            'being',
+            'have',
+            'has',
+            'had',
+            'do',
+            'does',
+            'did',
+            'will',
+            'would',
+            'should',
+            'could',
+            'may',
+            'might',
+            'must',
+            'can',
+            'this',
+            'that',
+            'these',
+            'those',
+            'i',
+            'you',
+            'he',
+            'she',
+            'it',
+            'we',
+            'they',
+        ]);
+        // Split by whitespace and punctuation, filter out stop words and short words
+        const words = goal
+            .toLowerCase()
+            .split(/[\s,.;:!?()[\]{}'"]+/)
+            .filter(word => word.length > 2 && !stopWords.has(word));
+        // Remove duplicates
+        return Array.from(new Set(words));
+    }
+}
+exports.ElementFilter = ElementFilter;
+//# sourceMappingURL=element-filter.js.map

package/dist/utils/element-filter.js.map

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

package/dist/utils/grid-utils.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Utility functions for working with grid layout data in snapshots.
+ */
+import type { Snapshot, GridInfo } from '../types';
+/**
+ * Get grid coordinates (bounding boxes) for detected grids.
+ *
+ * Groups elements by grid_id and computes the overall bounding box,
+ * row/column counts, and item count for each grid.
+ *
+ * @param snapshot - The snapshot containing elements with layout data
+ * @param gridId - Optional grid ID to filter by. If undefined, returns all grids.
+ * @returns Array of GridInfo objects, one per detected grid, sorted by grid_id.
+ *          Each GridInfo contains:
+ *          - grid_id: The grid identifier
+ *          - bbox: Bounding box (x, y, width, height) in document coordinates
+ *          - row_count: Number of rows in the grid
+ *          - col_count: Number of columns in the grid
+ *          - item_count: Total number of items in the grid
+ *          - confidence: Confidence score (currently 1.0)
+ *          - label: Optional inferred label (e.g., "product_grid", "search_results", "navigation")
+ *            Note: Label inference is best-effort and may not always be accurate
+ *
+ * @example
+ * ```typescript
+ * const snapshot = await browser.snapshot();
+ * // Get all grids
+ * const allGrids = getGridBounds(snapshot);
+ * // Get specific grid
+ * const mainGrid = getGridBounds(snapshot, 0);
+ * if (mainGrid.length > 0) {
+ *   console.log(`Grid 0: ${mainGrid[0].item_count} items at (${mainGrid[0].bbox.x}, ${mainGrid[0].bbox.y})`);
+ * }
+ * ```
+ */
+export declare function getGridBounds(snapshot: Snapshot, gridId?: number): GridInfo[];
+//# sourceMappingURL=grid-utils.d.ts.map

package/dist/utils/grid-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grid-utils.d.ts","sourceRoot":"","sources":["../../src/utils/grid-utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAW,MAAM,UAAU,CAAC;AAE5D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,QAAQ,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,QAAQ,EAAE,CAgI7E"}