@midscene/android 0.26.2 → 0.26.3-beta-20250813075706.0

package/dist/es/index.mjs

@@ -0,0 +1,711 @@
+import node_assert from "node:assert";
+import { randomUUID } from "node:crypto";
+import node_fs from "node:fs";
+import node_path from "node:path";
+import { getAIConfig } from "@midscene/core";
+import { getTmpFile, sleep } from "@midscene/core/utils";
+import { MIDSCENE_ADB_PATH, MIDSCENE_ADB_REMOTE_HOST, MIDSCENE_ADB_REMOTE_PORT, MIDSCENE_ANDROID_IME_STRATEGY, overrideAIConfig, vlLocateMode } from "@midscene/shared/env";
+import { isValidPNGImageBuffer, resizeImg } from "@midscene/shared/img";
+import { getDebug } from "@midscene/shared/logger";
+import { repeat } from "@midscene/shared/utils";
+import { commonWebActions } from "@midscene/web";
+import { ADB } from "appium-adb";
+import { PageAgent } from "@midscene/web/agent";
+function _define_property(obj, key, value) {
+    if (key in obj) Object.defineProperty(obj, key, {
+        value: value,
+        enumerable: true,
+        configurable: true,
+        writable: true
+    });
+    else obj[key] = value;
+    return obj;
+}
+const defaultScrollUntilTimes = 10;
+const defaultFastScrollDuration = 100;
+const defaultNormalScrollDuration = 1000;
+const debugPage = getDebug('android:device');
+const asyncNoop = async ()=>{};
+const androidActions = [
+    {
+        name: 'AndroidBackButton',
+        description: 'Trigger the system "back" operation on Android devices',
+        location: false,
+        call: asyncNoop
+    },
+    {
+        name: 'AndroidHomeButton',
+        description: 'Trigger the system "home" operation on Android devices',
+        location: false,
+        call: asyncNoop
+    },
+    {
+        name: 'AndroidRecentAppsButton',
+        description: 'Trigger the system "recent apps" operation on Android devices',
+        location: false,
+        call: asyncNoop
+    },
+    {
+        name: 'AndroidLongPress',
+        description: 'Trigger a long press on the screen at specified coordinates on Android devices',
+        paramSchema: '{ duration?: number }',
+        paramDescription: 'The duration of the long press',
+        location: 'optional',
+        whatToLocate: 'The element to be long pressed',
+        call: asyncNoop
+    },
+    {
+        name: 'AndroidPull',
+        description: 'Trigger pull down to refresh or pull up actions on Android devices',
+        paramSchema: '{ direction: "up" | "down", distance?: number, duration?: number }',
+        paramDescription: 'The direction to pull, the distance to pull, and the duration of the pull.',
+        location: 'optional',
+        whatToLocate: 'The element to be pulled',
+        call: asyncNoop
+    }
+];
+class AndroidDevice {
+    actionSpace() {
+        return commonWebActions.concat(androidActions);
+    }
+    async connect() {
+        return this.getAdb();
+    }
+    async getAdb() {
+        if (this.destroyed) throw new Error(`AndroidDevice ${this.deviceId} has been destroyed and cannot execute ADB commands`);
+        if (this.adb) return this.createAdbProxy(this.adb);
+        if (this.connectingAdb) return this.connectingAdb.then((adb)=>this.createAdbProxy(adb));
+        this.connectingAdb = (async ()=>{
+            let error = null;
+            debugPage(`Initializing ADB with device ID: ${this.deviceId}`);
+            try {
+                var _this_options, _this_options1, _this_options2;
+                const androidAdbPath = (null == (_this_options = this.options) ? void 0 : _this_options.androidAdbPath) || getAIConfig(MIDSCENE_ADB_PATH);
+                const remoteAdbHost = (null == (_this_options1 = this.options) ? void 0 : _this_options1.remoteAdbHost) || getAIConfig(MIDSCENE_ADB_REMOTE_HOST);
+                const remoteAdbPort = (null == (_this_options2 = this.options) ? void 0 : _this_options2.remoteAdbPort) || getAIConfig(MIDSCENE_ADB_REMOTE_PORT);
+                this.adb = await new ADB({
+                    udid: this.deviceId,
+                    adbExecTimeout: 60000,
+                    executable: androidAdbPath ? {
+                        path: androidAdbPath,
+                        defaultArgs: []
+                    } : void 0,
+                    remoteAdbHost: remoteAdbHost || void 0,
+                    remoteAdbPort: remoteAdbPort ? Number(remoteAdbPort) : void 0
+                });
+                const size = await this.getScreenSize();
+                console.log(`
+DeviceId: ${this.deviceId}
+ScreenSize:
+${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[key]}${'override' === key && size[key] ? " \u2705" : ''}`).join('\n')}
+`);
+                debugPage('ADB initialized successfully');
+                return this.adb;
+            } catch (e) {
+                debugPage(`Failed to initialize ADB: ${e}`);
+                error = new Error(`Unable to connect to device ${this.deviceId}: ${e}`);
+            } finally{
+                this.connectingAdb = null;
+            }
+            if (error) throw error;
+            throw new Error('ADB initialization failed unexpectedly');
+        })();
+        return this.connectingAdb;
+    }
+    createAdbProxy(adb) {
+        return new Proxy(adb, {
+            get: (target, prop)=>{
+                const originalMethod = target[prop];
+                if ('function' != typeof originalMethod) return originalMethod;
+                return async (...args)=>{
+                    try {
+                        debugPage(`adb ${String(prop)} ${args.join(' ')}`);
+                        const result = await originalMethod.apply(target, args);
+                        debugPage(`adb ${String(prop)} ${args.join(' ')} end`);
+                        return result;
+                    } catch (error) {
+                        const methodName = String(prop);
+                        const deviceId = this.deviceId;
+                        debugPage(`ADB error with device ${deviceId} when calling ${methodName}: ${error}`);
+                        throw new Error(`ADB error with device ${deviceId} when calling ${methodName}, please check https://midscenejs.com/integrate-with-android.html#faq : ${error.message}`, {
+                            cause: error
+                        });
+                    }
+                };
+            }
+        });
+    }
+    async launch(uri) {
+        const adb = await this.getAdb();
+        this.uri = uri;
+        try {
+            debugPage(`Launching app: ${uri}`);
+            if (uri.startsWith('http://') || uri.startsWith('https://') || uri.includes('://')) await adb.startUri(uri);
+            else if (uri.includes('/')) {
+                const [appPackage, appActivity] = uri.split('/');
+                await adb.startApp({
+                    pkg: appPackage,
+                    activity: appActivity
+                });
+            } else await adb.activateApp(uri);
+            debugPage(`Successfully launched: ${uri}`);
+        } catch (error) {
+            debugPage(`Error launching ${uri}: ${error}`);
+            throw new Error(`Failed to launch ${uri}: ${error.message}`, {
+                cause: error
+            });
+        }
+        return this;
+    }
+    async execYadb(keyboardContent) {
+        await this.ensureYadb();
+        const adb = await this.getAdb();
+        await adb.shell(`app_process -Djava.class.path=/data/local/tmp/yadb /data/local/tmp com.ysbing.yadb.Main -keyboard "${keyboardContent}"`);
+    }
+    async getElementsInfo() {
+        return [];
+    }
+    async getElementsNodeTree() {
+        return {
+            node: null,
+            children: []
+        };
+    }
+    async getScreenSize() {
+        const adb = await this.getAdb();
+        const stdout = await adb.shell([
+            'wm',
+            'size'
+        ]);
+        const size = {
+            override: '',
+            physical: ''
+        };
+        const overrideSize = new RegExp(/Override size: ([^\r?\n]+)*/g).exec(stdout);
+        if (overrideSize && overrideSize.length >= 2 && overrideSize[1]) {
+            debugPage(`Using Override size: ${overrideSize[1].trim()}`);
+            size.override = overrideSize[1].trim();
+        }
+        const physicalSize = new RegExp(/Physical size: ([^\r?\n]+)*/g).exec(stdout);
+        if (physicalSize && physicalSize.length >= 2) {
+            debugPage(`Using Physical size: ${physicalSize[1].trim()}`);
+            size.physical = physicalSize[1].trim();
+        }
+        let orientation = 0;
+        try {
+            const orientationStdout = await adb.shell('dumpsys input | grep SurfaceOrientation');
+            const orientationMatch = orientationStdout.match(/SurfaceOrientation:\s*(\d)/);
+            if (!orientationMatch) throw new Error('Failed to get orientation from input');
+            orientation = Number(orientationMatch[1]);
+            debugPage(`Screen orientation: ${orientation}`);
+        } catch (e) {
+            debugPage('Failed to get orientation from input, try display');
+            try {
+                const orientationStdout = await adb.shell('dumpsys display | grep mCurrentOrientation');
+                const orientationMatch = orientationStdout.match(/mCurrentOrientation=(\d)/);
+                if (!orientationMatch) throw new Error('Failed to get orientation from display');
+                orientation = Number(orientationMatch[1]);
+                debugPage(`Screen orientation (fallback): ${orientation}`);
+            } catch (e2) {
+                orientation = 0;
+                debugPage('Failed to get orientation from display, default to 0');
+            }
+        }
+        if (size.override || size.physical) return {
+            ...size,
+            orientation
+        };
+        throw new Error(`Failed to get screen size, output: ${stdout}`);
+    }
+    async size() {
+        const adb = await this.getAdb();
+        const screenSize = await this.getScreenSize();
+        const match = (screenSize.override || screenSize.physical).match(/(\d+)x(\d+)/);
+        if (!match || match.length < 3) throw new Error(`Unable to parse screen size: ${screenSize}`);
+        const isLandscape = 1 === screenSize.orientation || 3 === screenSize.orientation;
+        const width = Number.parseInt(match[isLandscape ? 2 : 1], 10);
+        const height = Number.parseInt(match[isLandscape ? 1 : 2], 10);
+        const densityNum = await adb.getScreenDensity();
+        this.devicePixelRatio = Number(densityNum) / 160;
+        const { x: logicalWidth, y: logicalHeight } = this.reverseAdjustCoordinates(width, height);
+        return {
+            width: logicalWidth,
+            height: logicalHeight,
+            dpr: this.devicePixelRatio
+        };
+    }
+    adjustCoordinates(x, y) {
+        const ratio = this.devicePixelRatio;
+        return {
+            x: Math.round(x * ratio),
+            y: Math.round(y * ratio)
+        };
+    }
+    reverseAdjustCoordinates(x, y) {
+        const ratio = this.devicePixelRatio;
+        return {
+            x: Math.round(x / ratio),
+            y: Math.round(y / ratio)
+        };
+    }
+    async screenshotBase64() {
+        debugPage('screenshotBase64 begin');
+        const { width, height } = await this.size();
+        const adb = await this.getAdb();
+        let screenshotBuffer;
+        const androidScreenshotPath = `/data/local/tmp/midscene_screenshot_${randomUUID()}.png`;
+        try {
+            debugPage('Taking screenshot via adb.takeScreenshot');
+            screenshotBuffer = await adb.takeScreenshot(null);
+            debugPage('adb.takeScreenshot completed');
+            if (!screenshotBuffer) throw new Error('Failed to capture screenshot: screenshotBuffer is null');
+            if (!isValidPNGImageBuffer(screenshotBuffer)) {
+                debugPage('Invalid image buffer detected: not a valid image format');
+                throw new Error('Screenshot buffer has invalid format: could not find valid image signature');
+            }
+        } catch (error) {
+            const screenshotPath = getTmpFile('png');
+            try {
+                debugPage('Fallback: taking screenshot via shell screencap');
+                try {
+                    await adb.shell(`screencap -p ${androidScreenshotPath}`);
+                    debugPage('adb.shell screencap completed');
+                } catch (error) {
+                    debugPage('screencap failed, using forceScreenshot');
+                    await this.forceScreenshot(androidScreenshotPath);
+                    debugPage('forceScreenshot completed');
+                }
+                debugPage('Pulling screenshot file from device');
+                await adb.pull(androidScreenshotPath, screenshotPath);
+                debugPage('adb.pull completed');
+                screenshotBuffer = await node_fs.promises.readFile(screenshotPath);
+            } finally{
+                await adb.shell(`rm -f ${androidScreenshotPath}`);
+            }
+        }
+        debugPage('Resizing screenshot image');
+        const resizedScreenshotBuffer = await resizeImg(screenshotBuffer, {
+            width,
+            height
+        });
+        debugPage('Image resize completed');
+        debugPage('Converting to base64');
+        const result = `data:image/jpeg;base64,${resizedScreenshotBuffer.toString('base64')}`;
+        debugPage('screenshotBase64 end');
+        return result;
+    }
+    get mouse() {
+        return {
+            click: (x, y)=>this.mouseClick(x, y),
+            wheel: (deltaX, deltaY)=>this.mouseWheel(deltaX, deltaY),
+            move: (x, y)=>this.mouseMove(x, y),
+            drag: (from, to)=>this.mouseDrag(from, to)
+        };
+    }
+    get keyboard() {
+        return {
+            type: (text, options)=>this.keyboardType(text, options),
+            press: (action)=>this.keyboardPressAction(action)
+        };
+    }
+    async clearInput(element) {
+        if (!element) return;
+        await this.ensureYadb();
+        const adb = await this.getAdb();
+        await this.mouse.click(element.center[0], element.center[1]);
+        await adb.shell('app_process -Djava.class.path=/data/local/tmp/yadb /data/local/tmp com.ysbing.yadb.Main -keyboard "~CLEAR~"');
+        if (await adb.isSoftKeyboardPresent()) return;
+        await this.mouse.click(element.center[0], element.center[1]);
+    }
+    async forceScreenshot(path) {
+        await this.ensureYadb();
+        const adb = await this.getAdb();
+        await adb.shell(`app_process -Djava.class.path=/data/local/tmp/yadb /data/local/tmp com.ysbing.yadb.Main -screenshot ${path}`);
+    }
+    async url() {
+        return '';
+    }
+    async scrollUntilTop(startPoint) {
+        if (startPoint) {
+            const start = {
+                x: startPoint.left,
+                y: startPoint.top
+            };
+            const end = {
+                x: start.x,
+                y: 0
+            };
+            await this.mouseDrag(start, end);
+            return;
+        }
+        await repeat(defaultScrollUntilTimes, ()=>this.mouseWheel(0, 9999999, defaultFastScrollDuration));
+        await sleep(1000);
+    }
+    async scrollUntilBottom(startPoint) {
+        if (startPoint) {
+            const { height } = await this.size();
+            const start = {
+                x: startPoint.left,
+                y: startPoint.top
+            };
+            const end = {
+                x: start.x,
+                y: height
+            };
+            await this.mouseDrag(start, end);
+            return;
+        }
+        await repeat(defaultScrollUntilTimes, ()=>this.mouseWheel(0, -9999999, defaultFastScrollDuration));
+        await sleep(1000);
+    }
+    async scrollUntilLeft(startPoint) {
+        if (startPoint) {
+            const start = {
+                x: startPoint.left,
+                y: startPoint.top
+            };
+            const end = {
+                x: 0,
+                y: start.y
+            };
+            await this.mouseDrag(start, end);
+            return;
+        }
+        await repeat(defaultScrollUntilTimes, ()=>this.mouseWheel(9999999, 0, defaultFastScrollDuration));
+        await sleep(1000);
+    }
+    async scrollUntilRight(startPoint) {
+        if (startPoint) {
+            const { width } = await this.size();
+            const start = {
+                x: startPoint.left,
+                y: startPoint.top
+            };
+            const end = {
+                x: width,
+                y: start.y
+            };
+            await this.mouseDrag(start, end);
+            return;
+        }
+        await repeat(defaultScrollUntilTimes, ()=>this.mouseWheel(-9999999, 0, defaultFastScrollDuration));
+        await sleep(1000);
+    }
+    async scrollUp(distance, startPoint) {
+        const { height } = await this.size();
+        const scrollDistance = distance || height;
+        if (startPoint) {
+            const start = {
+                x: startPoint.left,
+                y: startPoint.top
+            };
+            const endY = Math.max(0, start.y - scrollDistance);
+            const end = {
+                x: start.x,
+                y: endY
+            };
+            await this.mouseDrag(start, end);
+            return;
+        }
+        await this.mouseWheel(0, scrollDistance);
+    }
+    async scrollDown(distance, startPoint) {
+        const { height } = await this.size();
+        const scrollDistance = distance || height;
+        if (startPoint) {
+            const start = {
+                x: startPoint.left,
+                y: startPoint.top
+            };
+            const endY = Math.min(height, start.y + scrollDistance);
+            const end = {
+                x: start.x,
+                y: endY
+            };
+            await this.mouseDrag(start, end);
+            return;
+        }
+        await this.mouseWheel(0, -scrollDistance);
+    }
+    async scrollLeft(distance, startPoint) {
+        const { width } = await this.size();
+        const scrollDistance = distance || width;
+        if (startPoint) {
+            const start = {
+                x: startPoint.left,
+                y: startPoint.top
+            };
+            const endX = Math.max(0, start.x - scrollDistance);
+            const end = {
+                x: endX,
+                y: start.y
+            };
+            await this.mouseDrag(start, end);
+            return;
+        }
+        await this.mouseWheel(scrollDistance, 0);
+    }
+    async scrollRight(distance, startPoint) {
+        const { width } = await this.size();
+        const scrollDistance = distance || width;
+        if (startPoint) {
+            const start = {
+                x: startPoint.left,
+                y: startPoint.top
+            };
+            const endX = Math.min(width, start.x + scrollDistance);
+            const end = {
+                x: endX,
+                y: start.y
+            };
+            await this.mouseDrag(start, end);
+            return;
+        }
+        await this.mouseWheel(-scrollDistance, 0);
+    }
+    async ensureYadb() {
+        if (!this.yadbPushed) {
+            const adb = await this.getAdb();
+            const androidPkgJson = require.resolve('@midscene/android/package.json');
+            const yadbBin = node_path.join(node_path.dirname(androidPkgJson), 'bin', 'yadb');
+            await adb.push(yadbBin, '/data/local/tmp');
+            this.yadbPushed = true;
+        }
+    }
+    async keyboardType(text, options) {
+        var _this_options, _this_options1;
+        if (!text) return;
+        const adb = await this.getAdb();
+        const isChinese = /[\p{Script=Han}\p{sc=Hani}]/u.test(text);
+        const IME_STRATEGY = ((null == (_this_options = this.options) ? void 0 : _this_options.imeStrategy) || getAIConfig(MIDSCENE_ANDROID_IME_STRATEGY)) ?? 'always-yadb';
+        const isAutoDismissKeyboard = (null == options ? void 0 : options.autoDismissKeyboard) ?? (null == (_this_options1 = this.options) ? void 0 : _this_options1.autoDismissKeyboard) ?? true;
+        if ('always-yadb' === IME_STRATEGY || 'yadb-for-non-ascii' === IME_STRATEGY && isChinese) await this.execYadb(text);
+        else await adb.inputText(text);
+        if (true === isAutoDismissKeyboard) await this.hideKeyboard(options);
+    }
+    async keyboardPress(key) {
+        const keyCodeMap = {
+            Enter: 66,
+            Backspace: 67,
+            Tab: 61,
+            ArrowUp: 19,
+            ArrowDown: 20,
+            ArrowLeft: 21,
+            ArrowRight: 22,
+            Escape: 111,
+            Home: 3,
+            End: 123
+        };
+        const adb = await this.getAdb();
+        const keyCode = keyCodeMap[key];
+        if (void 0 !== keyCode) await adb.keyevent(keyCode);
+        else if (1 === key.length) {
+            const asciiCode = key.toUpperCase().charCodeAt(0);
+            if (asciiCode >= 65 && asciiCode <= 90) await adb.keyevent(asciiCode - 36);
+        }
+    }
+    async keyboardPressAction(action) {
+        if (Array.isArray(action)) for (const act of action)await this.keyboardPress(act.key);
+        else await this.keyboardPress(action.key);
+    }
+    async mouseClick(x, y) {
+        const adb = await this.getAdb();
+        const { x: adjustedX, y: adjustedY } = this.adjustCoordinates(x, y);
+        await adb.shell(`input swipe ${adjustedX} ${adjustedY} ${adjustedX} ${adjustedY} 150`);
+    }
+    async mouseMove(x, y) {
+        return Promise.resolve();
+    }
+    async mouseDrag(from, to) {
+        const adb = await this.getAdb();
+        const { x: fromX, y: fromY } = this.adjustCoordinates(from.x, from.y);
+        const { x: toX, y: toY } = this.adjustCoordinates(to.x, to.y);
+        await adb.shell(`input swipe ${fromX} ${fromY} ${toX} ${toY} 300`);
+    }
+    async mouseWheel(deltaX, deltaY, duration = defaultNormalScrollDuration) {
+        const { width, height } = await this.size();
+        const n = 4;
+        const startX = deltaX < 0 ? width / n * (n - 1) : width / n;
+        const startY = deltaY < 0 ? height / n * (n - 1) : height / n;
+        const maxNegativeDeltaX = startX;
+        const maxPositiveDeltaX = width / n * (n - 1);
+        const maxNegativeDeltaY = startY;
+        const maxPositiveDeltaY = height / n * (n - 1);
+        deltaX = Math.max(-maxNegativeDeltaX, Math.min(deltaX, maxPositiveDeltaX));
+        deltaY = Math.max(-maxNegativeDeltaY, Math.min(deltaY, maxPositiveDeltaY));
+        const endX = startX + deltaX;
+        const endY = startY + deltaY;
+        const { x: adjustedStartX, y: adjustedStartY } = this.adjustCoordinates(startX, startY);
+        const { x: adjustedEndX, y: adjustedEndY } = this.adjustCoordinates(endX, endY);
+        const adb = await this.getAdb();
+        await adb.shell(`input swipe ${adjustedStartX} ${adjustedStartY} ${adjustedEndX} ${adjustedEndY} ${duration}`);
+    }
+    async destroy() {
+        if (this.destroyed) return;
+        this.destroyed = true;
+        try {
+            if (this.adb) this.adb = null;
+        } catch (error) {
+            console.error('Error during cleanup:', error);
+        }
+        this.connectingAdb = null;
+        this.yadbPushed = false;
+    }
+    async back() {
+        const adb = await this.getAdb();
+        await adb.shell('input keyevent 4');
+    }
+    async home() {
+        const adb = await this.getAdb();
+        await adb.shell('input keyevent 3');
+    }
+    async recentApps() {
+        const adb = await this.getAdb();
+        await adb.shell('input keyevent 187');
+    }
+    async longPress(x, y, duration = 1000) {
+        const adb = await this.getAdb();
+        const { x: adjustedX, y: adjustedY } = this.adjustCoordinates(x, y);
+        await adb.shell(`input swipe ${adjustedX} ${adjustedY} ${adjustedX} ${adjustedY} ${duration}`);
+    }
+    async pullDown(startPoint, distance, duration = 800) {
+        const { width, height } = await this.size();
+        const start = startPoint ? {
+            x: startPoint.left,
+            y: startPoint.top
+        } : {
+            x: width / 2,
+            y: 0.15 * height
+        };
+        const pullDistance = distance || 0.5 * height;
+        const end = {
+            x: start.x,
+            y: start.y + pullDistance
+        };
+        await this.pullDrag(start, end, duration);
+        await sleep(200);
+    }
+    async pullDrag(from, to, duration) {
+        const adb = await this.getAdb();
+        const { x: fromX, y: fromY } = this.adjustCoordinates(from.x, from.y);
+        const { x: toX, y: toY } = this.adjustCoordinates(to.x, to.y);
+        await adb.shell(`input swipe ${fromX} ${fromY} ${toX} ${toY} ${duration}`);
+    }
+    async pullUp(startPoint, distance, duration = 600) {
+        const { width, height } = await this.size();
+        const start = startPoint ? {
+            x: startPoint.left,
+            y: startPoint.top
+        } : {
+            x: width / 2,
+            y: 0.85 * height
+        };
+        const pullDistance = distance || 0.4 * height;
+        const end = {
+            x: start.x,
+            y: start.y - pullDistance
+        };
+        await this.pullDrag(start, end, duration);
+        await sleep(100);
+    }
+    async getXpathsById(id) {
+        throw new Error('Not implemented');
+    }
+    async getXpathsByPoint(point, isOrderSensitive) {
+        throw new Error('Not implemented');
+    }
+    async getElementInfoByXpath(xpath) {
+        throw new Error('Not implemented');
+    }
+    async hideKeyboard(options, timeoutMs = 1000) {
+        var _this_options;
+        const adb = await this.getAdb();
+        const keyboardDismissStrategy = (null == options ? void 0 : options.keyboardDismissStrategy) ?? (null == (_this_options = this.options) ? void 0 : _this_options.keyboardDismissStrategy) ?? 'esc-first';
+        const keyboardStatus = await adb.isSoftKeyboardPresent();
+        const isKeyboardShown = 'boolean' == typeof keyboardStatus ? keyboardStatus : null == keyboardStatus ? void 0 : keyboardStatus.isKeyboardShown;
+        if (!isKeyboardShown) {
+            debugPage('Keyboard has no UI; no closing necessary');
+            return false;
+        }
+        const keyCodes = 'back-first' === keyboardDismissStrategy ? [
+            4,
+            111
+        ] : [
+            111,
+            4
+        ];
+        for (const keyCode of keyCodes){
+            await adb.keyevent(keyCode);
+            const startTime = Date.now();
+            const intervalMs = 100;
+            while(Date.now() - startTime < timeoutMs){
+                await sleep(intervalMs);
+                const currentStatus = await adb.isSoftKeyboardPresent();
+                const isStillShown = 'boolean' == typeof currentStatus ? currentStatus : null == currentStatus ? void 0 : currentStatus.isKeyboardShown;
+                if (!isStillShown) {
+                    debugPage(`Keyboard hidden successfully with keycode ${keyCode}`);
+                    return true;
+                }
+            }
+            debugPage(`Keyboard still shown after keycode ${keyCode}, trying next key`);
+        }
+        console.warn('Warning: Failed to hide the software keyboard after trying both ESC and BACK keys');
+        return false;
+    }
+    constructor(deviceId, options){
+        _define_property(this, "deviceId", void 0);
+        _define_property(this, "yadbPushed", false);
+        _define_property(this, "devicePixelRatio", 1);
+        _define_property(this, "adb", null);
+        _define_property(this, "connectingAdb", null);
+        _define_property(this, "destroyed", false);
+        _define_property(this, "pageType", 'android');
+        _define_property(this, "uri", void 0);
+        _define_property(this, "options", void 0);
+        node_assert(deviceId, 'deviceId is required for AndroidDevice');
+        this.deviceId = deviceId;
+        this.options = options;
+    }
+}
+async function getConnectedDevices() {
+    try {
+        const adb = await ADB.createADB({
+            adbExecTimeout: 60000
+        });
+        const devices = await adb.getConnectedDevices();
+        debugPage(`Found ${devices.length} connected devices: `, devices);
+        return devices;
+    } catch (error) {
+        console.error('Failed to get device list:', error);
+        throw new Error(`Unable to get connected Android device list, please check https://midscenejs.com/integrate-with-android.html#faq : ${error.message}`, {
+            cause: error
+        });
+    }
+}
+class AndroidAgent extends PageAgent {
+    async launch(uri) {
+        const device = this.page;
+        await device.launch(uri);
+    }
+    constructor(page, opts){
+        super(page, opts);
+        if (!vlLocateMode()) throw new Error('Android Agent only supports vl-model. https://midscenejs.com/choose-a-model.html');
+    }
+}
+async function agentFromAdbDevice(deviceId, opts) {
+    if (!deviceId) {
+        const devices = await getConnectedDevices();
+        deviceId = devices[0].udid;
+        debugPage('deviceId not specified, will use the first device (id = %s)', deviceId);
+    }
+    const page = new AndroidDevice(deviceId, {
+        autoDismissKeyboard: null == opts ? void 0 : opts.autoDismissKeyboard,
+        androidAdbPath: null == opts ? void 0 : opts.androidAdbPath,
+        remoteAdbHost: null == opts ? void 0 : opts.remoteAdbHost,
+        remoteAdbPort: null == opts ? void 0 : opts.remoteAdbPort,
+        imeStrategy: null == opts ? void 0 : opts.imeStrategy
+    });
+    await page.connect();
+    return new AndroidAgent(page, opts);
+}
+export { AndroidAgent, AndroidDevice, agentFromAdbDevice, getConnectedDevices, overrideAIConfig };