sentienceapi 0.98.5 → 0.99.1

package/dist/actions.d.ts

@@ -3,6 +3,7 @@
  */
 import { IBrowser } from './protocols/browser-protocol';
 import { ActionResult, BBox } from './types';
+import { SnapshotOptions } from './snapshot';
 import { CursorPolicy } from './cursor-policy';
 export interface ClickRect {
     x: number;
@@ -62,6 +63,34 @@ export declare function click(browser: IBrowser, elementId: number, useMouse?: b
  * ```
  */
 export declare function typeText(browser: IBrowser, elementId: number, text: string, takeSnapshot?: boolean, delayMs?: number): Promise<ActionResult>;
+/**
+ * Clear the value of an input/textarea element (best-effort).
+ */
+export declare function clear(browser: IBrowser, elementId: number, takeSnapshot?: boolean): Promise<ActionResult>;
+/**
+ * Ensure a checkbox/radio is checked (best-effort).
+ */
+export declare function check(browser: IBrowser, elementId: number, takeSnapshot?: boolean): Promise<ActionResult>;
+/**
+ * Ensure a checkbox/radio is unchecked (best-effort).
+ */
+export declare function uncheck(browser: IBrowser, elementId: number, takeSnapshot?: boolean): Promise<ActionResult>;
+/**
+ * Select an option in a <select> element by matching option value or label (best-effort).
+ */
+export declare function selectOption(browser: IBrowser, elementId: number, option: string, takeSnapshot?: boolean): Promise<ActionResult>;
+/**
+ * Upload a local file via an <input type="file"> element (best-effort).
+ */
+export declare function uploadFile(browser: IBrowser, elementId: number, filePath: string, takeSnapshot?: boolean): Promise<ActionResult>;
+/**
+ * Submit a form (best-effort) by clicking a submit control or calling requestSubmit().
+ */
+export declare function submit(browser: IBrowser, elementId: number, takeSnapshot?: boolean): Promise<ActionResult>;
+/**
+ * Navigate back in history (best-effort).
+ */
+export declare function back(browser: IBrowser, takeSnapshot?: boolean): Promise<ActionResult>;
 /**
  * Scroll an element into view
  *
@@ -108,6 +137,14 @@ export declare function scrollTo(browser: IBrowser, elementId: number, behavior?
  * ```
  */
 export declare function press(browser: IBrowser, key: string, takeSnapshot?: boolean): Promise<ActionResult>;
+/**
+ * Send a sequence of key presses (e.g., "CMD+H", "CTRL+SHIFT+P").
+ */
+export declare function sendKeys(browser: IBrowser, sequence: string, takeSnapshot?: boolean, delayMs?: number): Promise<ActionResult>;
+/**
+ * Navigate to a search results page for the given query.
+ */
+export declare function search(browser: IBrowser, query: string, engine?: string, takeSnapshot?: boolean, snapshotOptions?: SnapshotOptions | undefined): Promise<ActionResult>;
 /**
  * Click at the center of a rectangle using Playwright's native mouse simulation.
  * This uses a hybrid approach: calculates center coordinates and uses mouse.click()

package/dist/actions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,8BAA8B,CAAC;AACxD,OAAO,EAAE,YAAY,EAAY,IAAI,EAAE,MAAM,SAAS,CAAC;AAGvD,OAAO,EAAE,YAAY,EAAwB,MAAM,iBAAiB,CAAC;AAoCrE,MAAM,WAAW,SAAS;IACxB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAoED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,KAAK,CACzB,OAAO,EAAE,QAAQ,EACjB,SAAS,EAAE,MAAM,EACjB,QAAQ,GAAE,OAAc,EACxB,YAAY,GAAE,OAAe,EAC7B,YAAY,CAAC,EAAE,YAAY,GAC1B,OAAO,CAAC,YAAY,CAAC,CA2GvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,QAAQ,CAC5B,OAAO,EAAE,QAAQ,EACjB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,YAAY,GAAE,OAAe,EAC7B,OAAO,GAAE,MAAU,GAClB,OAAO,CAAC,YAAY,CAAC,CAoDvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,QAAQ,CAC5B,OAAO,EAAE,QAAQ,EACjB,SAAS,EAAE,MAAM,EACjB,QAAQ,GAAE,QAAQ,GAAG,SAAS,GAAG,MAAiB,EAClD,KAAK,GAAE,OAAO,GAAG,QAAQ,GAAG,KAAK,GAAG,SAAoB,EACxD,YAAY,GAAE,OAAe,GAC5B,OAAO,CAAC,YAAY,CAAC,CAwDvB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,KAAK,CACzB,OAAO,EAAE,QAAQ,EACjB,GAAG,EAAE,MAAM,EACX,YAAY,GAAE,OAAe,GAC5B,OAAO,CAAC,YAAY,CAAC,CAgCvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAsB,SAAS,CAC7B,OAAO,EAAE,QAAQ,EACjB,IAAI,EAAE,SAAS,GAAG,IAAI,EACtB,SAAS,GAAE,OAAc,EACzB,iBAAiB,GAAE,MAAY,EAC/B,YAAY,GAAE,OAAe,EAC7B,YAAY,CAAC,EAAE,YAAY,GAC1B,OAAO,CAAC,YAAY,CAAC,CAgGvB"}
+{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"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"}

package/dist/actions.js

@@ -5,8 +5,17 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.click = click;
 exports.typeText = typeText;
+exports.clear = clear;
+exports.check = check;
+exports.uncheck = uncheck;
+exports.selectOption = selectOption;
+exports.uploadFile = uploadFile;
+exports.submit = submit;
+exports.back = back;
 exports.scrollTo = scrollTo;
 exports.press = press;
+exports.sendKeys = sendKeys;
+exports.search = search;
 exports.clickRect = clickRect;
 const snapshot_1 = require("./snapshot");
 const browser_evaluator_1 = require("./utils/browser-evaluator");
@@ -273,6 +282,465 @@ async function typeText(browser, elementId, text, takeSnapshot = false, delayMs
         snapshot_after: snapshotAfter,
     };
 }
+/**
+ * Clear the value of an input/textarea element (best-effort).
+ */
+async function clear(browser, elementId, takeSnapshot = false) {
+    const page = browser.getPage();
+    if (!page)
+        throw new Error('Browser not started. Call start() first.');
+    const startTime = Date.now();
+    const urlBefore = page.url();
+    const ok = await browser_evaluator_1.BrowserEvaluator.evaluate(page, id => {
+        const el = window.sentience_registry?.[id];
+        if (!el)
+            return false;
+        try {
+            el.focus?.();
+        }
+        catch {
+            /* ignore */
+        }
+        if ('value' in el) {
+            el.value = '';
+            el.dispatchEvent(new Event('input', { bubbles: true }));
+            el.dispatchEvent(new Event('change', { bubbles: true }));
+            return true;
+        }
+        return false;
+    }, elementId);
+    if (!ok) {
+        return {
+            success: false,
+            duration_ms: Date.now() - startTime,
+            outcome: 'error',
+            error: { code: 'clear_failed', reason: 'Element not found or not clearable' },
+        };
+    }
+    try {
+        await page.waitForTimeout(250);
+    }
+    catch {
+        /* ignore */
+    }
+    const durationMs = Date.now() - startTime;
+    const urlAfter = page.url();
+    const urlChanged = urlBefore !== urlAfter;
+    const outcome = urlChanged ? 'navigated' : 'dom_updated';
+    let snapshotAfter;
+    if (takeSnapshot) {
+        snapshotAfter = await (0, snapshot_1.snapshot)(browser);
+    }
+    return {
+        success: true,
+        duration_ms: durationMs,
+        outcome,
+        url_changed: urlChanged,
+        snapshot_after: snapshotAfter,
+    };
+}
+/**
+ * Ensure a checkbox/radio is checked (best-effort).
+ */
+async function check(browser, elementId, takeSnapshot = false) {
+    const page = browser.getPage();
+    if (!page)
+        throw new Error('Browser not started. Call start() first.');
+    const startTime = Date.now();
+    const urlBefore = page.url();
+    const ok = await browser_evaluator_1.BrowserEvaluator.evaluate(page, id => {
+        const el = window.sentience_registry?.[id];
+        if (!el)
+            return false;
+        try {
+            el.focus?.();
+        }
+        catch {
+            /* ignore */
+        }
+        if (!('checked' in el))
+            return false;
+        if (el.checked === true)
+            return true;
+        try {
+            el.click();
+        }
+        catch {
+            return false;
+        }
+        return true;
+    }, elementId);
+    if (!ok) {
+        return {
+            success: false,
+            duration_ms: Date.now() - startTime,
+            outcome: 'error',
+            error: { code: 'check_failed', reason: 'Element not found or not checkable' },
+        };
+    }
+    try {
+        await page.waitForTimeout(250);
+    }
+    catch {
+        /* ignore */
+    }
+    const durationMs = Date.now() - startTime;
+    const urlAfter = page.url();
+    const urlChanged = urlBefore !== urlAfter;
+    const outcome = urlChanged ? 'navigated' : 'dom_updated';
+    let snapshotAfter;
+    if (takeSnapshot)
+        snapshotAfter = await (0, snapshot_1.snapshot)(browser);
+    return {
+        success: true,
+        duration_ms: durationMs,
+        outcome,
+        url_changed: urlChanged,
+        snapshot_after: snapshotAfter,
+    };
+}
+/**
+ * Ensure a checkbox/radio is unchecked (best-effort).
+ */
+async function uncheck(browser, elementId, takeSnapshot = false) {
+    const page = browser.getPage();
+    if (!page)
+        throw new Error('Browser not started. Call start() first.');
+    const startTime = Date.now();
+    const urlBefore = page.url();
+    const ok = await browser_evaluator_1.BrowserEvaluator.evaluate(page, id => {
+        const el = window.sentience_registry?.[id];
+        if (!el)
+            return false;
+        try {
+            el.focus?.();
+        }
+        catch {
+            /* ignore */
+        }
+        if (!('checked' in el))
+            return false;
+        if (el.checked === false)
+            return true;
+        try {
+            el.click();
+        }
+        catch {
+            return false;
+        }
+        return true;
+    }, elementId);
+    if (!ok) {
+        return {
+            success: false,
+            duration_ms: Date.now() - startTime,
+            outcome: 'error',
+            error: { code: 'uncheck_failed', reason: 'Element not found or not uncheckable' },
+        };
+    }
+    try {
+        await page.waitForTimeout(250);
+    }
+    catch {
+        /* ignore */
+    }
+    const durationMs = Date.now() - startTime;
+    const urlAfter = page.url();
+    const urlChanged = urlBefore !== urlAfter;
+    const outcome = urlChanged ? 'navigated' : 'dom_updated';
+    let snapshotAfter;
+    if (takeSnapshot)
+        snapshotAfter = await (0, snapshot_1.snapshot)(browser);
+    return {
+        success: true,
+        duration_ms: durationMs,
+        outcome,
+        url_changed: urlChanged,
+        snapshot_after: snapshotAfter,
+    };
+}
+/**
+ * Select an option in a <select> element by matching option value or label (best-effort).
+ */
+async function selectOption(browser, elementId, option, takeSnapshot = false) {
+    const page = browser.getPage();
+    if (!page)
+        throw new Error('Browser not started. Call start() first.');
+    const startTime = Date.now();
+    const urlBefore = page.url();
+    const ok = await browser_evaluator_1.BrowserEvaluator.evaluate(page, (args) => {
+        const el = window.sentience_registry?.[args.id];
+        if (!el)
+            return false;
+        const tag = String(el.tagName || '').toUpperCase();
+        if (tag !== 'SELECT')
+            return false;
+        const needle = String(args.option ?? '');
+        const opts = Array.from(el.options || []);
+        let chosen = null;
+        for (const o of opts) {
+            const oo = o;
+            if (String(oo.value) === needle || String(oo.text) === needle) {
+                chosen = o;
+                break;
+            }
+        }
+        if (!chosen) {
+            for (const o of opts) {
+                const oo = o;
+                if (String(oo.text || '').includes(needle)) {
+                    chosen = o;
+                    break;
+                }
+            }
+        }
+        if (!chosen)
+            return false;
+        el.value = chosen.value;
+        el.dispatchEvent(new Event('input', { bubbles: true }));
+        el.dispatchEvent(new Event('change', { bubbles: true }));
+        return true;
+    }, { id: elementId, option });
+    if (!ok) {
+        return {
+            success: false,
+            duration_ms: Date.now() - startTime,
+            outcome: 'error',
+            error: { code: 'select_failed', reason: 'Element not found or option not found' },
+        };
+    }
+    try {
+        await page.waitForTimeout(250);
+    }
+    catch {
+        /* ignore */
+    }
+    const durationMs = Date.now() - startTime;
+    const urlAfter = page.url();
+    const urlChanged = urlBefore !== urlAfter;
+    const outcome = urlChanged ? 'navigated' : 'dom_updated';
+    let snapshotAfter;
+    if (takeSnapshot)
+        snapshotAfter = await (0, snapshot_1.snapshot)(browser);
+    return {
+        success: true,
+        duration_ms: durationMs,
+        outcome,
+        url_changed: urlChanged,
+        snapshot_after: snapshotAfter,
+    };
+}
+/**
+ * Upload a local file via an <input type="file"> element (best-effort).
+ */
+async function uploadFile(browser, elementId, filePath, takeSnapshot = false) {
+    const page = browser.getPage();
+    if (!page)
+        throw new Error('Browser not started. Call start() first.');
+    const startTime = Date.now();
+    const urlBefore = page.url();
+    let success = false;
+    let errorMsg;
+    try {
+        // First try: grab the exact element handle from the sentience registry.
+        try {
+            const handle = await page.evaluateHandle('(id) => (window.sentience_registry && window.sentience_registry[id]) || null', elementId);
+            const el = handle.asElement?.() ?? null;
+            if (!el)
+                throw new Error('Element not found');
+            await el.setInputFiles(filePath);
+            success = true;
+        }
+        catch {
+            // Fallback: resolve a selector from the element's attributes and use page.setInputFiles().
+            const attrs = await browser_evaluator_1.BrowserEvaluator.evaluate(page, id => {
+                const el = window.sentience_registry?.[id];
+                if (!el)
+                    return null;
+                const tag = String(el.tagName || '').toUpperCase();
+                const type = String(el.type || '').toLowerCase();
+                const idAttr = el.id ? String(el.id) : null;
+                const nameAttr = el.name ? String(el.name) : null;
+                return { tag, type, id: idAttr, name: nameAttr };
+            }, elementId);
+            let selector = null;
+            if (attrs && attrs.tag === 'INPUT' && attrs.type === 'file') {
+                if (attrs.id)
+                    selector = `input#${attrs.id}`;
+                else if (attrs.name)
+                    selector = `input[name="${String(attrs.name).replace(/"/g, '\\"')}"]`;
+            }
+            if (!selector)
+                throw new Error('Element not found');
+            await page.setInputFiles(selector, filePath);
+            success = true;
+        }
+    }
+    catch (e) {
+        success = false;
+        errorMsg = String(e?.message ?? e);
+    }
+    try {
+        await page.waitForTimeout(250);
+    }
+    catch {
+        /* ignore */
+    }
+    const durationMs = Date.now() - startTime;
+    const urlAfter = page.url();
+    const urlChanged = urlBefore !== urlAfter;
+    const outcome = urlChanged ? 'navigated' : success ? 'dom_updated' : 'error';
+    let snapshotAfter;
+    if (takeSnapshot) {
+        try {
+            snapshotAfter = await (0, snapshot_1.snapshot)(browser);
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    return {
+        success,
+        duration_ms: durationMs,
+        outcome,
+        url_changed: urlChanged,
+        snapshot_after: snapshotAfter,
+        error: success ? undefined : { code: 'upload_failed', reason: errorMsg ?? 'upload failed' },
+    };
+}
+/**
+ * Submit a form (best-effort) by clicking a submit control or calling requestSubmit().
+ */
+async function submit(browser, elementId, takeSnapshot = false) {
+    const page = browser.getPage();
+    if (!page)
+        throw new Error('Browser not started. Call start() first.');
+    const startTime = Date.now();
+    const urlBefore = page.url();
+    const ok = await browser_evaluator_1.BrowserEvaluator.evaluate(page, id => {
+        const el = window.sentience_registry?.[id];
+        if (!el)
+            return false;
+        try {
+            el.focus?.();
+        }
+        catch {
+            /* ignore */
+        }
+        const tag = String(el.tagName || '').toUpperCase();
+        if (tag === 'FORM') {
+            if (typeof el.requestSubmit === 'function') {
+                el.requestSubmit();
+                return true;
+            }
+            try {
+                el.submit();
+                return true;
+            }
+            catch {
+                return false;
+            }
+        }
+        const form = el.form;
+        if (form && typeof form.requestSubmit === 'function') {
+            form.requestSubmit();
+            return true;
+        }
+        try {
+            el.click();
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }, elementId);
+    if (!ok) {
+        return {
+            success: false,
+            duration_ms: Date.now() - startTime,
+            outcome: 'error',
+            error: { code: 'submit_failed', reason: 'Element not found or not submittable' },
+        };
+    }
+    try {
+        await page.waitForTimeout(500);
+    }
+    catch {
+        /* ignore */
+    }
+    const durationMs = Date.now() - startTime;
+    const urlAfter = page.url();
+    const urlChanged = urlBefore !== urlAfter;
+    const outcome = urlChanged ? 'navigated' : 'dom_updated';
+    let snapshotAfter;
+    if (takeSnapshot) {
+        try {
+            snapshotAfter = await (0, snapshot_1.snapshot)(browser);
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    return {
+        success: true,
+        duration_ms: durationMs,
+        outcome,
+        url_changed: urlChanged,
+        snapshot_after: snapshotAfter,
+    };
+}
+/**
+ * Navigate back in history (best-effort).
+ */
+async function back(browser, takeSnapshot = false) {
+    const page = browser.getPage();
+    if (!page)
+        throw new Error('Browser not started. Call start() first.');
+    const startTime = Date.now();
+    const urlBefore = page.url();
+    let success = false;
+    let errorMsg;
+    try {
+        await page.goBack();
+        success = true;
+    }
+    catch (e) {
+        success = false;
+        errorMsg = String(e?.message ?? e);
+    }
+    try {
+        await page.waitForTimeout(500);
+    }
+    catch {
+        /* ignore */
+    }
+    const durationMs = Date.now() - startTime;
+    let urlChanged = false;
+    try {
+        urlChanged = urlBefore !== page.url();
+    }
+    catch {
+        urlChanged = true;
+    }
+    const outcome = urlChanged ? 'navigated' : success ? 'dom_updated' : 'error';
+    let snapshotAfter;
+    if (takeSnapshot) {
+        try {
+            snapshotAfter = await (0, snapshot_1.snapshot)(browser);
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    return {
+        success,
+        duration_ms: durationMs,
+        outcome,
+        url_changed: urlChanged,
+        snapshot_after: snapshotAfter,
+        error: success ? undefined : { code: 'back_failed', reason: errorMsg ?? 'back failed' },
+    };
+}
 /**
  * Scroll an element into view
  *
@@ -390,6 +858,130 @@ async function press(browser, key, takeSnapshot = false) {
         snapshot_after: snapshotAfter,
     };
 }
+function normalizeKeyToken(token) {
+    const lookup = {
+        CMD: 'Meta',
+        COMMAND: 'Meta',
+        CTRL: 'Control',
+        CONTROL: 'Control',
+        ALT: 'Alt',
+        OPTION: 'Alt',
+        SHIFT: 'Shift',
+        ESC: 'Escape',
+        ESCAPE: 'Escape',
+        ENTER: 'Enter',
+        RETURN: 'Enter',
+        TAB: 'Tab',
+        SPACE: 'Space',
+    };
+    const upper = token.trim().toUpperCase();
+    return lookup[upper] ?? token.trim();
+}
+function parseKeySequence(sequence) {
+    const parts = [];
+    for (const rawPart of sequence.replace(/,/g, ' ').split(/\s+/)) {
+        let raw = rawPart.trim();
+        if (!raw)
+            continue;
+        if (raw.startsWith('{') && raw.endsWith('}')) {
+            raw = raw.slice(1, -1);
+        }
+        if (raw.includes('+')) {
+            const combo = raw
+                .split('+')
+                .filter(Boolean)
+                .map(token => normalizeKeyToken(token))
+                .join('+');
+            parts.push(combo);
+        }
+        else {
+            parts.push(normalizeKeyToken(raw));
+        }
+    }
+    return parts;
+}
+/**
+ * Send a sequence of key presses (e.g., "CMD+H", "CTRL+SHIFT+P").
+ */
+async function sendKeys(browser, sequence, takeSnapshot = false, delayMs = 50) {
+    const page = browser.getPage();
+    if (!page) {
+        throw new Error('Browser not started. Call start() first.');
+    }
+    const startTime = Date.now();
+    const urlBefore = page.url();
+    const keys = parseKeySequence(sequence);
+    if (keys.length === 0) {
+        throw new Error('send_keys sequence is empty');
+    }
+    for (const key of keys) {
+        await page.keyboard.press(key);
+        if (delayMs > 0) {
+            await page.waitForTimeout(delayMs);
+        }
+    }
+    const durationMs = Date.now() - startTime;
+    const urlAfter = page.url();
+    const urlChanged = urlBefore !== urlAfter;
+    const outcome = urlChanged ? 'navigated' : 'dom_updated';
+    let snapshotAfter;
+    if (takeSnapshot) {
+        snapshotAfter = await (0, snapshot_1.snapshot)(browser);
+    }
+    return {
+        success: true,
+        duration_ms: durationMs,
+        outcome,
+        url_changed: urlChanged,
+        snapshot_after: snapshotAfter,
+    };
+}
+function buildSearchUrl(query, engine) {
+    const q = encodeURIComponent(query).replace(/%20/g, '+');
+    const key = engine.trim().toLowerCase();
+    if (key === 'duckduckgo' || key === 'ddg') {
+        return `https://duckduckgo.com/?q=${q}`;
+    }
+    if (key === 'google.com' || key === 'google') {
+        return `https://www.google.com/search?q=${q}`;
+    }
+    if (key === 'bing') {
+        return `https://www.bing.com/search?q=${q}`;
+    }
+    throw new Error(`unsupported search engine: ${engine}`);
+}
+/**
+ * Navigate to a search results page for the given query.
+ */
+async function search(browser, query, engine = 'duckduckgo', takeSnapshot = false, snapshotOptions = undefined) {
+    const page = browser.getPage();
+    if (!page) {
+        throw new Error('Browser not started. Call start() first.');
+    }
+    if (!query.trim()) {
+        throw new Error('search query is empty');
+    }
+    const startTime = Date.now();
+    const urlBefore = page.url();
+    const url = buildSearchUrl(query, engine);
+    await browser.goto(url);
+    await page.waitForLoadState('networkidle');
+    const durationMs = Date.now() - startTime;
+    const urlAfter = page.url();
+    const urlChanged = urlBefore !== urlAfter;
+    const outcome = urlChanged ? 'navigated' : 'dom_updated';
+    let snapshotAfter;
+    if (takeSnapshot) {
+        snapshotAfter = await (0, snapshot_1.snapshot)(browser, snapshotOptions);
+    }
+    return {
+        success: true,
+        duration_ms: durationMs,
+        outcome,
+        url_changed: urlChanged,
+        snapshot_after: snapshotAfter,
+    };
+}
 /**
  * Click at the center of a rectangle using Playwright's native mouse simulation.
  * This uses a hybrid approach: calculates center coordinates and uses mouse.click()