@taqwright/taqwright 0.0.24

package/dist/locator/index.js

@@ -0,0 +1,1506 @@
+import { Platform, W3C_ELEMENT_KEY, } from '../types/index.js';
+import { ANDROID_NAMED_KEYS, IOS_NAMED_KEYS, KEY_TO_UNICODE } from '../keys.js';
+const DEFAULT_TIMEOUT = 30_000;
+const POLL_INTERVAL = 200;
+export class Locator {
+    ctx;
+    strategy;
+    state;
+    pinnedIds;
+    constructor(ctx, strategy, state, pinnedIds) {
+        this.ctx = ctx;
+        this.strategy = strategy;
+        this.state = state ?? { chainOps: [] };
+        this.pinnedIds = pinnedIds;
+    }
+    static fromStrategy(ctx, strategy) {
+        return new Locator(ctx, strategy);
+    }
+    static pinnedToIds(ctx, ids) {
+        return new Locator(ctx, { using: 'xpath', value: '__pinned__' }, { chainOps: [] }, ids);
+    }
+    derive(patch) {
+        return new Locator(this.ctx, this.strategy, {
+            parent: 'parent' in patch ? patch.parent : this.state.parent,
+            chainOps: patch.chainOps ?? this.state.chainOps,
+            indexSelector: 'indexSelector' in patch ? patch.indexSelector : this.state.indexSelector,
+        });
+    }
+    rebaseRoot(newRoot) {
+        if (!this.state.parent) {
+            return this.derive({ parent: newRoot });
+        }
+        return this.derive({ parent: this.state.parent.rebaseRoot(newRoot) });
+    }
+    async click(opts) {
+        const id = await this.resolveActionable(opts);
+        await this.ctx.driver.elementClick(id);
+    }
+    async tap(opts) {
+        return this.click(opts);
+    }
+    async clickWithCoordFallback(opts) {
+        const driver = this.ctx.driver;
+        const snap = async () => {
+            try {
+                return await driver.getPageSource();
+            }
+            catch {
+                return null;
+            }
+        };
+        const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+        const tapAt = async (px, py) => {
+            try {
+                await driver.performActions([
+                    {
+                        type: 'pointer',
+                        id: 'finger1',
+                        parameters: { pointerType: 'touch' },
+                        actions: [
+                            { type: 'pointerMove', duration: 0, x: px, y: py },
+                            { type: 'pointerDown', button: 0 },
+                            { type: 'pointerUp', button: 0 },
+                        ],
+                    },
+                ]);
+            }
+            finally {
+                await driver.releaseActions().catch(() => { });
+            }
+        };
+        const idEarly = await this.resolveOnce();
+        let hasClickableSpan = false;
+        if (idEarly) {
+            try {
+                const v = await driver.getElementAttribute(idEarly, 'text-has-clickable-span');
+                hasClickableSpan = v === 'true';
+            }
+            catch {
+            }
+        }
+        if (!hasClickableSpan) {
+            const before1 = await snap();
+            let clickThrew = false;
+            try {
+                await this.click({ timeout: opts?.timeout ?? 10_000 });
+            }
+            catch {
+                clickThrew = true;
+            }
+            if (!clickThrew && before1 != null) {
+                await sleep(800);
+                const after = await snap();
+                if (after != null && after !== before1)
+                    return;
+            }
+        }
+        const id = idEarly ?? (await this.resolveOnce());
+        if (!id)
+            return;
+        let rect = null;
+        try {
+            rect = await driver.getElementRect(id);
+        }
+        catch {
+        }
+        if (!rect || rect.width <= 0 || rect.height <= 0)
+            return;
+        const cy = Math.round(rect.y + rect.height * 0.5);
+        const probes = [
+            { x: Math.round(rect.x + rect.width * 0.5), y: cy },
+            { x: Math.round(rect.x + rect.width * 0.1), y: cy },
+            { x: Math.round(rect.x + rect.width * 0.9), y: cy },
+        ];
+        for (const pt of probes) {
+            const before = await snap();
+            await tapAt(pt.x, pt.y);
+            if (before == null)
+                return;
+            await sleep(800);
+            const after = await snap();
+            if (after != null && after !== before)
+                return;
+        }
+    }
+    async doubleClick(opts) {
+        const id = await this.resolveActionable(opts);
+        const driver = this.ctx.driver;
+        if (this.ctx.platform === Platform.IOS) {
+            try {
+                await driver.executeScript('mobile: doubleTap', [{ elementId: id }]);
+                return;
+            }
+            catch {
+            }
+        }
+        else if (this.ctx.platform === Platform.ANDROID) {
+            try {
+                await driver.executeScript('mobile: doubleClickGesture', [{ elementId: id }]);
+                return;
+            }
+            catch {
+            }
+        }
+        const rect = await driver.getElementRect(id);
+        const x = Math.floor(rect.x + rect.width / 2);
+        const y = Math.floor(rect.y + rect.height / 2);
+        try {
+            await driver.performActions([
+                {
+                    type: 'pointer',
+                    id: 'finger1',
+                    parameters: { pointerType: 'touch' },
+                    actions: [
+                        { type: 'pointerMove', duration: 0, x, y },
+                        { type: 'pointerDown', button: 0 },
+                        { type: 'pointerUp', button: 0 },
+                        { type: 'pause', duration: 50 },
+                        { type: 'pointerDown', button: 0 },
+                        { type: 'pointerUp', button: 0 },
+                    ],
+                },
+            ]);
+        }
+        finally {
+            await driver.releaseActions().catch(() => { });
+        }
+    }
+    async doubleTap(opts) {
+        return this.doubleClick(opts);
+    }
+    async longPress(opts) {
+        const id = await this.resolveActionable(opts);
+        const driver = this.ctx.driver;
+        const duration = opts?.duration ?? 1_000;
+        const rect = await driver.getElementRect(id);
+        const x = Math.floor(rect.x + rect.width / 2);
+        const y = Math.floor(rect.y + rect.height / 2);
+        try {
+            await driver.performActions([
+                {
+                    type: 'pointer',
+                    id: 'finger1',
+                    parameters: { pointerType: 'touch' },
+                    actions: [
+                        { type: 'pointerMove', duration: 0, x, y },
+                        { type: 'pointerDown', button: 0 },
+                        { type: 'pause', duration },
+                        { type: 'pointerUp', button: 0 },
+                    ],
+                },
+            ]);
+        }
+        finally {
+            await driver.releaseActions().catch(() => { });
+        }
+    }
+    async clear(opts) {
+        const id = await this.resolveActionable(opts);
+        try {
+            await this.ctx.driver.elementClick(id);
+        }
+        catch {
+        }
+        try {
+            await this.ctx.driver.elementClear(id);
+        }
+        catch {
+        }
+    }
+    async fill(value, opts) {
+        const id = await this.resolveActionable(opts);
+        try {
+            await this.typeInto(id, value);
+        }
+        catch (err) {
+            if (!isInvalidElementState(err))
+                throw err;
+            const editableId = await this.findEditableNode(id);
+            if (!editableId)
+                throw err;
+            await this.typeInto(editableId, value);
+        }
+    }
+    async typeInto(id, value) {
+        try {
+            await this.ctx.driver.elementClick(id);
+        }
+        catch {
+        }
+        try {
+            await this.ctx.driver.elementClear(id);
+        }
+        catch {
+        }
+        await this.ctx.driver.elementSendKeys(id, value);
+    }
+    async findEditableNode(id) {
+        const descendant = await this.findEditableDescendant(id);
+        if (descendant)
+            return descendant;
+        try {
+            const active = (await this.ctx.driver.getActiveElement());
+            const activeId = active?.[W3C_ELEMENT_KEY];
+            if (activeId && activeId !== id && (await this.isEditableElement(activeId))) {
+                return activeId;
+            }
+        }
+        catch {
+        }
+        return null;
+    }
+    async findEditableDescendant(id) {
+        const xpath = this.ctx.platform === Platform.IOS
+            ? './/*[self::XCUIElementTypeTextField or self::XCUIElementTypeSecureTextField]'
+            : './/android.widget.EditText';
+        const refs = (await this.ctx.driver
+            .findElementsFromElement(id, 'xpath', xpath)
+            .catch(() => []));
+        return refs.length > 0 ? refs[0][W3C_ELEMENT_KEY] : null;
+    }
+    async isEditableElement(id) {
+        const isIOS = this.ctx.platform === Platform.IOS;
+        const cls = await this.ctx.driver
+            .getElementAttribute(id, isIOS ? 'type' : 'class')
+            .catch(() => null);
+        if (!cls)
+            return false;
+        return isIOS ? /TextField|SecureTextField/.test(cls) : /EditText/.test(cls);
+    }
+    async sendKeyStrokes(value, opts) {
+        return this.fill(value, opts);
+    }
+    async focus(opts) {
+        const id = await this.resolveActionable(opts);
+        await this.ctx.driver.elementClick(id);
+    }
+    async blur(_opts) {
+        try {
+            if (await this.ctx.driver.isKeyboardShown()) {
+                if (this.ctx.platform === Platform.IOS) {
+                    await this.ctx.driver.executeScript('mobile: hideKeyboard', [{}]).catch(async () => {
+                        await this.ctx.driver.hideKeyboard().catch(() => { });
+                    });
+                }
+                else {
+                    await this.ctx.driver.hideKeyboard().catch(() => { });
+                }
+                return;
+            }
+        }
+        catch {
+        }
+        try {
+            await this.ctx.driver.performActions([
+                {
+                    type: 'pointer',
+                    id: 'finger1',
+                    parameters: { pointerType: 'touch' },
+                    actions: [
+                        { type: 'pointerMove', duration: 0, x: 1, y: 1 },
+                        { type: 'pointerDown', button: 0 },
+                        { type: 'pointerUp', button: 0 },
+                    ],
+                },
+            ]);
+        }
+        finally {
+            await this.ctx.driver.releaseActions().catch(() => { });
+        }
+    }
+    async isChecked(opts) {
+        const id = await this.resolveVisible(opts);
+        const state = await this.readChecked(id);
+        if (state === undefined) {
+            throw new Error(`isChecked: element (${this.strategy.using}=${this.strategy.value}) is not a checkable control — no readable checked/value attribute`);
+        }
+        return state;
+    }
+    async check(opts) {
+        const id = await this.resolveActionable(opts);
+        const current = await this.readChecked(id);
+        if (current === true)
+            return;
+        if (current === undefined) {
+            throw new Error(`check: element (${this.strategy.using}=${this.strategy.value}) is not a checkable control`);
+        }
+        await this.ctx.driver.elementClick(id);
+        await this.waitForChecked(true, opts);
+    }
+    async uncheck(opts) {
+        const id = await this.resolveActionable(opts);
+        const current = await this.readChecked(id);
+        if (current === false)
+            return;
+        if (current === undefined) {
+            throw new Error(`uncheck: element (${this.strategy.using}=${this.strategy.value}) is not a checkable control`);
+        }
+        await this.ctx.driver.elementClick(id);
+        await this.waitForChecked(false, opts);
+    }
+    async readChecked(id) {
+        if (this.ctx.platform === Platform.ANDROID) {
+            const v = await this.ctx.driver.getElementAttribute(id, 'checked').catch(() => null);
+            if (v === 'true')
+                return true;
+            if (v === 'false')
+                return false;
+            return undefined;
+        }
+        const v = await this.ctx.driver.getElementAttribute(id, 'value').catch(() => null);
+        if (v === '1' || v === 'true')
+            return true;
+        if (v === '0' || v === 'false' || v === '')
+            return false;
+        return undefined;
+    }
+    async waitForChecked(expected, opts) {
+        const timeout = opts?.timeout ?? this.ctx.defaultTimeout;
+        const deadline = Date.now() + timeout;
+        let last;
+        while (Date.now() < deadline) {
+            const id = await this.resolveOnce();
+            if (id) {
+                last = await this.readChecked(id);
+                if (last === expected)
+                    return;
+            }
+            await sleep(POLL_INTERVAL);
+        }
+        throw new Error(`${expected ? 'check' : 'uncheck'}: toggle did not reach state ${expected} within ${timeout}ms (last observed: ${last ?? '<unknown>'})`);
+    }
+    async press(key, opts) {
+        const id = await this.resolveActionable(opts);
+        await this.ctx.driver.elementClick(id).catch(() => { });
+        const unicode = KEY_TO_UNICODE[key];
+        if (unicode !== undefined) {
+            await this.ctx.driver.elementSendKeys(id, unicode);
+            return;
+        }
+        if (key.length === 1) {
+            await this.ctx.driver.elementSendKeys(id, key);
+            return;
+        }
+        if (this.ctx.platform === Platform.ANDROID) {
+            const code = ANDROID_NAMED_KEYS[key];
+            if (code !== undefined) {
+                await this.ctx.driver.executeScript('mobile: pressKey', [{ keycode: code }]);
+                return;
+            }
+        }
+        else {
+            const name = IOS_NAMED_KEYS[key];
+            if (name !== undefined) {
+                await this.ctx.driver.executeScript('mobile: keys', [{ keys: [{ name }] }]);
+                return;
+            }
+        }
+        throw new Error(`press: key "${key}" is not supported on ${this.ctx.platform}. ` +
+            `Supported: single chars, ${Object.keys(KEY_TO_UNICODE).join(', ')}, ` +
+            `${Object.keys(this.ctx.platform === Platform.ANDROID ? ANDROID_NAMED_KEYS : IOS_NAMED_KEYS).join(', ')}.`);
+    }
+    async pressSequentially(text, opts) {
+        const id = await this.resolveActionable(opts);
+        await this.ctx.driver.elementClick(id).catch(() => { });
+        const delay = opts?.delay ?? 0;
+        const ctx = await this.ctx.driver.getAppiumContext().catch(() => 'NATIVE_APP');
+        const replaces = this.ctx.platform === Platform.ANDROID && String(ctx) === 'NATIVE_APP';
+        let acc = '';
+        for (const ch of text) {
+            acc += ch;
+            await this.ctx.driver.elementSendKeys(id, replaces ? acc : ch);
+            if (delay > 0)
+                await sleep(delay);
+        }
+    }
+    async selectOption(value, opts) {
+        const input = typeof value === 'string' ? { label: value } : value;
+        const id = await this.resolveActionable(opts);
+        const type = await this.detectPickerType(id);
+        switch (type) {
+            case 'ios-picker-wheel':
+                return this.selectPickerWheel(id, input);
+            case 'ios-date-picker':
+                return this.selectIosDatePicker(id, input);
+            case 'android-spinner':
+                return this.selectAndroidSpinner(id, input);
+            case 'android-date-picker':
+                return this.selectAndroidDatePicker(id, input);
+            case 'android-time-picker':
+                return this.selectAndroidTimePicker(id, input);
+            case 'menu':
+                return this.selectMenuOption(id, input);
+            default:
+                throw new Error(`selectOption: element type "${type ?? 'unknown'}" is not a supported picker. ` +
+                    `Supported: iOS XCUIElementTypePickerWheel / DatePicker, ` +
+                    `Android Spinner / DatePicker / TimePicker, popup menus.`);
+        }
+    }
+    async detectPickerType(id) {
+        if (this.ctx.platform === Platform.IOS) {
+            const t = await this.ctx.driver.getElementAttribute(id, 'type').catch(() => null);
+            if (!t)
+                return undefined;
+            if (t === 'XCUIElementTypePickerWheel')
+                return 'ios-picker-wheel';
+            if (t === 'XCUIElementTypeDatePicker')
+                return 'ios-date-picker';
+            if (t === 'XCUIElementTypePicker')
+                return 'ios-date-picker';
+            return undefined;
+        }
+        const cls = await this.ctx.driver.getElementAttribute(id, 'class').catch(() => null);
+        if (!cls)
+            return undefined;
+        if (cls.endsWith('Spinner'))
+            return 'android-spinner';
+        if (cls.endsWith('DatePicker'))
+            return 'android-date-picker';
+        if (cls.endsWith('TimePicker'))
+            return 'android-time-picker';
+        if (cls.endsWith('PopupMenu') || cls.endsWith('ListPopupWindow'))
+            return 'menu';
+        return undefined;
+    }
+    async selectPickerWheel(id, input) {
+        if (input.label !== undefined) {
+            await this.ctx.driver.executeScript('mobile: setPickerValue', [
+                { elementId: id, order: 'next', offset: 0.15, value: input.label },
+            ]);
+            return;
+        }
+        if (input.index !== undefined) {
+            throw new Error('selectOption({index}) is not supported for XCUIElementTypePickerWheel; pass {label} instead');
+        }
+        throw new Error('selectOption: PickerWheel requires {label}');
+    }
+    async selectIosDatePicker(id, input) {
+        const wheels = (await this.ctx.driver.findElementsFromElement(id, 'class name', 'XCUIElementTypePickerWheel'));
+        if (!wheels || wheels.length === 0) {
+            throw new Error('selectOption: iOS DatePicker has no PickerWheel children — is it open?');
+        }
+        const parts = parseDateOrTime(input);
+        if (parts.length === 0) {
+            throw new Error('selectOption: iOS DatePicker requires {date: "YYYY-MM-DD"} or {time: "HH:mm"}');
+        }
+        if (parts.length > wheels.length) {
+            throw new Error(`selectOption: ${parts.length} value parts but DatePicker only has ${wheels.length} wheel(s)`);
+        }
+        for (let i = 0; i < parts.length; i++) {
+            const wheelId = wheels[i][W3C_ELEMENT_KEY];
+            await this.ctx.driver.executeScript('mobile: setPickerValue', [
+                { elementId: wheelId, order: 'next', offset: 0.15, value: parts[i] },
+            ]);
+        }
+    }
+    async selectAndroidSpinner(id, input) {
+        if (input.label === undefined) {
+            throw new Error('selectOption: Android Spinner requires {label}');
+        }
+        await this.ctx.driver.elementClick(id);
+        await sleep(200);
+        const optionRef = await this.ctx.driver
+            .findElement('-android uiautomator', `new UiSelector().text(${JSON.stringify(input.label)})`)
+            .catch(() => null);
+        if (!optionRef) {
+            throw new Error(`selectOption: Spinner option "${input.label}" not found after opening`);
+        }
+        const optId = optionRef[W3C_ELEMENT_KEY];
+        await this.ctx.driver.elementClick(optId);
+    }
+    async selectAndroidDatePicker(id, input) {
+        if (!input.date) {
+            throw new Error('selectOption: Android DatePicker requires {date: "YYYY-MM-DD"}');
+        }
+        try {
+            await this.ctx.driver.executeScript('mobile: setDate', [
+                { elementId: id, datestring: input.date },
+            ]);
+            return;
+        }
+        catch {
+        }
+        throw new Error('selectOption: Android DatePicker — native `mobile: setDate` failed. ' +
+            'This picker variant likely requires manual interaction; use locator.click() + wheel-by-wheel scrolling.');
+    }
+    async selectAndroidTimePicker(id, input) {
+        if (!input.time) {
+            throw new Error('selectOption: Android TimePicker requires {time: "HH:mm"}');
+        }
+        try {
+            await this.ctx.driver.executeScript('mobile: setTime', [
+                { elementId: id, timestring: input.time },
+            ]);
+            return;
+        }
+        catch {
+        }
+        throw new Error('selectOption: Android TimePicker — native `mobile: setTime` failed. ' +
+            'This picker variant likely requires manual interaction.');
+    }
+    async selectMenuOption(_id, input) {
+        if (input.label === undefined) {
+            throw new Error('selectOption: menu requires {label}');
+        }
+        const optionRef = await this.ctx.driver
+            .findElement('xpath', `//*[@text=${xpathLiteral(input.label)} or @label=${xpathLiteral(input.label)} or @name=${xpathLiteral(input.label)}]`)
+            .catch(() => null);
+        if (!optionRef) {
+            throw new Error(`selectOption: menu option "${input.label}" not found`);
+        }
+        const optId = optionRef[W3C_ELEMENT_KEY];
+        await this.ctx.driver.elementClick(optId);
+    }
+    async screenshot(opts) {
+        const id = await this.resolveVisible(opts);
+        const data = await this.ctx.driver.takeElementScreenshot(id);
+        return Buffer.from(data, 'base64');
+    }
+    async scrollIntoView(opts) {
+        await this.scrollUntilVisible(opts);
+        if (opts?.bottomMargin && opts.bottomMargin > 0) {
+            await this.nudgeAboveBottom(opts.bottomMargin, opts);
+        }
+    }
+    async nudgeAboveBottom(margin, opts) {
+        const driver = this.ctx.driver;
+        const xFrac = opts?.from?.x ?? 0.5;
+        for (let i = 0; i < 5; i++) {
+            const rect = await driver.getWindowRect();
+            const box = await this.boundingBox({ timeout: opts?.visibleTimeout ?? 500 }).catch(() => null);
+            if (!box)
+                return;
+            const bottom = box.y + box.height;
+            const limit = rect.height * (1 - margin);
+            if (bottom <= limit)
+                return;
+            const overshootFrac = Math.min(0.4, (bottom - limit) / rect.height);
+            const x = Math.floor(rect.width * xFrac);
+            const fromY = Math.floor(rect.height * (0.5 + overshootFrac / 2));
+            const toY = Math.floor(rect.height * (0.5 - overshootFrac / 2));
+            try {
+                await driver.performActions([
+                    {
+                        type: 'pointer',
+                        id: 'finger1',
+                        parameters: { pointerType: 'touch' },
+                        actions: [
+                            { type: 'pointerMove', duration: 0, x, y: fromY },
+                            { type: 'pointerDown', button: 0 },
+                            { type: 'pointerMove', duration: opts?.duration ?? 600, x, y: toY },
+                            { type: 'pointerUp', button: 0 },
+                        ],
+                    },
+                ]);
+            }
+            finally {
+                await driver.releaseActions().catch(() => { });
+            }
+        }
+    }
+    async scrollUntilVisible(opts) {
+        const direction = opts?.direction ?? 'down';
+        const maxAttempts = opts?.maxAttempts ?? 10;
+        const visibleTimeout = opts?.visibleTimeout ?? 500;
+        const driver = this.ctx.driver;
+        if (!opts?.forceGesture) {
+            if (this.ctx.platform === Platform.IOS) {
+                const id = await this.resolveOnce();
+                if (id) {
+                    try {
+                        await driver.executeScript('mobile: scroll', [{ elementId: id, toVisible: true }]);
+                        return;
+                    }
+                    catch {
+                    }
+                }
+            }
+            else if (this.ctx.platform === Platform.ANDROID &&
+                this.strategy.using === '-android uiautomator') {
+                const wrapped = `new UiScrollable(new UiSelector().scrollable(true).instance(0)).scrollIntoView(${this.strategy.value})`;
+                try {
+                    await driver.findElement('-android uiautomator', wrapped);
+                    return;
+                }
+                catch {
+                }
+            }
+        }
+        for (let i = 0; i < maxAttempts; i++) {
+            if (await this.isVisible({ timeout: visibleTimeout }))
+                return;
+            const rect = await driver.getWindowRect();
+            const cx = Math.floor(rect.width / 2);
+            const cy = Math.floor(rect.height / 2);
+            const span = Math.floor(Math.min(rect.width, rect.height) * (opts?.distance ?? 0.4));
+            const defaultFromX = direction === 'left' ? cx - span : direction === 'right' ? cx + span : cx;
+            const defaultFromY = direction === 'up' ? cy - span : direction === 'down' ? cy + span : cy;
+            const defaultToX = direction === 'left' ? cx + span : direction === 'right' ? cx - span : cx;
+            const defaultToY = direction === 'up' ? cy + span : direction === 'down' ? cy - span : cy;
+            const fromX = opts?.from?.x !== undefined ? Math.floor(rect.width * opts.from.x) : defaultFromX;
+            const fromY = opts?.from?.y !== undefined ? Math.floor(rect.height * opts.from.y) : defaultFromY;
+            const toX = opts?.to?.x !== undefined ? Math.floor(rect.width * opts.to.x) : defaultToX;
+            const toY = opts?.to?.y !== undefined ? Math.floor(rect.height * opts.to.y) : defaultToY;
+            try {
+                await driver.performActions([
+                    {
+                        type: 'pointer',
+                        id: 'finger1',
+                        parameters: { pointerType: 'touch' },
+                        actions: [
+                            { type: 'pointerMove', duration: 0, x: fromX, y: fromY },
+                            { type: 'pointerDown', button: 0 },
+                            { type: 'pointerMove', duration: opts?.duration ?? 300, x: toX, y: toY },
+                            { type: 'pointerUp', button: 0 },
+                        ],
+                    },
+                ]);
+            }
+            finally {
+                await driver.releaseActions().catch(() => { });
+            }
+        }
+        if (await this.isVisible({ timeout: visibleTimeout }))
+            return;
+        throw new Error(`scrollIntoView: locator (${this.strategy.using}=${this.strategy.value}) did not become visible after ${maxAttempts} ${direction} swipe attempt(s)`);
+    }
+    async swipeLeft(opts) {
+        return this.swipeElement('left', opts);
+    }
+    async swipeRight(opts) {
+        return this.swipeElement('right', opts);
+    }
+    async swipeUp(opts) {
+        return this.swipeElement('up', opts);
+    }
+    async swipeDown(opts) {
+        return this.swipeElement('down', opts);
+    }
+    async pinchIn(opts) {
+        const id = await this.resolveActionable(opts);
+        if (this.ctx.platform === Platform.IOS) {
+            await this.iosTwoFingerPinch(id, 'in');
+        }
+        else {
+            await this.ctx.driver.executeScript('mobile: pinchCloseGesture', [
+                { elementId: id, percent: 0.75 },
+            ]);
+        }
+    }
+    async pinchOut(opts) {
+        const id = await this.resolveActionable(opts);
+        if (this.ctx.platform === Platform.IOS) {
+            await this.iosTwoFingerPinch(id, 'out');
+        }
+        else {
+            await this.ctx.driver.executeScript('mobile: pinchOpenGesture', [
+                { elementId: id, percent: 0.75 },
+            ]);
+        }
+    }
+    async iosTwoFingerPinch(id, mode) {
+        const driver = this.ctx.driver;
+        const rect = await driver.getElementRect(id);
+        const cx = Math.floor(rect.x + rect.width / 2);
+        const cy = Math.floor(rect.y + rect.height / 2);
+        const span = Math.max(20, Math.floor(Math.min(rect.width, rect.height) * 0.4));
+        const close = Math.max(8, Math.floor(span * 0.25));
+        const fromOffset = mode === 'in' ? span : close;
+        const toOffset = mode === 'in' ? close : span;
+        try {
+            await driver.performActions([
+                {
+                    type: 'pointer',
+                    id: 'finger1',
+                    parameters: { pointerType: 'touch' },
+                    actions: [
+                        { type: 'pointerMove', duration: 0, x: cx - fromOffset, y: cy },
+                        { type: 'pointerDown', button: 0 },
+                        { type: 'pause', duration: 100 },
+                        { type: 'pointerMove', duration: 400, x: cx - toOffset, y: cy },
+                        { type: 'pointerUp', button: 0 },
+                    ],
+                },
+                {
+                    type: 'pointer',
+                    id: 'finger2',
+                    parameters: { pointerType: 'touch' },
+                    actions: [
+                        { type: 'pointerMove', duration: 0, x: cx + fromOffset, y: cy },
+                        { type: 'pointerDown', button: 0 },
+                        { type: 'pause', duration: 100 },
+                        { type: 'pointerMove', duration: 400, x: cx + toOffset, y: cy },
+                        { type: 'pointerUp', button: 0 },
+                    ],
+                },
+            ]);
+        }
+        finally {
+            await driver.releaseActions().catch(() => {
+            });
+        }
+    }
+    async dragTo(target, opts) {
+        const sourceId = await this.resolveActionable(opts);
+        const targetId = await target.resolveActionable(opts);
+        const driver = this.ctx.driver;
+        const sourceRect = await driver.getElementRect(sourceId);
+        const targetRect = await driver.getElementRect(targetId);
+        const fromX = Math.floor(sourceRect.x + sourceRect.width * (opts?.from?.x ?? 0.5));
+        const fromY = Math.floor(sourceRect.y + sourceRect.height * (opts?.from?.y ?? 0.5));
+        const toX = Math.floor(targetRect.x + targetRect.width * (opts?.to?.x ?? 0.5));
+        const toY = Math.floor(targetRect.y + targetRect.height * (opts?.to?.y ?? 0.5));
+        await this.executeDrag({ x: fromX, y: fromY }, { x: toX, y: toY }, opts);
+    }
+    async dragToPoint(point, opts) {
+        const sourceId = await this.resolveActionable(opts);
+        const driver = this.ctx.driver;
+        const sourceRect = await driver.getElementRect(sourceId);
+        const fromX = Math.floor(sourceRect.x + sourceRect.width * (opts?.from?.x ?? 0.5));
+        const fromY = Math.floor(sourceRect.y + sourceRect.height * (opts?.from?.y ?? 0.5));
+        await this.executeDrag({ x: fromX, y: fromY }, point, opts);
+    }
+    async isVisible(opts) {
+        const timeout = opts?.timeout ?? this.ctx.defaultTimeout;
+        const deadline = Date.now() + timeout;
+        while (Date.now() < deadline) {
+            const id = await this.resolveOnce();
+            if (id) {
+                try {
+                    if (await this.ctx.driver.isElementDisplayed(id))
+                        return true;
+                }
+                catch {
+                }
+            }
+            await sleep(POLL_INTERVAL);
+        }
+        return false;
+    }
+    async isEnabled(opts) {
+        const id = await this.resolveActionable(opts);
+        return this.ctx.driver.isElementEnabled(id);
+    }
+    async getText(opts) {
+        const id = await this.resolveVisible(opts);
+        return this.ctx.driver.getElementText(id);
+    }
+    async getValue(opts) {
+        const id = await this.resolveVisible(opts);
+        if (this.ctx.platform === Platform.ANDROID) {
+            const text = await this.ctx.driver.getElementAttribute(id, 'text');
+            if (text !== null && text !== undefined)
+                return text;
+            return (await this.ctx.driver.getElementText(id).catch(() => '')) ?? '';
+        }
+        const attr = await this.ctx.driver.getElementAttribute(id, 'value');
+        return attr ?? '';
+    }
+    async boundingBox(opts) {
+        const id = await this.resolveVisible(opts);
+        const rect = await this.ctx.driver.getElementRect(id);
+        return { x: rect.x, y: rect.y, width: rect.width, height: rect.height };
+    }
+    async getAttribute(name, opts) {
+        const id = await this.resolveVisible(opts);
+        const v = await this.ctx.driver.getElementAttribute(id, name).catch(() => null);
+        return v ?? null;
+    }
+    async isFocused(opts) {
+        const id = await this.resolveVisible(opts);
+        if (this.ctx.platform === Platform.ANDROID) {
+            const v = await this.ctx.driver.getElementAttribute(id, 'focused').catch(() => null);
+            return v === 'true';
+        }
+        const v = await this.ctx.driver.getElementAttribute(id, 'hasKeyboardFocus').catch(() => null);
+        if (v === 'true' || v === '1')
+            return true;
+        if (v === 'false' || v === '0')
+            return false;
+        const alt = await this.ctx.driver.getElementAttribute(id, 'focused').catch(() => null);
+        return alt === 'true' || alt === '1';
+    }
+    async isEditable(opts) {
+        const id = await this.resolveVisible(opts);
+        const enabled = await this.ctx.driver.isElementEnabled(id).catch(() => false);
+        if (!enabled)
+            return false;
+        if (this.ctx.platform === Platform.ANDROID) {
+            const cls = await this.ctx.driver.getElementAttribute(id, 'class').catch(() => null);
+            return typeof cls === 'string' && cls.includes('EditText');
+        }
+        const type = await this.ctx.driver.getElementAttribute(id, 'type').catch(() => null);
+        return (type === 'XCUIElementTypeTextField' ||
+            type === 'XCUIElementTypeSecureTextField' ||
+            type === 'XCUIElementTypeTextView');
+    }
+    async isInViewport(opts) {
+        const id = await this.resolveVisible(opts);
+        try {
+            const [rect, win] = await Promise.all([
+                this.ctx.driver.getElementRect(id),
+                this.ctx.driver.getWindowRect(),
+            ]);
+            if (rect.width <= 0 || rect.height <= 0)
+                return false;
+            return (rect.x < win.width &&
+                rect.x + rect.width > 0 &&
+                rect.y < win.height &&
+                rect.y + rect.height > 0);
+        }
+        catch {
+            return false;
+        }
+    }
+    async isEmpty(opts) {
+        const id = await this.resolveVisible(opts);
+        try {
+            const children = (await this.ctx.driver.findElementsFromElement(id, 'xpath', './*'));
+            if (children && children.length > 0)
+                return false;
+        }
+        catch {
+        }
+        const text = await this.readElementText(id);
+        return text.length === 0;
+    }
+    async assertVisible(opts) {
+        return this.waitFor({ state: 'visible', timeout: opts?.timeout });
+    }
+    async assertHidden(opts) {
+        return this.waitFor({ state: 'hidden', timeout: opts?.timeout });
+    }
+    async assertEnabled(opts) {
+        return this.waitFor({ state: 'enabled', timeout: opts?.timeout });
+    }
+    async assertDisabled(opts) {
+        return this.waitFor({ state: 'disabled', timeout: opts?.timeout });
+    }
+    async assertChecked(opts) {
+        return this.waitForChecked(true, opts);
+    }
+    async assertUnchecked(opts) {
+        return this.waitForChecked(false, opts);
+    }
+    async assertAttached(opts) {
+        return this.waitFor({ state: 'attached', timeout: opts?.timeout });
+    }
+    async assertEditable(opts) {
+        await this.pollBooleanQuery('editable', () => this.isEditable(opts), true, opts);
+    }
+    async assertReadonly(opts) {
+        await this.pollBooleanQuery('editable', () => this.isEditable(opts), false, opts);
+    }
+    async assertFocused(opts) {
+        await this.pollBooleanQuery('focused', () => this.isFocused(opts), true, opts);
+    }
+    async assertEmpty(opts) {
+        await this.pollBooleanQuery('empty', () => this.isEmpty(opts), true, opts);
+    }
+    async assertInViewport(opts) {
+        await this.pollBooleanQuery('inViewport', () => this.isInViewport(opts), true, opts);
+    }
+    async assertCount(expected, opts) {
+        const timeout = opts?.timeout ?? this.ctx.defaultTimeout;
+        const deadline = Date.now() + timeout;
+        let last = -1;
+        while (Date.now() < deadline) {
+            try {
+                last = await this.count();
+                if (last === expected)
+                    return;
+            }
+            catch {
+            }
+            await sleep(POLL_INTERVAL);
+        }
+        throw new Error(`assertCount: expected ${expected} but found ${last} within ${timeout}ms ` +
+            `(${this.strategy.using}=${this.strategy.value})`);
+    }
+    async assertAttribute(name, expected, opts) {
+        const predicate = typeof expected === 'string'
+            ? (v) => v === expected
+            : (v) => v !== null && expected.test(v);
+        const timeout = opts?.timeout ?? this.ctx.defaultTimeout;
+        const deadline = Date.now() + timeout;
+        let last = null;
+        while (Date.now() < deadline) {
+            const id = await this.resolveOnce();
+            if (id) {
+                last = await this.ctx.driver.getElementAttribute(id, name).catch(() => null);
+                if (predicate(last))
+                    return;
+            }
+            await sleep(POLL_INTERVAL);
+        }
+        const expectedStr = expected instanceof RegExp ? expected.toString() : JSON.stringify(expected);
+        throw new Error(`assertAttribute(${JSON.stringify(name)}): expected ${expectedStr} within ${timeout}ms ` +
+            `(got: ${last !== null ? JSON.stringify(last) : '<null>'})`);
+    }
+    async pollBooleanQuery(label, getter, expected, opts) {
+        const timeout = opts?.timeout ?? this.ctx.defaultTimeout;
+        const deadline = Date.now() + timeout;
+        let last;
+        while (Date.now() < deadline) {
+            try {
+                last = await getter();
+                if (last === expected)
+                    return;
+            }
+            catch {
+            }
+            await sleep(POLL_INTERVAL);
+        }
+        throw new Error(`assert ${label}: expected ${expected} within ${timeout}ms (last: ${last ?? '<unresolved>'})`);
+    }
+    async assertText(expected, opts) {
+        const predicate = typeof expected === 'string'
+            ? (v) => v === expected
+            : (v) => expected.test(v);
+        await this.assertGetter('text', () => this.getText(), predicate, expected, opts);
+    }
+    async assertContainsText(expected, opts) {
+        await this.assertGetter('text', () => this.getText(), (v) => v.includes(expected), `contains ${JSON.stringify(expected)}`, opts);
+    }
+    async assertValue(expected, opts) {
+        const predicate = typeof expected === 'string'
+            ? (v) => v === expected
+            : (v) => expected.test(v);
+        await this.assertGetter('value', () => this.getValue(), predicate, expected, opts);
+    }
+    async assertGetter(field, getter, predicate, expected, opts) {
+        const timeout = opts?.timeout ?? this.ctx.defaultTimeout;
+        const deadline = Date.now() + timeout;
+        let last;
+        while (Date.now() < deadline) {
+            try {
+                last = await getter();
+                if (predicate(last))
+                    return;
+            }
+            catch {
+            }
+            await sleep(POLL_INTERVAL);
+        }
+        const expectedStr = expected instanceof RegExp ? expected.toString() : JSON.stringify(expected);
+        throw new Error(`assert ${field}: expected ${expectedStr} within ${timeout}ms ` +
+            `(got: ${last !== undefined ? JSON.stringify(last) : '<unresolved>'})`);
+    }
+    async waitFor(opts) {
+        const state = opts?.state ?? 'visible';
+        const timeout = opts?.timeout ?? this.ctx.defaultTimeout;
+        const deadline = Date.now() + timeout;
+        while (Date.now() < deadline) {
+            if (await this.matchesState(state))
+                return;
+            await sleep(POLL_INTERVAL);
+        }
+        throw new Error(`waitFor: locator (${this.strategy.using}=${this.strategy.value}) did not reach state "${state}" within ${timeout}ms`);
+    }
+    filter(opts) {
+        if (opts.visible === false) {
+            throw new Error('filter({ visible: false }) is not supported; use assertHidden or filter({ hasNot: ... }) instead');
+        }
+        return this.derive({
+            chainOps: [...this.state.chainOps, { kind: 'filter', filter: opts }],
+        });
+    }
+    first() {
+        return this.derive({ indexSelector: { kind: 'first' } });
+    }
+    last() {
+        return this.derive({ indexSelector: { kind: 'last' } });
+    }
+    nth(n) {
+        if (!Number.isInteger(n)) {
+            throw new Error(`Locator.nth(${n}): index must be an integer`);
+        }
+        return this.derive({ indexSelector: { kind: 'nth', n } });
+    }
+    locator(child) {
+        let childLoc;
+        if (child instanceof Locator) {
+            if (child.ctx !== this.ctx) {
+                throw new Error('locator.locator(): child Locator was created against a different Mobile/session');
+            }
+            childLoc = child;
+        }
+        else {
+            childLoc = Locator.fromStrategy(this.ctx, child);
+        }
+        return childLoc.rebaseRoot(this);
+    }
+    and(other) {
+        if (other.ctx !== this.ctx) {
+            throw new Error('Locator.and(): other Locator was created against a different Mobile/session');
+        }
+        return this.derive({
+            chainOps: [...this.state.chainOps, { kind: 'and', other }],
+        });
+    }
+    or(other) {
+        if (other.ctx !== this.ctx) {
+            throw new Error('Locator.or(): other Locator was created against a different Mobile/session');
+        }
+        return this.derive({
+            chainOps: [...this.state.chainOps, { kind: 'or', other }],
+        });
+    }
+    async count() {
+        return (await this.resolveAll()).length;
+    }
+    async all() {
+        const n = (await this.resolveAll()).length;
+        return Array.from({ length: n }, (_, i) => this.nth(i));
+    }
+    async allInnerTexts() {
+        const ids = await this.resolveAll();
+        return Promise.all(ids.map((id) => this.readElementText(id)));
+    }
+    async allTextContents() {
+        return this.allInnerTexts();
+    }
+    async readElementText(id) {
+        const text = await this.ctx.driver.getElementText(id).catch(() => '');
+        if (text)
+            return text;
+        if (this.ctx.platform === Platform.ANDROID) {
+            const attr = await this.ctx.driver.getElementAttribute(id, 'text').catch(() => null);
+            if (attr !== null && attr !== undefined)
+                return attr;
+        }
+        return '';
+    }
+    async matchesState(state) {
+        const id = await this.resolveOnce();
+        if (state === 'attached')
+            return id !== null;
+        if (state === 'hidden') {
+            if (!id)
+                return true;
+            try {
+                return !(await this.ctx.driver.isElementDisplayed(id));
+            }
+            catch {
+                return true;
+            }
+        }
+        if (!id)
+            return false;
+        try {
+            if (state === 'visible')
+                return await this.ctx.driver.isElementDisplayed(id);
+            if (state === 'enabled')
+                return await this.ctx.driver.isElementEnabled(id);
+            if (state === 'disabled')
+                return !(await this.ctx.driver.isElementEnabled(id));
+        }
+        catch {
+            return false;
+        }
+        return false;
+    }
+    async resolveAll() {
+        if (this.pinnedIds !== undefined) {
+            return [...this.pinnedIds];
+        }
+        let candidates = [];
+        const shortCircuitFirst = this.state.indexSelector?.kind === 'first' &&
+            this.state.chainOps.length === 0 &&
+            this.strategy.textFilter === undefined;
+        if (this.state.parent) {
+            let parentIds;
+            try {
+                parentIds = await this.state.parent.resolveAll();
+            }
+            catch {
+                parentIds = [];
+            }
+            const seen = new Set();
+            outer: for (const pid of parentIds) {
+                try {
+                    const refs = (await this.ctx.driver.findElementsFromElement(pid, this.strategy.using, this.strategy.value));
+                    for (const ref of refs ?? []) {
+                        const id = ref[W3C_ELEMENT_KEY];
+                        if (!seen.has(id)) {
+                            seen.add(id);
+                            candidates.push(id);
+                            if (shortCircuitFirst)
+                                break outer;
+                        }
+                    }
+                }
+                catch {
+                }
+            }
+        }
+        else {
+            try {
+                const refs = (await this.ctx.driver.findElements(this.strategy.using, this.strategy.value));
+                candidates = (refs ?? []).map((r) => r[W3C_ELEMENT_KEY]);
+            }
+            catch {
+                candidates = [];
+            }
+        }
+        if (this.strategy.textFilter !== undefined) {
+            candidates = await this.filterIdsByText(candidates, this.strategy.textFilter, true);
+        }
+        for (const op of this.state.chainOps) {
+            if (candidates.length === 0)
+                break;
+            if (op.kind === 'filter') {
+                candidates = await this.applyFilterOp(candidates, op.filter);
+            }
+            else if (op.kind === 'and') {
+                const otherIds = new Set(await op.other.resolveAll());
+                candidates = candidates.filter((id) => otherIds.has(id));
+            }
+            else if (op.kind === 'or') {
+                const others = await op.other.resolveAll();
+                const seen = new Set(candidates);
+                for (const id of others) {
+                    if (!seen.has(id)) {
+                        seen.add(id);
+                        candidates.push(id);
+                    }
+                }
+            }
+        }
+        if (this.state.indexSelector) {
+            const sel = this.state.indexSelector;
+            if (sel.kind === 'first') {
+                return candidates.length > 0 ? [candidates[0]] : [];
+            }
+            if (sel.kind === 'last') {
+                return candidates.length > 0 ? [candidates[candidates.length - 1]] : [];
+            }
+            const picked = candidates.at(sel.n);
+            return picked !== undefined ? [picked] : [];
+        }
+        return candidates;
+    }
+    async resolveOnce() {
+        try {
+            const ids = await this.resolveAll();
+            return ids[0] ?? null;
+        }
+        catch {
+            return null;
+        }
+    }
+    async elementMatchesText(id, pattern, exact) {
+        const matchOne = (s) => {
+            if (s === null || s === undefined)
+                return false;
+            if (typeof pattern === 'string') {
+                return exact ? s === pattern : s.includes(pattern);
+            }
+            return pattern.test(s);
+        };
+        const labelAttr = this.ctx.platform === Platform.IOS ? 'name' : 'content-desc';
+        const probes = await Promise.all([
+            this.ctx.driver.getElementText(id).catch(() => null),
+            this.ctx.driver.getElementAttribute(id, 'value').catch(() => null),
+            this.ctx.driver.getElementAttribute(id, labelAttr).catch(() => null),
+        ]);
+        return probes.some(matchOne);
+    }
+    async filterIdsByText(ids, pattern, exact) {
+        const out = [];
+        for (const id of ids) {
+            if (await this.elementMatchesText(id, pattern, exact))
+                out.push(id);
+        }
+        return out;
+    }
+    async applyFilterOp(candidates, filter) {
+        if (filter.visible === false) {
+            throw new Error('filter({ visible: false }) is not supported; use assertHidden or filter({ hasNot: ... }) instead');
+        }
+        const out = [];
+        for (const id of candidates) {
+            if (filter.visible === true) {
+                const ok = await this.ctx.driver.isElementDisplayed(id).catch(() => false);
+                if (!ok)
+                    continue;
+            }
+            if (filter.hasText !== undefined) {
+                if (!(await this.elementMatchesText(id, filter.hasText, false)))
+                    continue;
+            }
+            if (filter.hasNotText !== undefined) {
+                if (await this.elementMatchesText(id, filter.hasNotText, false))
+                    continue;
+            }
+            if (filter.has) {
+                if (!(await this.existsUnder(id, filter.has)))
+                    continue;
+            }
+            if (filter.hasNot) {
+                if (await this.existsUnder(id, filter.hasNot))
+                    continue;
+            }
+            out.push(id);
+        }
+        return out;
+    }
+    async existsUnder(parentId, child) {
+        const pinned = Locator.pinnedToIds(this.ctx, [parentId]);
+        const rooted = child.rebaseRoot(pinned);
+        const ids = await rooted.resolveAll();
+        return ids.length > 0;
+    }
+    async resolveVisible(opts) {
+        await this.waitFor({ state: 'visible', timeout: opts?.timeout });
+        const id = await this.resolveOnce();
+        if (!id) {
+            throw new Error(`Element (${this.strategy.using}=${this.strategy.value}) disappeared after being found`);
+        }
+        return id;
+    }
+    async resolveActionable(opts, retried = false) {
+        const id = await this.resolveVisible(opts);
+        try {
+            const enabled = await this.ctx.driver.isElementEnabled(id);
+            if (enabled)
+                return id;
+            throw new Error(`Element (${this.strategy.using}=${this.strategy.value}) is visible but not enabled`);
+        }
+        catch (err) {
+            if (err instanceof Error && err.message.includes('not enabled'))
+                throw err;
+            if (retried)
+                throw err;
+            return this.resolveActionable(opts, true);
+        }
+    }
+    async swipeElement(direction, opts) {
+        const id = await this.resolveActionable();
+        const driver = this.ctx.driver;
+        const hasOverride = opts?.from !== undefined || opts?.to !== undefined;
+        if (!hasOverride) {
+            if (this.ctx.platform === Platform.IOS) {
+                if (opts?.distance === undefined) {
+                    try {
+                        await driver.executeScript('mobile: swipe', [{ elementId: id, direction }]);
+                        return;
+                    }
+                    catch {
+                    }
+                }
+            }
+            else if (this.ctx.platform === Platform.ANDROID) {
+                try {
+                    await driver.executeScript('mobile: swipeGesture', [
+                        { elementId: id, direction, percent: opts?.distance ?? 0.4 },
+                    ]);
+                    return;
+                }
+                catch {
+                }
+            }
+        }
+        const rect = await driver.getElementRect(id);
+        const cx = Math.floor(rect.x + rect.width / 2);
+        const cy = Math.floor(rect.y + rect.height / 2);
+        const span = Math.floor(Math.min(rect.width, rect.height) * (opts?.distance ?? 0.4));
+        const defaultFromX = direction === 'left' ? cx + span : direction === 'right' ? cx - span : cx;
+        const defaultFromY = direction === 'up' ? cy + span : direction === 'down' ? cy - span : cy;
+        const defaultToX = direction === 'left' ? cx - span : direction === 'right' ? cx + span : cx;
+        const defaultToY = direction === 'up' ? cy - span : direction === 'down' ? cy + span : cy;
+        const fromX = opts?.from?.x !== undefined ? Math.floor(rect.x + rect.width * opts.from.x) : defaultFromX;
+        const fromY = opts?.from?.y !== undefined ? Math.floor(rect.y + rect.height * opts.from.y) : defaultFromY;
+        const toX = opts?.to?.x !== undefined ? Math.floor(rect.x + rect.width * opts.to.x) : defaultToX;
+        const toY = opts?.to?.y !== undefined ? Math.floor(rect.y + rect.height * opts.to.y) : defaultToY;
+        try {
+            await driver.performActions([
+                {
+                    type: 'pointer',
+                    id: 'finger1',
+                    parameters: { pointerType: 'touch' },
+                    actions: [
+                        { type: 'pointerMove', duration: 0, x: fromX, y: fromY },
+                        { type: 'pointerDown', button: 0 },
+                        { type: 'pointerMove', duration: opts?.duration ?? 300, x: toX, y: toY },
+                        { type: 'pointerUp', button: 0 },
+                    ],
+                },
+            ]);
+        }
+        finally {
+            await driver.releaseActions().catch(() => { });
+        }
+    }
+    async executeDrag(from, to, opts) {
+        const driver = this.ctx.driver;
+        const holdMs = opts?.duration ?? 500;
+        if (this.ctx.platform === Platform.IOS) {
+            try {
+                await driver.executeScript('mobile: dragFromToForDuration', [
+                    {
+                        duration: holdMs / 1000,
+                        fromX: from.x,
+                        fromY: from.y,
+                        toX: to.x,
+                        toY: to.y,
+                    },
+                ]);
+                return;
+            }
+            catch {
+            }
+        }
+        else if (this.ctx.platform === Platform.ANDROID) {
+            try {
+                await driver.executeScript('mobile: dragGesture', [
+                    {
+                        startX: from.x,
+                        startY: from.y,
+                        endX: to.x,
+                        endY: to.y,
+                        speed: opts?.speed ?? 2500,
+                    },
+                ]);
+                return;
+            }
+            catch {
+            }
+        }
+        const moveMs = opts?.moveDuration ?? 300;
+        try {
+            await driver.performActions([
+                {
+                    type: 'pointer',
+                    id: 'finger1',
+                    parameters: { pointerType: 'touch' },
+                    actions: [
+                        { type: 'pointerMove', duration: 0, x: from.x, y: from.y },
+                        { type: 'pointerDown', button: 0 },
+                        { type: 'pause', duration: holdMs },
+                        { type: 'pointerMove', duration: moveMs, x: to.x, y: to.y },
+                        { type: 'pointerUp', button: 0 },
+                    ],
+                },
+            ]);
+        }
+        finally {
+            await driver.releaseActions().catch(() => { });
+        }
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function isInvalidElementState(err) {
+    const msg = err?.message ?? String(err);
+    return /invalid element state|Cannot set the element/i.test(msg);
+}
+function parseDateOrTime(input) {
+    if (input.date) {
+        const m = input.date.match(/^(\d{4})-(\d{2})-(\d{2})$/);
+        if (!m) {
+            throw new Error(`selectOption: invalid date "${input.date}" — expected YYYY-MM-DD`);
+        }
+        const monthIdx = Number(m[2]) - 1;
+        const monthNames = [
+            'January',
+            'February',
+            'March',
+            'April',
+            'May',
+            'June',
+            'July',
+            'August',
+            'September',
+            'October',
+            'November',
+            'December',
+        ];
+        return [m[1], monthNames[monthIdx] ?? m[2], m[3]];
+    }
+    if (input.time) {
+        const m = input.time.match(/^(\d{1,2}):(\d{2})$/);
+        if (!m) {
+            throw new Error(`selectOption: invalid time "${input.time}" — expected HH:mm`);
+        }
+        return [m[1], m[2]];
+    }
+    return [];
+}
+function xpathLiteral(s) {
+    if (!s.includes("'"))
+        return `'${s}'`;
+    if (!s.includes('"'))
+        return `"${s}"`;
+    const parts = s.split("'");
+    const pieces = [];
+    parts.forEach((part, i) => {
+        if (i > 0)
+            pieces.push(`"'"`);
+        if (part.length > 0)
+            pieces.push(`'${part}'`);
+    });
+    return `concat(${pieces.join(', ')})`;
+}
+export { DEFAULT_TIMEOUT as DEFAULT_LOCATOR_TIMEOUT };
+export function buildLocatorFromDescriptor(ctx, desc) {
+    switch (desc.kind) {
+        case 'leaf': {
+            const strategy = { using: desc.using, value: desc.value };
+            const tf = deserializeText(desc.textFilter);
+            if (tf !== undefined)
+                strategy.textFilter = tf;
+            return Locator.fromStrategy(ctx, strategy);
+        }
+        case 'first':
+            return buildLocatorFromDescriptor(ctx, desc.on).first();
+        case 'last':
+            return buildLocatorFromDescriptor(ctx, desc.on).last();
+        case 'nth':
+            return buildLocatorFromDescriptor(ctx, desc.on).nth(desc.n);
+        case 'filter': {
+            const base = buildLocatorFromDescriptor(ctx, desc.on);
+            return base.filter(deserializeFilter(ctx, desc.filter));
+        }
+        case 'child': {
+            const parent = buildLocatorFromDescriptor(ctx, desc.parent);
+            const child = buildLocatorFromDescriptor(ctx, desc.child);
+            return parent.locator(child);
+        }
+        case 'and': {
+            const left = buildLocatorFromDescriptor(ctx, desc.left);
+            const right = buildLocatorFromDescriptor(ctx, desc.right);
+            return left.and(right);
+        }
+        case 'or': {
+            const left = buildLocatorFromDescriptor(ctx, desc.left);
+            const right = buildLocatorFromDescriptor(ctx, desc.right);
+            return left.or(right);
+        }
+    }
+}
+function deserializeText(t) {
+    if (t === undefined)
+        return undefined;
+    if (typeof t === 'string')
+        return t;
+    return new RegExp(t.regex, t.flags);
+}
+function deserializeFilter(ctx, f) {
+    const out = {};
+    if (f.has)
+        out.has = buildLocatorFromDescriptor(ctx, f.has);
+    if (f.hasNot)
+        out.hasNot = buildLocatorFromDescriptor(ctx, f.hasNot);
+    const ht = deserializeText(f.hasText);
+    if (ht !== undefined)
+        out.hasText = ht;
+    const hnt = deserializeText(f.hasNotText);
+    if (hnt !== undefined)
+        out.hasNotText = hnt;
+    if (f.visible !== undefined)
+        out.visible = f.visible;
+    return out;
+}