sentienceapi 0.92.2 → 0.93.0

package/dist/canonicalization.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Shared canonicalization utilities for snapshot comparison and indexing.
+ *
+ * This module provides consistent normalization functions used by both:
+ * - tracing/indexer.ts (for computing stable digests)
+ * - snapshot-diff.ts (for computing diff_status labels)
+ *
+ * By sharing these helpers, we ensure consistent behavior:
+ * - Same text normalization (whitespace, case, length)
+ * - Same bbox rounding (2px precision)
+ * - Same change detection thresholds
+ */
+export interface BBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface VisualCues {
+    is_primary?: boolean;
+    is_clickable?: boolean;
+}
+export interface ElementData {
+    id?: number;
+    role?: string;
+    text?: string | null;
+    bbox?: BBox;
+    visual_cues?: VisualCues;
+    is_primary?: boolean;
+    is_clickable?: boolean;
+}
+export interface CanonicalElement {
+    id: number | undefined;
+    role: string;
+    text_norm: string;
+    bbox: BBox;
+    is_primary: boolean;
+    is_clickable: boolean;
+}
+/**
+ * Normalize text for canonical comparison.
+ *
+ * Transforms:
+ * - Trims leading/trailing whitespace
+ * - Collapses internal whitespace to single spaces
+ * - Lowercases
+ * - Caps length
+ *
+ * @param text - Input text (may be undefined/null)
+ * @param maxLen - Maximum length to retain (default: 80)
+ * @returns Normalized text string (empty string if input is falsy)
+ *
+ * @example
+ * normalizeText("  Hello   World  ") // "hello world"
+ * normalizeText(undefined) // ""
+ */
+export declare function normalizeText(text: string | undefined | null, maxLen?: number): string;
+/**
+ * Round bbox coordinates to reduce noise.
+ *
+ * Snaps coordinates to grid of `precision` pixels to ignore
+ * sub-pixel rendering differences.
+ *
+ * @param bbox - Bounding box with x, y, width, height
+ * @param precision - Grid size in pixels (default: 2)
+ * @returns Rounded bbox with integer coordinates
+ *
+ * @example
+ * roundBBox({x: 101, y: 203, width: 50, height: 25})
+ * // {x: 100, y: 202, width: 50, height: 24}
+ */
+export declare function roundBBox(bbox: Partial<BBox>, precision?: number): BBox;
+/**
+ * Check if two bboxes are equal within a threshold.
+ *
+ * @param bbox1 - First bounding box
+ * @param bbox2 - Second bounding box
+ * @param threshold - Maximum allowed difference in pixels (default: 5.0)
+ * @returns True if all bbox properties differ by less than threshold
+ */
+export declare function bboxEqual(bbox1: Partial<BBox>, bbox2: Partial<BBox>, threshold?: number): boolean;
+/**
+ * Check if two bboxes differ beyond the threshold.
+ *
+ * This is the inverse of bboxEqual, provided for semantic clarity
+ * in diff detection code.
+ *
+ * @param bbox1 - First bounding box
+ * @param bbox2 - Second bounding box
+ * @param threshold - Maximum allowed difference in pixels (default: 5.0)
+ * @returns True if any bbox property differs by more than threshold
+ */
+export declare function bboxChanged(bbox1: Partial<BBox>, bbox2: Partial<BBox>, threshold?: number): boolean;
+/**
+ * Create canonical representation of an element for comparison/hashing.
+ *
+ * Extracts and normalizes the fields that matter for identity:
+ * - id, role, normalized text, rounded bbox
+ * - is_primary, is_clickable from visual_cues
+ *
+ * @param elem - Raw element object
+ * @returns Canonical element object with normalized fields
+ */
+export declare function canonicalizeElement(elem: ElementData): CanonicalElement;
+/**
+ * Check if two elements have equal content (ignoring position).
+ *
+ * Compares normalized text, role, and visual cues.
+ *
+ * @param elem1 - First element (raw or canonical)
+ * @param elem2 - Second element (raw or canonical)
+ * @returns True if content is equal after normalization
+ */
+export declare function contentEqual(elem1: ElementData, elem2: ElementData): boolean;
+/**
+ * Check if two elements have different content (ignoring position).
+ *
+ * This is the inverse of contentEqual, provided for semantic clarity
+ * in diff detection code.
+ *
+ * @param elem1 - First element
+ * @param elem2 - Second element
+ * @returns True if content differs after normalization
+ */
+export declare function contentChanged(elem1: ElementData, elem2: ElementData): boolean;
+//# sourceMappingURL=canonicalization.d.ts.map

package/dist/canonicalization.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonicalization.d.ts","sourceRoot":"","sources":["../src/canonicalization.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,IAAI;IACnB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,UAAU;IACzB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,WAAW;IAC1B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,IAAI,CAAC,EAAE,IAAI,CAAC;IACZ,WAAW,CAAC,EAAE,UAAU,CAAC;IACzB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,GAAG,SAAS,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,IAAI,CAAC;IACX,UAAU,EAAE,OAAO,CAAC;IACpB,YAAY,EAAE,OAAO,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,EAAE,MAAM,GAAE,MAAW,GAAG,MAAM,CAe1F;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,EAAE,SAAS,GAAE,MAAU,GAAG,IAAI,CAO1E;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CACvB,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,EACpB,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,EACpB,SAAS,GAAE,MAAY,GACtB,OAAO,CAOT;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,EACpB,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,EACpB,SAAS,GAAE,MAAY,GACtB,OAAO,CAET;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,WAAW,GAAG,gBAAgB,CAoBvE;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,WAAW,GAAG,OAAO,CAW5E;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,WAAW,GAAG,OAAO,CAE9E"}

package/dist/canonicalization.js

@@ -0,0 +1,161 @@
+"use strict";
+/**
+ * Shared canonicalization utilities for snapshot comparison and indexing.
+ *
+ * This module provides consistent normalization functions used by both:
+ * - tracing/indexer.ts (for computing stable digests)
+ * - snapshot-diff.ts (for computing diff_status labels)
+ *
+ * By sharing these helpers, we ensure consistent behavior:
+ * - Same text normalization (whitespace, case, length)
+ * - Same bbox rounding (2px precision)
+ * - Same change detection thresholds
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeText = normalizeText;
+exports.roundBBox = roundBBox;
+exports.bboxEqual = bboxEqual;
+exports.bboxChanged = bboxChanged;
+exports.canonicalizeElement = canonicalizeElement;
+exports.contentEqual = contentEqual;
+exports.contentChanged = contentChanged;
+/**
+ * Normalize text for canonical comparison.
+ *
+ * Transforms:
+ * - Trims leading/trailing whitespace
+ * - Collapses internal whitespace to single spaces
+ * - Lowercases
+ * - Caps length
+ *
+ * @param text - Input text (may be undefined/null)
+ * @param maxLen - Maximum length to retain (default: 80)
+ * @returns Normalized text string (empty string if input is falsy)
+ *
+ * @example
+ * normalizeText("  Hello   World  ") // "hello world"
+ * normalizeText(undefined) // ""
+ */
+function normalizeText(text, maxLen = 80) {
+    if (!text)
+        return '';
+    // Trim and collapse whitespace
+    let normalized = text.split(/\s+/).join(' ').trim();
+    // Lowercase
+    normalized = normalized.toLowerCase();
+    // Cap length
+    if (normalized.length > maxLen) {
+        normalized = normalized.substring(0, maxLen);
+    }
+    return normalized;
+}
+/**
+ * Round bbox coordinates to reduce noise.
+ *
+ * Snaps coordinates to grid of `precision` pixels to ignore
+ * sub-pixel rendering differences.
+ *
+ * @param bbox - Bounding box with x, y, width, height
+ * @param precision - Grid size in pixels (default: 2)
+ * @returns Rounded bbox with integer coordinates
+ *
+ * @example
+ * roundBBox({x: 101, y: 203, width: 50, height: 25})
+ * // {x: 100, y: 202, width: 50, height: 24}
+ */
+function roundBBox(bbox, precision = 2) {
+    return {
+        x: Math.round((bbox.x || 0) / precision) * precision,
+        y: Math.round((bbox.y || 0) / precision) * precision,
+        width: Math.round((bbox.width || 0) / precision) * precision,
+        height: Math.round((bbox.height || 0) / precision) * precision,
+    };
+}
+/**
+ * Check if two bboxes are equal within a threshold.
+ *
+ * @param bbox1 - First bounding box
+ * @param bbox2 - Second bounding box
+ * @param threshold - Maximum allowed difference in pixels (default: 5.0)
+ * @returns True if all bbox properties differ by less than threshold
+ */
+function bboxEqual(bbox1, bbox2, threshold = 5.0) {
+    return (Math.abs((bbox1.x || 0) - (bbox2.x || 0)) <= threshold &&
+        Math.abs((bbox1.y || 0) - (bbox2.y || 0)) <= threshold &&
+        Math.abs((bbox1.width || 0) - (bbox2.width || 0)) <= threshold &&
+        Math.abs((bbox1.height || 0) - (bbox2.height || 0)) <= threshold);
+}
+/**
+ * Check if two bboxes differ beyond the threshold.
+ *
+ * This is the inverse of bboxEqual, provided for semantic clarity
+ * in diff detection code.
+ *
+ * @param bbox1 - First bounding box
+ * @param bbox2 - Second bounding box
+ * @param threshold - Maximum allowed difference in pixels (default: 5.0)
+ * @returns True if any bbox property differs by more than threshold
+ */
+function bboxChanged(bbox1, bbox2, threshold = 5.0) {
+    return !bboxEqual(bbox1, bbox2, threshold);
+}
+/**
+ * Create canonical representation of an element for comparison/hashing.
+ *
+ * Extracts and normalizes the fields that matter for identity:
+ * - id, role, normalized text, rounded bbox
+ * - is_primary, is_clickable from visual_cues
+ *
+ * @param elem - Raw element object
+ * @returns Canonical element object with normalized fields
+ */
+function canonicalizeElement(elem) {
+    // Extract is_primary and is_clickable from visual_cues if present
+    const visualCues = elem.visual_cues || {};
+    const isPrimary = typeof visualCues === 'object' && visualCues !== null
+        ? visualCues.is_primary || false
+        : elem.is_primary || false;
+    const isClickable = typeof visualCues === 'object' && visualCues !== null
+        ? visualCues.is_clickable || false
+        : elem.is_clickable || false;
+    return {
+        id: elem.id,
+        role: elem.role || '',
+        text_norm: normalizeText(elem.text),
+        bbox: roundBBox(elem.bbox || { x: 0, y: 0, width: 0, height: 0 }),
+        is_primary: isPrimary,
+        is_clickable: isClickable,
+    };
+}
+/**
+ * Check if two elements have equal content (ignoring position).
+ *
+ * Compares normalized text, role, and visual cues.
+ *
+ * @param elem1 - First element (raw or canonical)
+ * @param elem2 - Second element (raw or canonical)
+ * @returns True if content is equal after normalization
+ */
+function contentEqual(elem1, elem2) {
+    // Normalize both elements
+    const c1 = canonicalizeElement(elem1);
+    const c2 = canonicalizeElement(elem2);
+    return (c1.role === c2.role &&
+        c1.text_norm === c2.text_norm &&
+        c1.is_primary === c2.is_primary &&
+        c1.is_clickable === c2.is_clickable);
+}
+/**
+ * Check if two elements have different content (ignoring position).
+ *
+ * This is the inverse of contentEqual, provided for semantic clarity
+ * in diff detection code.
+ *
+ * @param elem1 - First element
+ * @param elem2 - Second element
+ * @returns True if content differs after normalization
+ */
+function contentChanged(elem1, elem2) {
+    return !contentEqual(elem1, elem2);
+}
+//# sourceMappingURL=canonicalization.js.map

package/dist/canonicalization.js.map

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

package/dist/index.d.ts

@@ -4,7 +4,7 @@
 export { SentienceBrowser } from './browser';
 export { snapshot, SnapshotOptions } from './snapshot';
 export { query, find, parseSelector } from './query';
-export { click, typeText, press, clickRect, ClickRect } from './actions';
+export { click, typeText, press, scrollTo, clickRect, ClickRect } from './actions';
 export { waitFor } from './wait';
 export { expect, Expectation } from './expect';
 export { Inspector, inspect } from './inspector';
@@ -21,4 +21,7 @@ export { SentienceAgent, AgentActResult, HistoryEntry, TokenStats } from './agen
 export { SentienceVisualAgent } from './visual-agent';
 export { ConversationalAgent, ExecutionPlan, PlanStep, StepResult, ConversationEntry, ActionType, ActionParameters, } from './conversational-agent';
 export { Tracer, TraceSink, JsonlTraceSink, TraceEvent, TraceEventData } from './tracing';
+export { AssertOutcome, AssertContext, Predicate, urlMatches, urlContains, exists, notExists, elementCount, allOf, anyOf, custom, } from './verification';
+export { AgentRuntime, AssertionRecord } from './agent-runtime';
+export { OrdinalIntent, OrdinalKind, detectOrdinalIntent, selectByOrdinal, boostOrdinalElements, } from './ordinal';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AACvD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACrD,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACzE,OAAO,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AACjC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAC/C,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAChE,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AACvD,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAC7D,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACtD,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,cAAc,SAAS,CAAC;AACxB,OAAO,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAG3C,OAAO,EACL,WAAW,EACX,WAAW,EACX,cAAc,EACd,iBAAiB,EACjB,WAAW,GACZ,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACnF,OAAO,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAGtD,OAAO,EACL,mBAAmB,EACnB,aAAa,EACb,QAAQ,EACR,UAAU,EACV,iBAAiB,EACjB,UAAU,EACV,gBAAgB,GACjB,MAAM,wBAAwB,CAAC;AAGhC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,cAAc,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AACvD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACrD,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACnF,OAAO,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AACjC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAC/C,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAChE,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AACvD,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAC7D,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACtD,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,cAAc,SAAS,CAAC;AACxB,OAAO,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAG3C,OAAO,EACL,WAAW,EACX,WAAW,EACX,cAAc,EACd,iBAAiB,EACjB,WAAW,GACZ,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACnF,OAAO,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAGtD,OAAO,EACL,mBAAmB,EACnB,aAAa,EACb,QAAQ,EACR,UAAU,EACV,iBAAiB,EACjB,UAAU,EACV,gBAAgB,GACjB,MAAM,wBAAwB,CAAC;AAGhC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,cAAc,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAG1F,OAAO,EACL,aAAa,EACb,aAAa,EACb,SAAS,EACT,UAAU,EACV,WAAW,EACX,MAAM,EACN,SAAS,EACT,YAAY,EACZ,KAAK,EACL,KAAK,EACL,MAAM,GACP,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAGhE,OAAO,EACL,aAAa,EACb,WAAW,EACX,mBAAmB,EACnB,eAAe,EACf,oBAAoB,GACrB,MAAM,WAAW,CAAC"}

package/dist/index.js

@@ -17,7 +17,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.JsonlTraceSink = exports.TraceSink = exports.Tracer = exports.ConversationalAgent = exports.SentienceVisualAgent = exports.SentienceAgent = exports.GLMProvider = exports.AnthropicProvider = exports.OpenAIProvider = exports.LLMProvider = exports.saveStorageState = exports.findTextRect = exports.clearOverlay = exports.showOverlay = exports.screenshot = exports.read = exports.generate = exports.ScriptGenerator = exports.record = exports.Recorder = exports.inspect = exports.Inspector = exports.Expectation = exports.expect = exports.waitFor = exports.clickRect = exports.press = exports.typeText = exports.click = exports.parseSelector = exports.find = exports.query = exports.snapshot = exports.SentienceBrowser = void 0;
+exports.boostOrdinalElements = exports.selectByOrdinal = exports.detectOrdinalIntent = exports.AgentRuntime = exports.custom = exports.anyOf = exports.allOf = exports.elementCount = exports.notExists = exports.exists = exports.urlContains = exports.urlMatches = exports.JsonlTraceSink = exports.TraceSink = exports.Tracer = exports.ConversationalAgent = exports.SentienceVisualAgent = exports.SentienceAgent = exports.GLMProvider = exports.AnthropicProvider = exports.OpenAIProvider = exports.LLMProvider = exports.saveStorageState = exports.findTextRect = exports.clearOverlay = exports.showOverlay = exports.screenshot = exports.read = exports.generate = exports.ScriptGenerator = exports.record = exports.Recorder = exports.inspect = exports.Inspector = exports.Expectation = exports.expect = exports.waitFor = exports.clickRect = exports.press = exports.typeText = exports.click = exports.parseSelector = exports.find = exports.query = exports.snapshot = exports.SentienceBrowser = void 0;
 var browser_1 = require("./browser");
 Object.defineProperty(exports, "SentienceBrowser", { enumerable: true, get: function () { return browser_1.SentienceBrowser; } });
 var snapshot_1 = require("./snapshot");
@@ -30,6 +30,7 @@ var actions_1 = require("./actions");
 Object.defineProperty(exports, "click", { enumerable: true, get: function () { return actions_1.click; } });
 Object.defineProperty(exports, "typeText", { enumerable: true, get: function () { return actions_1.typeText; } });
 Object.defineProperty(exports, "press", { enumerable: true, get: function () { return actions_1.press; } });
+Object.defineProperty(exports, "scrollTo", { enumerable: true, get: function () { return actions_1.scrollTo; } });
 Object.defineProperty(exports, "clickRect", { enumerable: true, get: function () { return actions_1.clickRect; } });
 var wait_1 = require("./wait");
 Object.defineProperty(exports, "waitFor", { enumerable: true, get: function () { return wait_1.waitFor; } });
@@ -75,4 +76,21 @@ var tracing_1 = require("./tracing");
 Object.defineProperty(exports, "Tracer", { enumerable: true, get: function () { return tracing_1.Tracer; } });
 Object.defineProperty(exports, "TraceSink", { enumerable: true, get: function () { return tracing_1.TraceSink; } });
 Object.defineProperty(exports, "JsonlTraceSink", { enumerable: true, get: function () { return tracing_1.JsonlTraceSink; } });
+// Verification Layer (agent assertion loop)
+var verification_1 = require("./verification");
+Object.defineProperty(exports, "urlMatches", { enumerable: true, get: function () { return verification_1.urlMatches; } });
+Object.defineProperty(exports, "urlContains", { enumerable: true, get: function () { return verification_1.urlContains; } });
+Object.defineProperty(exports, "exists", { enumerable: true, get: function () { return verification_1.exists; } });
+Object.defineProperty(exports, "notExists", { enumerable: true, get: function () { return verification_1.notExists; } });
+Object.defineProperty(exports, "elementCount", { enumerable: true, get: function () { return verification_1.elementCount; } });
+Object.defineProperty(exports, "allOf", { enumerable: true, get: function () { return verification_1.allOf; } });
+Object.defineProperty(exports, "anyOf", { enumerable: true, get: function () { return verification_1.anyOf; } });
+Object.defineProperty(exports, "custom", { enumerable: true, get: function () { return verification_1.custom; } });
+var agent_runtime_1 = require("./agent-runtime");
+Object.defineProperty(exports, "AgentRuntime", { enumerable: true, get: function () { return agent_runtime_1.AgentRuntime; } });
+// Ordinal Support (Phase 3)
+var ordinal_1 = require("./ordinal");
+Object.defineProperty(exports, "detectOrdinalIntent", { enumerable: true, get: function () { return ordinal_1.detectOrdinalIntent; } });
+Object.defineProperty(exports, "selectByOrdinal", { enumerable: true, get: function () { return ordinal_1.selectByOrdinal; } });
+Object.defineProperty(exports, "boostOrdinalElements", { enumerable: true, get: function () { return ordinal_1.boostOrdinalElements; } });
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;GAEG;;;;;;;;;;;;;;;;;AAEH,qCAA6C;AAApC,2GAAA,gBAAgB,OAAA;AACzB,uCAAuD;AAA9C,oGAAA,QAAQ,OAAA;AACjB,iCAAqD;AAA5C,8FAAA,KAAK,OAAA;AAAE,6FAAA,IAAI,OAAA;AAAE,sGAAA,aAAa,OAAA;AACnC,qCAAyE;AAAhE,gGAAA,KAAK,OAAA;AAAE,mGAAA,QAAQ,OAAA;AAAE,gGAAA,KAAK,OAAA;AAAE,oGAAA,SAAS,OAAA;AAC1C,+BAAiC;AAAxB,+FAAA,OAAO,OAAA;AAChB,mCAA+C;AAAtC,gGAAA,MAAM,OAAA;AAAE,qGAAA,WAAW,OAAA;AAC5B,yCAAiD;AAAxC,sGAAA,SAAS,OAAA;AAAE,oGAAA,OAAO,OAAA;AAC3B,uCAAgE;AAAvD,oGAAA,QAAQ,OAAA;AAAoB,kGAAA,MAAM,OAAA;AAC3C,yCAAwD;AAA/C,4GAAA,eAAe,OAAA;AAAE,qGAAA,QAAQ,OAAA;AAClC,+BAAuD;AAA9C,4FAAA,IAAI,OAAA;AACb,2CAA6D;AAApD,wGAAA,UAAU,OAAA;AACnB,qCAAsD;AAA7C,sGAAA,WAAW,OAAA;AAAE,uGAAA,YAAY,OAAA;AAClC,2CAA4C;AAAnC,0GAAA,YAAY,OAAA;AACrB,0CAAwB;AACxB,iCAA2C;AAAlC,yGAAA,gBAAgB,OAAA;AAEzB,wBAAwB;AACxB,+CAMwB;AALtB,2GAAA,WAAW,OAAA;AAEX,8GAAA,cAAc,OAAA;AACd,iHAAA,iBAAiB,OAAA;AACjB,2GAAA,WAAW,OAAA;AAEb,iCAAmF;AAA1E,uGAAA,cAAc,OAAA;AACvB,+CAAsD;AAA7C,oHAAA,oBAAoB,OAAA;AAE7B,uCAAuC;AACvC,+DAQgC;AAP9B,2HAAA,mBAAmB,OAAA;AASrB,0BAA0B;AAC1B,qCAA0F;AAAjF,iGAAA,MAAM,OAAA;AAAE,oGAAA,SAAS,OAAA;AAAE,yGAAA,cAAc,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;GAEG;;;;;;;;;;;;;;;;;AAEH,qCAA6C;AAApC,2GAAA,gBAAgB,OAAA;AACzB,uCAAuD;AAA9C,oGAAA,QAAQ,OAAA;AACjB,iCAAqD;AAA5C,8FAAA,KAAK,OAAA;AAAE,6FAAA,IAAI,OAAA;AAAE,sGAAA,aAAa,OAAA;AACnC,qCAAmF;AAA1E,gGAAA,KAAK,OAAA;AAAE,mGAAA,QAAQ,OAAA;AAAE,gGAAA,KAAK,OAAA;AAAE,mGAAA,QAAQ,OAAA;AAAE,oGAAA,SAAS,OAAA;AACpD,+BAAiC;AAAxB,+FAAA,OAAO,OAAA;AAChB,mCAA+C;AAAtC,gGAAA,MAAM,OAAA;AAAE,qGAAA,WAAW,OAAA;AAC5B,yCAAiD;AAAxC,sGAAA,SAAS,OAAA;AAAE,oGAAA,OAAO,OAAA;AAC3B,uCAAgE;AAAvD,oGAAA,QAAQ,OAAA;AAAoB,kGAAA,MAAM,OAAA;AAC3C,yCAAwD;AAA/C,4GAAA,eAAe,OAAA;AAAE,qGAAA,QAAQ,OAAA;AAClC,+BAAuD;AAA9C,4FAAA,IAAI,OAAA;AACb,2CAA6D;AAApD,wGAAA,UAAU,OAAA;AACnB,qCAAsD;AAA7C,sGAAA,WAAW,OAAA;AAAE,uGAAA,YAAY,OAAA;AAClC,2CAA4C;AAAnC,0GAAA,YAAY,OAAA;AACrB,0CAAwB;AACxB,iCAA2C;AAAlC,yGAAA,gBAAgB,OAAA;AAEzB,wBAAwB;AACxB,+CAMwB;AALtB,2GAAA,WAAW,OAAA;AAEX,8GAAA,cAAc,OAAA;AACd,iHAAA,iBAAiB,OAAA;AACjB,2GAAA,WAAW,OAAA;AAEb,iCAAmF;AAA1E,uGAAA,cAAc,OAAA;AACvB,+CAAsD;AAA7C,oHAAA,oBAAoB,OAAA;AAE7B,uCAAuC;AACvC,+DAQgC;AAP9B,2HAAA,mBAAmB,OAAA;AASrB,0BAA0B;AAC1B,qCAA0F;AAAjF,iGAAA,MAAM,OAAA;AAAE,oGAAA,SAAS,OAAA;AAAE,yGAAA,cAAc,OAAA;AAE1C,4CAA4C;AAC5C,+CAYwB;AARtB,0GAAA,UAAU,OAAA;AACV,2GAAA,WAAW,OAAA;AACX,sGAAA,MAAM,OAAA;AACN,yGAAA,SAAS,OAAA;AACT,4GAAA,YAAY,OAAA;AACZ,qGAAA,KAAK,OAAA;AACL,qGAAA,KAAK,OAAA;AACL,sGAAA,MAAM,OAAA;AAER,iDAAgE;AAAvD,6GAAA,YAAY,OAAA;AAErB,4BAA4B;AAC5B,qCAMmB;AAHjB,8GAAA,mBAAmB,OAAA;AACnB,0GAAA,eAAe,OAAA;AACf,+GAAA,oBAAoB,OAAA"}

package/dist/ordinal.d.ts

@@ -0,0 +1,90 @@
+/**
+ * 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);
+ * ```
+ */
+import { Element } from './types';
+export type OrdinalKind = 'first' | 'last' | 'nth' | 'top_k' | 'next' | 'previous';
+export interface OrdinalIntent {
+    /** Whether ordinal intent was detected */
+    detected: boolean;
+    /** Type of ordinal intent */
+    kind?: OrdinalKind;
+    /** For "nth" kind: 1-indexed position (1=first, 2=second) */
+    n?: number;
+    /** For "top_k" kind: number of items */
+    k?: number;
+}
+/**
+ * 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 }
+ * ```
+ */
+export declare function detectOrdinalIntent(goal: string): OrdinalIntent;
+/**
+ * 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
+ * ```
+ */
+export declare function selectByOrdinal(elements: Element[], dominantGroupKey: string | null | undefined, intent: OrdinalIntent, currentElementId?: number): Element | Element[] | 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
+ */
+export declare function boostOrdinalElements(elements: Element[], dominantGroupKey: string | null | undefined, intent: OrdinalIntent, boostFactor?: number): Element[];
+//# sourceMappingURL=ordinal.d.ts.map

package/dist/ordinal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ordinal.d.ts","sourceRoot":"","sources":["../src/ordinal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAElC,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,MAAM,GAAG,UAAU,CAAC;AAEnF,MAAM,WAAW,aAAa;IAC5B,0CAA0C;IAC1C,QAAQ,EAAE,OAAO,CAAC;IAClB,6BAA6B;IAC7B,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,6DAA6D;IAC7D,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,wCAAwC;IACxC,CAAC,CAAC,EAAE,MAAM,CAAC;CACZ;AAwDD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,CAqD/D;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,OAAO,EAAE,EACnB,gBAAgB,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAC3C,MAAM,EAAE,aAAa,EACrB,gBAAgB,CAAC,EAAE,MAAM,GACxB,OAAO,GAAG,OAAO,EAAE,GAAG,IAAI,CAmE5B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,OAAO,EAAE,EACnB,gBAAgB,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAC3C,MAAM,EAAE,aAAa,EACrB,WAAW,GAAE,MAAc,GAC1B,OAAO,EAAE,CAsBX"}