@predicatelabs/sdk 0.99.9

package/dist/ordinal.js

@@ -0,0 +1,249 @@
+"use strict";
+/**
+ * Phase 3: Ordinal Intent Detection for Semantic Search
+ *
+ * This module provides functions to detect ordinal intent in natural language goals
+ * and select elements based on their position within groups.
+ *
+ * Ordinal operators supported:
+ * - Position-based: "first", "second", "third", "1st", "2nd", "3rd", etc.
+ * - Relative: "top", "bottom", "last", "next", "previous"
+ * - Numeric: "#1", "#2", "number 1", "item 3"
+ *
+ * @example
+ * ```typescript
+ * import { detectOrdinalIntent, selectByOrdinal } from 'sentience';
+ *
+ * const intent = detectOrdinalIntent("click the first search result");
+ * // { detected: true, kind: 'nth', n: 1 }
+ *
+ * const element = selectByOrdinal(elements, "x5-w2-h1", intent);
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectOrdinalIntent = detectOrdinalIntent;
+exports.selectByOrdinal = selectByOrdinal;
+exports.boostOrdinalElements = boostOrdinalElements;
+/** Ordinal word to number mapping */
+const ORDINAL_WORDS = {
+    first: 1,
+    second: 2,
+    third: 3,
+    fourth: 4,
+    fifth: 5,
+    sixth: 6,
+    seventh: 7,
+    eighth: 8,
+    ninth: 9,
+    tenth: 10,
+    '1st': 1,
+    '2nd': 2,
+    '3rd': 3,
+    '4th': 4,
+    '5th': 5,
+    '6th': 6,
+    '7th': 7,
+    '8th': 8,
+    '9th': 9,
+    '10th': 10,
+};
+/** Patterns for detecting ordinal intent */
+const ORDINAL_PATTERNS = [
+    // "first", "second", etc.
+    {
+        pattern: /\b(first|second|third|fourth|fifth|sixth|seventh|eighth|ninth|tenth)\b/i,
+        type: 'ordinal_word',
+    },
+    // "1st", "2nd", "3rd", etc.
+    { pattern: /\b(\d+)(st|nd|rd|th)\b/i, type: 'ordinal_suffix' },
+    // "#1", "#2", etc.
+    { pattern: /#(\d+)\b/, type: 'hash_number' },
+    // "number 1", "item 3", "result 5"
+    { pattern: /\b(?:number|item|result|option|choice)\s*(\d+)\b/i, type: 'labeled_number' },
+    // "top" (implies first/best)
+    { pattern: /\btop\b(?!\s*\d)/i, type: 'top' },
+    // "top 3", "top 5"
+    { pattern: /\btop\s+(\d+)\b/i, type: 'top_k' },
+    // "last", "final", "bottom"
+    { pattern: /\b(last|final|bottom)\b/i, type: 'last' },
+    // "next", "following"
+    { pattern: /\b(next|following)\b/i, type: 'next' },
+    // "previous", "preceding", "prior"
+    { pattern: /\b(previous|preceding|prior)\b/i, type: 'previous' },
+];
+/**
+ * Detect ordinal intent from a goal string.
+ *
+ * @param goal - Natural language goal (e.g., "click the first search result")
+ * @returns OrdinalIntent with detected=true if ordinal intent found
+ *
+ * @example
+ * ```typescript
+ * detectOrdinalIntent("click the first item")
+ * // { detected: true, kind: 'nth', n: 1 }
+ *
+ * detectOrdinalIntent("select the 3rd option")
+ * // { detected: true, kind: 'nth', n: 3 }
+ *
+ * detectOrdinalIntent("show top 5 results")
+ * // { detected: true, kind: 'top_k', k: 5 }
+ *
+ * detectOrdinalIntent("find the submit button")
+ * // { detected: false }
+ * ```
+ */
+function detectOrdinalIntent(goal) {
+    const goalLower = goal.toLowerCase();
+    for (const { pattern, type } of ORDINAL_PATTERNS) {
+        const match = goalLower.match(pattern);
+        if (match) {
+            switch (type) {
+                case 'ordinal_word': {
+                    const word = match[1].toLowerCase();
+                    const n = ORDINAL_WORDS[word];
+                    if (n) {
+                        return { detected: true, kind: 'nth', n };
+                    }
+                    break;
+                }
+                case 'ordinal_suffix': {
+                    const n = parseInt(match[1], 10);
+                    return { detected: true, kind: 'nth', n };
+                }
+                case 'hash_number': {
+                    const n = parseInt(match[1], 10);
+                    return { detected: true, kind: 'nth', n };
+                }
+                case 'labeled_number': {
+                    const n = parseInt(match[1], 10);
+                    return { detected: true, kind: 'nth', n };
+                }
+                case 'top':
+                    // "top" without a number means "first/best"
+                    return { detected: true, kind: 'first' };
+                case 'top_k': {
+                    const k = parseInt(match[1], 10);
+                    return { detected: true, kind: 'top_k', k };
+                }
+                case 'last':
+                    return { detected: true, kind: 'last' };
+                case 'next':
+                    return { detected: true, kind: 'next' };
+                case 'previous':
+                    return { detected: true, kind: 'previous' };
+            }
+        }
+    }
+    return { detected: false };
+}
+/**
+ * Select element(s) from a list based on ordinal intent.
+ *
+ * Uses the dominantGroupKey to filter to the "main content" group,
+ * then selects by group_index based on the ordinal intent.
+ *
+ * @param elements - List of elements with group_key and group_index populated
+ * @param dominantGroupKey - The most common group key (main content group)
+ * @param intent - Detected ordinal intent
+ * @param currentElementId - Current element ID (for next/previous navigation)
+ * @returns Single Element for nth/first/last, array of Elements for top_k, or null
+ *
+ * @example
+ * ```typescript
+ * const intent = { detected: true, kind: 'nth', n: 1 };
+ * const element = selectByOrdinal(elements, "x5-w2-h1", intent);
+ * // Returns element with group_key="x5-w2-h1" and group_index=0
+ * ```
+ */
+function selectByOrdinal(elements, dominantGroupKey, intent, currentElementId) {
+    if (!intent.detected) {
+        return null;
+    }
+    // Filter to dominant group if available
+    let groupElements;
+    if (dominantGroupKey) {
+        groupElements = elements.filter(e => e.group_key === dominantGroupKey);
+    }
+    else {
+        // Fallback: use all elements with group_index
+        groupElements = elements.filter(e => e.group_index !== undefined);
+    }
+    if (groupElements.length === 0) {
+        return null;
+    }
+    // Sort by group_index to ensure correct ordering
+    groupElements.sort((a, b) => (a.group_index ?? 0) - (b.group_index ?? 0));
+    switch (intent.kind) {
+        case 'first':
+            return groupElements[0] ?? null;
+        case 'nth':
+            if (intent.n !== undefined) {
+                // Nth element (1-indexed, so n=2 means group_index=1)
+                const targetIndex = intent.n - 1;
+                if (targetIndex >= 0 && targetIndex < groupElements.length) {
+                    return groupElements[targetIndex];
+                }
+            }
+            return null;
+        case 'last':
+            return groupElements[groupElements.length - 1] ?? null;
+        case 'top_k':
+            if (intent.k !== undefined) {
+                return groupElements.slice(0, intent.k);
+            }
+            return null;
+        case 'next':
+            if (currentElementId !== undefined) {
+                for (let i = 0; i < groupElements.length; i++) {
+                    if (groupElements[i].id === currentElementId && i + 1 < groupElements.length) {
+                        return groupElements[i + 1];
+                    }
+                }
+            }
+            return null;
+        case 'previous':
+            if (currentElementId !== undefined) {
+                for (let i = 0; i < groupElements.length; i++) {
+                    if (groupElements[i].id === currentElementId && i > 0) {
+                        return groupElements[i - 1];
+                    }
+                }
+            }
+            return null;
+        default:
+            return null;
+    }
+}
+/**
+ * Boost the importance of elements matching ordinal intent.
+ *
+ * This is useful for integrating ordinal selection with existing
+ * importance-based ranking. Elements matching the ordinal intent
+ * get a significant importance boost.
+ *
+ * @param elements - List of elements (not modified)
+ * @param dominantGroupKey - The most common group key
+ * @param intent - Detected ordinal intent
+ * @param boostFactor - Amount to add to importance (default: 10000)
+ * @returns A new array with copies of elements, with boosted importance for matches
+ */
+function boostOrdinalElements(elements, dominantGroupKey, intent, boostFactor = 10000) {
+    if (!intent.detected || !dominantGroupKey) {
+        return elements.map(e => ({ ...e }));
+    }
+    const target = selectByOrdinal(elements, dominantGroupKey, intent);
+    if (target === null) {
+        return elements.map(e => ({ ...e }));
+    }
+    // Handle single element or array
+    const targetIds = new Set(Array.isArray(target) ? target.map(e => e.id) : [target.id]);
+    // Create copies and boost matching elements
+    return elements.map(elem => {
+        const copy = { ...elem };
+        if (targetIds.has(copy.id)) {
+            copy.importance = (copy.importance ?? 0) + boostFactor;
+        }
+        return copy;
+    });
+}
+//# sourceMappingURL=ordinal.js.map

package/dist/ordinal.js.map

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

package/dist/overlay.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Visual overlay utilities - show/clear element highlights in browser
+ */
+import { SentienceBrowser } from './browser';
+import { Element, Snapshot } from './types';
+/**
+ * Display visual overlay highlighting elements in the browser
+ *
+ * This function shows a Shadow DOM overlay with color-coded borders around
+ * detected elements. Useful for debugging, learning, and validating element detection.
+ *
+ * @param browser - SentienceBrowser instance
+ * @param elements - Can be:
+ *   - List of Element objects (from snapshot.elements)
+ *   - List of raw element objects (from snapshot result or API response)
+ *   - Snapshot object (will use snapshot.elements)
+ * @param targetElementId - Optional ID of element to highlight in red (default: null)
+ *
+ * Color Coding:
+ *   - Red: Target element (when targetElementId 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
+ * const snap = await snapshot(browser);
+ * await showOverlay(browser, snap);
+ *
+ * @example
+ * // Show overlay with custom elements
+ * const elements = [{id: 1, bbox: {x: 100, y: 100, width: 200, height: 50}, ...}];
+ * await showOverlay(browser, elements);
+ *
+ * @example
+ * // Show overlay with target element highlighted in red
+ * await showOverlay(browser, snap, 42);
+ *
+ * @example
+ * // Clear overlay manually before 5 seconds
+ * await clearOverlay(browser);
+ */
+export declare function showOverlay(browser: SentienceBrowser, elements: Element[] | any[] | Snapshot, targetElementId?: number | null): Promise<void>;
+/**
+ * Clear the visual overlay manually (before 5-second auto-clear)
+ *
+ * @param browser - SentienceBrowser instance
+ *
+ * @example
+ * await showOverlay(browser, snap);
+ * // ... inspect overlay ...
+ * await clearOverlay(browser);  // Remove immediately
+ */
+export declare function clearOverlay(browser: SentienceBrowser): Promise<void>;
+//# sourceMappingURL=overlay.d.ts.map

package/dist/overlay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"overlay.d.ts","sourceRoot":"","sources":["../src/overlay.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAE5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,wBAAsB,WAAW,CAC/B,OAAO,EAAE,gBAAgB,EACzB,QAAQ,EAAE,OAAO,EAAE,GAAG,GAAG,EAAE,GAAG,QAAQ,EACtC,eAAe,GAAE,MAAM,GAAG,IAAW,GACpC,OAAO,CAAC,IAAI,CAAC,CA6Bf;AAED;;;;;;;;;GASG;AACH,wBAAsB,YAAY,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAW3E"}

package/dist/overlay.js

@@ -0,0 +1,102 @@
+"use strict";
+/**
+ * Visual overlay utilities - show/clear element highlights in browser
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.showOverlay = showOverlay;
+exports.clearOverlay = clearOverlay;
+/**
+ * Display visual overlay highlighting elements in the browser
+ *
+ * This function shows a Shadow DOM overlay with color-coded borders around
+ * detected elements. Useful for debugging, learning, and validating element detection.
+ *
+ * @param browser - SentienceBrowser instance
+ * @param elements - Can be:
+ *   - List of Element objects (from snapshot.elements)
+ *   - List of raw element objects (from snapshot result or API response)
+ *   - Snapshot object (will use snapshot.elements)
+ * @param targetElementId - Optional ID of element to highlight in red (default: null)
+ *
+ * Color Coding:
+ *   - Red: Target element (when targetElementId 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
+ * const snap = await snapshot(browser);
+ * await showOverlay(browser, snap);
+ *
+ * @example
+ * // Show overlay with custom elements
+ * const elements = [{id: 1, bbox: {x: 100, y: 100, width: 200, height: 50}, ...}];
+ * await showOverlay(browser, elements);
+ *
+ * @example
+ * // Show overlay with target element highlighted in red
+ * await showOverlay(browser, snap, 42);
+ *
+ * @example
+ * // Clear overlay manually before 5 seconds
+ * await clearOverlay(browser);
+ */
+async function showOverlay(browser, elements, targetElementId = null) {
+    const page = browser.getPage();
+    if (!page) {
+        throw new Error('Browser not started. Call start() first.');
+    }
+    // Handle different input types
+    let elementsList;
+    if ('elements' in elements && Array.isArray(elements.elements)) {
+        // It's a Snapshot object
+        elementsList = elements.elements;
+    }
+    else if (Array.isArray(elements)) {
+        // It's already an array
+        elementsList = elements;
+    }
+    else {
+        throw new Error('elements must be a Snapshot object or array of elements');
+    }
+    // Call extension API
+    await 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: elementsList, targetId: targetElementId });
+}
+/**
+ * Clear the visual overlay manually (before 5-second auto-clear)
+ *
+ * @param browser - SentienceBrowser instance
+ *
+ * @example
+ * await showOverlay(browser, snap);
+ * // ... inspect overlay ...
+ * await clearOverlay(browser);  // Remove immediately
+ */
+async function clearOverlay(browser) {
+    const page = browser.getPage();
+    if (!page) {
+        throw new Error('Browser not started. Call start() first.');
+    }
+    await page.evaluate(() => {
+        if (window.sentience && window.sentience.clearOverlay) {
+            window.sentience.clearOverlay();
+        }
+    });
+}
+//# sourceMappingURL=overlay.js.map

package/dist/overlay.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"overlay.js","sourceRoot":"","sources":["../src/overlay.ts"],"names":[],"mappings":";AAAA;;GAEG;;AAkDH,kCAiCC;AAYD,oCAWC;AArGD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACI,KAAK,UAAU,WAAW,CAC/B,OAAyB,EACzB,QAAsC,EACtC,kBAAiC,IAAI;IAErC,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IAC/B,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAC;IAC9D,CAAC;IAED,+BAA+B;IAC/B,IAAI,YAAmB,CAAC;IACxB,IAAI,UAAU,IAAI,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC/D,yBAAyB;QACzB,YAAY,GAAG,QAAQ,CAAC,QAAQ,CAAC;IACnC,CAAC;SAAM,IAAI,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;QACnC,wBAAwB;QACxB,YAAY,GAAG,QAAQ,CAAC;IAC1B,CAAC;SAAM,CAAC;QACN,MAAM,IAAI,KAAK,CAAC,yDAAyD,CAAC,CAAC;IAC7E,CAAC;IAED,qBAAqB;IACrB,MAAM,IAAI,CAAC,QAAQ,CACjB,CAAC,IAAkD,EAAE,EAAE;QACrD,IAAK,MAAc,CAAC,SAAS,IAAK,MAAc,CAAC,SAAS,CAAC,WAAW,EAAE,CAAC;YACtE,MAAc,CAAC,SAAS,CAAC,WAAW,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;QACtE,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,IAAI,CAAC,kEAAkE,CAAC,CAAC;QACnF,CAAC;IACH,CAAC,EACD,EAAE,QAAQ,EAAE,YAAY,EAAE,QAAQ,EAAE,eAAe,EAAE,CACtD,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACI,KAAK,UAAU,YAAY,CAAC,OAAyB;IAC1D,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IAC/B,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAC;IAC9D,CAAC;IAED,MAAM,IAAI,CAAC,QAAQ,CAAC,GAAG,EAAE;QACvB,IAAK,MAAc,CAAC,SAAS,IAAK,MAAc,CAAC,SAAS,CAAC,YAAY,EAAE,CAAC;YACvE,MAAc,CAAC,SAAS,CAAC,YAAY,EAAE,CAAC;QAC3C,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/protocols/browser-protocol.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Browser Protocol Interfaces for Testability
+ *
+ * These interfaces allow classes to depend on abstractions rather than concrete implementations,
+ * making them easier to test with mocks.
+ */
+import { Page } from 'playwright';
+import { Snapshot } from '../types';
+import { SnapshotOptions } from '../snapshot';
+/**
+ * Interface for browser operations
+ * Allows mocking SentienceBrowser for testing
+ */
+export interface IBrowser {
+    /**
+     * Navigate to a URL
+     */
+    goto(url: string): Promise<void>;
+    /**
+     * Take a snapshot of the current page
+     */
+    snapshot(options?: SnapshotOptions): Promise<Snapshot>;
+    /**
+     * Get the underlying Playwright Page object
+     */
+    getPage(): Page | null;
+    /**
+     * Get the browser context
+     */
+    getContext(): any | null;
+    /**
+     * Get API key if configured
+     */
+    getApiKey(): string | undefined;
+    /**
+     * Get API URL if configured
+     */
+    getApiUrl(): string | undefined;
+}
+/**
+ * Interface for page operations
+ * Allows mocking Playwright Page for testing
+ */
+export interface IPage {
+    /**
+     * Evaluate JavaScript in the page context
+     */
+    evaluate<T>(script: string | ((...args: any[]) => T), ...args: any[]): Promise<T>;
+    /**
+     * Get current page URL
+     */
+    url(): string;
+    /**
+     * Navigate to a URL
+     */
+    goto(url: string, options?: any): Promise<any>;
+    /**
+     * Wait for a function to return truthy value
+     */
+    waitForFunction(fn: () => boolean | Promise<boolean>, options?: any): Promise<void>;
+    /**
+     * Wait for timeout
+     */
+    waitForTimeout(ms: number): Promise<void>;
+    /**
+     * Get page mouse
+     */
+    mouse: {
+        click(x: number, y: number): Promise<void>;
+    };
+    /**
+     * Get page keyboard
+     */
+    keyboard: {
+        type(text: string): Promise<void>;
+        press(key: string): Promise<void>;
+    };
+}
+//# sourceMappingURL=browser-protocol.d.ts.map

package/dist/protocols/browser-protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-protocol.d.ts","sourceRoot":"","sources":["../../src/protocols/browser-protocol.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAClC,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AACpC,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C;;;GAGG;AACH,MAAM,WAAW,QAAQ;IACvB;;OAEG;IACH,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjC;;OAEG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAEvD;;OAEG;IACH,OAAO,IAAI,IAAI,GAAG,IAAI,CAAC;IAEvB;;OAEG;IAEH,UAAU,IAAI,GAAG,GAAG,IAAI,CAAC;IAEzB;;OAEG;IACH,SAAS,IAAI,MAAM,GAAG,SAAS,CAAC;IAEhC;;OAEG;IACH,SAAS,IAAI,MAAM,GAAG,SAAS,CAAC;CACjC;AAED;;;GAGG;AACH,MAAM,WAAW,KAAK;IACpB;;OAEG;IAEH,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,GAAG,CAAC,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAElF;;OAEG;IACH,GAAG,IAAI,MAAM,CAAC;IAEd;;OAEG;IACH,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAE/C;;OAEG;IACH,eAAe,CAAC,EAAE,EAAE,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEpF;;OAEG;IACH,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE1C;;OAEG;IACH,KAAK,EAAE;QACL,KAAK,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;KAC5C,CAAC;IAEF;;OAEG;IACH,QAAQ,EAAE;QACR,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QAClC,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;KACnC,CAAC;CACH"}

package/dist/protocols/browser-protocol.js

@@ -0,0 +1,9 @@
+"use strict";
+/**
+ * Browser Protocol Interfaces for Testability
+ *
+ * These interfaces allow classes to depend on abstractions rather than concrete implementations,
+ * making them easier to test with mocks.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=browser-protocol.js.map

package/dist/protocols/browser-protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-protocol.js","sourceRoot":"","sources":["../../src/protocols/browser-protocol.ts"],"names":[],"mappings":";AAAA;;;;;GAKG"}

package/dist/query.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Query engine v1 - semantic selector matching
+ */
+import { Snapshot, Element, QuerySelector, QuerySelectorObject } from './types';
+/**
+ * Parse a selector string into a QuerySelectorObject
+ *
+ * Supports operators: =, !=, ~, ^=, $=, >, >=, <, <=
+ * Supports dot notation: attr.id, css.color, bbox.x
+ *
+ * @param selector - Selector string (e.g., "role=button", "text~search", "importance>0.5")
+ * @returns Parsed query object
+ *
+ * @example
+ * ```typescript
+ * const query = parseSelector('role=button clickable=true importance>0.5');
+ * // Returns: { role: 'button', clickable: true, importance_min: 0.5 }
+ * ```
+ */
+export declare function parseSelector(selector: string): QuerySelectorObject;
+/**
+ * Query elements from a snapshot using a selector
+ *
+ * @param snapshot - Snapshot containing elements to query
+ * @param selector - Query selector (string DSL or object)
+ * @returns Array of matching elements, sorted by importance (descending)
+ *
+ * @example
+ * ```typescript
+ * const snap = await snapshot(browser);
+ *
+ * // String selector
+ * const buttons = query(snap, 'role=button');
+ * const clickable = query(snap, 'clickable=true');
+ *
+ * // Object selector
+ * const results = query(snap, {
+ *   role: 'button',
+ *   importance_min: 0.5
+ * });
+ * ```
+ */
+export declare function query(snapshot: Snapshot, selector: QuerySelector): Element[];
+/**
+ * Find the first element matching a selector
+ *
+ * @param snapshot - Snapshot containing elements to search
+ * @param selector - Query selector (string DSL or object)
+ * @returns First matching element, or null if none found
+ *
+ * @example
+ * ```typescript
+ * const snap = await snapshot(browser);
+ *
+ * // Find first button
+ * const button = find(snap, 'role=button');
+ * if (button) {
+ *   await click(browser, button.id);
+ * }
+ *
+ * // Find element by text
+ * const searchBox = find(snap, 'text~search');
+ * ```
+ */
+export declare function find(snapshot: Snapshot, selector: QuerySelector): Element | null;
+//# sourceMappingURL=query.d.ts.map

package/dist/query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../src/query.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAEhF;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,mBAAmB,CA8KnE;AAsQD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,KAAK,CAAC,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,aAAa,GAAG,OAAO,EAAE,CAW5E;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,IAAI,CAAC,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,aAAa,GAAG,OAAO,GAAG,IAAI,CAGhF"}