@midscene/android 0.30.10 → 0.30.11-beta-20251218071621.0

package/dist/es/index.mjs

@@ -55,14 +55,13 @@ class AndroidDevice {
                     locate: getMidsceneLocationSchema().describe('The input field to be filled').optional()
                 }),
                 call: async (param)=>{
-                    var _this_options;
                     const element = param.locate;
                     if (element) {
                         if ('append' !== param.mode) await this.clearInput(element);
                     }
                     if ('clear' === param.mode) return;
                     if (!param || !param.value) return;
-                    const autoDismissKeyboard = param.autoDismissKeyboard ?? (null == (_this_options = this.options) ? void 0 : _this_options.autoDismissKeyboard);
+                    const autoDismissKeyboard = param.autoDismissKeyboard ?? this.options?.autoDismissKeyboard;
                     await this.keyboardType(param.value, {
                         autoDismissKeyboard
                     });
@@ -74,18 +73,18 @@ class AndroidDevice {
                     left: element.center[0],
                     top: element.center[1]
                 } : void 0;
-                const scrollToEventName = null == param ? void 0 : param.scrollType;
-                if ('untilTop' === scrollToEventName) await this.scrollUntilTop(startingPoint);
-                else if ('untilBottom' === scrollToEventName) await this.scrollUntilBottom(startingPoint);
-                else if ('untilRight' === scrollToEventName) await this.scrollUntilRight(startingPoint);
-                else if ('untilLeft' === scrollToEventName) await this.scrollUntilLeft(startingPoint);
-                else if ('once' !== scrollToEventName && scrollToEventName) throw new Error(`Unknown scroll event type: ${scrollToEventName}, param: ${JSON.stringify(param)}`);
+                const scrollToEventName = param?.scrollType;
+                if ('scrollToTop' === scrollToEventName) await this.scrollUntilTop(startingPoint);
+                else if ('scrollToBottom' === scrollToEventName) await this.scrollUntilBottom(startingPoint);
+                else if ('scrollToRight' === scrollToEventName) await this.scrollUntilRight(startingPoint);
+                else if ('scrollToLeft' === scrollToEventName) await this.scrollUntilLeft(startingPoint);
+                else if ('singleAction' !== scrollToEventName && scrollToEventName) throw new Error(`Unknown scroll event type: ${scrollToEventName}, param: ${JSON.stringify(param)}`);
                 else {
-                    if ((null == param ? void 0 : param.direction) !== 'down' && param && param.direction) if ('up' === param.direction) await this.scrollUp(param.distance || void 0, startingPoint);
+                    if (param?.direction !== 'down' && param && param.direction) if ('up' === param.direction) await this.scrollUp(param.distance || void 0, startingPoint);
                     else if ('left' === param.direction) await this.scrollLeft(param.distance || void 0, startingPoint);
                     else if ('right' === param.direction) await this.scrollRight(param.distance || void 0, startingPoint);
                     else throw new Error(`Unknown scroll direction: ${param.direction}`);
-                    else await this.scrollDown((null == param ? void 0 : param.distance) || void 0, startingPoint);
+                    else await this.scrollDown(param?.distance || void 0, startingPoint);
                     await sleep(500);
                 }
             }),
@@ -105,30 +104,6 @@ class AndroidDevice {
             defineActionKeyboardPress(async (param)=>{
                 await this.keyboardPress(param.keyName);
             }),
-            defineAction({
-                name: 'AndroidBackButton',
-                description: 'Trigger the system "back" operation on Android devices',
-                paramSchema: z.object({}),
-                call: async ()=>{
-                    await this.back();
-                }
-            }),
-            defineAction({
-                name: 'AndroidHomeButton',
-                description: 'Trigger the system "home" operation on Android devices',
-                paramSchema: z.object({}),
-                call: async ()=>{
-                    await this.home();
-                }
-            }),
-            defineAction({
-                name: 'AndroidRecentAppsButton',
-                description: 'Trigger the system "recent apps" operation on Android devices',
-                paramSchema: z.object({}),
-                call: async ()=>{
-                    await this.recentApps();
-                }
-            }),
             defineAction({
                 name: 'AndroidLongPress',
                 description: 'Trigger a long press on the screen at specified coordinates on Android devices',
@@ -140,7 +115,7 @@ class AndroidDevice {
                     const element = param.locate;
                     if (!element) throw new Error('AndroidLongPress requires an element to be located');
                     const [x, y] = element.center;
-                    await this.longPress(x, y, null == param ? void 0 : param.duration);
+                    await this.longPress(x, y, param?.duration);
                 }
             }),
             defineAction({
@@ -173,9 +148,11 @@ class AndroidDevice {
                 await this.clearInput(element);
             })
         ];
+        const platformSpecificActions = Object.values(createPlatformActions(this));
         const customActions = this.customActions || [];
         return [
             ...defaultActions,
+            ...platformSpecificActions,
             ...customActions
         ];
     }
@@ -193,10 +170,9 @@ class AndroidDevice {
             let error = null;
             debugDevice(`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) || globalConfigManager.getEnvConfigValue(MIDSCENE_ADB_PATH);
-                const remoteAdbHost = (null == (_this_options1 = this.options) ? void 0 : _this_options1.remoteAdbHost) || globalConfigManager.getEnvConfigValue(MIDSCENE_ADB_REMOTE_HOST);
-                const remoteAdbPort = (null == (_this_options2 = this.options) ? void 0 : _this_options2.remoteAdbPort) || globalConfigManager.getEnvConfigValue(MIDSCENE_ADB_REMOTE_PORT);
+                const androidAdbPath = this.options?.androidAdbPath || globalConfigManager.getEnvConfigValue(MIDSCENE_ADB_PATH);
+                const remoteAdbHost = this.options?.remoteAdbHost || globalConfigManager.getEnvConfigValue(MIDSCENE_ADB_REMOTE_HOST);
+                const remoteAdbPort = this.options?.remoteAdbPort || globalConfigManager.getEnvConfigValue(MIDSCENE_ADB_REMOTE_PORT);
                 this.adb = await new ADB({
                     udid: this.deviceId,
                     adbExecTimeout: 60000,
@@ -211,7 +187,7 @@ class AndroidDevice {
                 this.description = `
 DeviceId: ${this.deviceId}
 ScreenSize:
-${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[key]}${'override' === key && size[key] ? " \u2705" : ''}`).join('\n')}
+${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[key]}${'override' === key && size[key] ? ' ✅' : ''}`).join('\n')}
 `;
                 debugDevice('ADB initialized successfully', this.description);
                 return this.adb;
@@ -286,14 +262,12 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
         };
     }
     async getScreenSize() {
-        var _this_options, _this_options1;
-        const shouldCache = !((null == (_this_options = this.options) ? void 0 : _this_options.alwaysRefreshScreenInfo) ?? false);
+        const shouldCache = !(this.options?.alwaysRefreshScreenInfo ?? false);
         if (shouldCache && this.cachedScreenSize) return this.cachedScreenSize;
         const adb = await this.getAdb();
-        if ('number' == typeof (null == (_this_options1 = this.options) ? void 0 : _this_options1.displayId)) try {
-            var _this_options2;
+        if ('number' == typeof this.options?.displayId) try {
             const stdout = await adb.shell('dumpsys display');
-            if (null == (_this_options2 = this.options) ? void 0 : _this_options2.usePhysicalDisplayIdForDisplayLookup) {
+            if (this.options?.usePhysicalDisplayIdForDisplayLookup) {
                 const physicalDisplayId = await this.getPhysicalDisplayId();
                 if (physicalDisplayId) {
                     const lineRegex = new RegExp(`^.*uniqueId \"local:${physicalDisplayId}\".*$
@@ -312,7 +286,8 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
                             const result = {
                                 override: sizeStr,
                                 physical: sizeStr,
-                                orientation: rotation
+                                orientation: rotation,
+                                isCurrentOrientation: true
                             };
                             if (shouldCache) this.cachedScreenSize = result;
                             return result;
@@ -335,7 +310,8 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
                         const result = {
                             override: sizeStr,
                             physical: sizeStr,
-                            orientation: rotation
+                            orientation: rotation,
+                            isCurrentOrientation: true
                         };
                         if (shouldCache) this.cachedScreenSize = result;
                         return result;
@@ -368,7 +344,8 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
         if (size.override || size.physical) {
             const result = {
                 ...size,
-                orientation
+                orientation,
+                isCurrentOrientation: false
             };
             if (shouldCache) this.cachedScreenSize = result;
             return result;
@@ -383,12 +360,10 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
         this.devicePixelRatioInitialized = true;
     }
     async getDisplayDensity() {
-        var _this_options;
         const adb = await this.getAdb();
-        if ('number' == typeof (null == (_this_options = this.options) ? void 0 : _this_options.displayId)) try {
-            var _this_options1;
+        if ('number' == typeof this.options?.displayId) try {
             const stdout = await adb.shell('dumpsys display');
-            if (null == (_this_options1 = this.options) ? void 0 : _this_options1.usePhysicalDisplayIdForDisplayLookup) {
+            if (this.options?.usePhysicalDisplayIdForDisplayLookup) {
                 const physicalDisplayId = await this.getPhysicalDisplayId();
                 if (physicalDisplayId) {
                     const lineRegex = new RegExp(`^.*uniqueId \"local:${physicalDisplayId}\".*$
@@ -420,8 +395,7 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
         return density ?? 160;
     }
     async getDisplayOrientation() {
-        var _this_options;
-        const shouldCache = !((null == (_this_options = this.options) ? void 0 : _this_options.alwaysRefreshScreenInfo) ?? false);
+        const shouldCache = !(this.options?.alwaysRefreshScreenInfo ?? false);
         if (shouldCache && null !== this.cachedOrientation) return this.cachedOrientation;
         const adb = await this.getAdb();
         let orientation = 0;
@@ -448,15 +422,15 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
         return orientation;
     }
     async size() {
-        var _this_options;
         await this.initializeDevicePixelRatio();
         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 scale = (null == (_this_options = this.options) ? void 0 : _this_options.screenshotResizeScale) ?? 1 / this.devicePixelRatio;
+        const shouldSwap = true !== screenSize.isCurrentOrientation && isLandscape;
+        const width = Number.parseInt(match[shouldSwap ? 2 : 1], 10);
+        const height = Number.parseInt(match[shouldSwap ? 1 : 2], 10);
+        const scale = this.options?.screenshotResizeScale ?? 1 / this.devicePixelRatio;
         this.scalingRatio = scale;
         const logicalWidth = Math.round(width * scale);
         const logicalHeight = Math.round(height * scale);
@@ -497,17 +471,13 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
         };
     }
     async screenshotBase64() {
-        var _this_options;
         debugDevice('screenshotBase64 begin');
         const adb = await this.getAdb();
         let screenshotBuffer;
         const androidScreenshotPath = `/data/local/tmp/midscene_screenshot_${uuid()}.png`;
-        const useShellScreencap = 'number' == typeof (null == (_this_options = this.options) ? void 0 : _this_options.displayId);
+        const useShellScreencap = 'number' == typeof this.options?.displayId;
         try {
-            if (useShellScreencap) {
-                var _this_options1;
-                throw new Error(`Display ${null == (_this_options1 = this.options) ? void 0 : _this_options1.displayId} requires shell screencap`);
-            }
+            if (useShellScreencap) throw new Error(`Display ${this.options?.displayId} requires shell screencap`);
             debugDevice('Taking screenshot via adb.takeScreenshot');
             screenshotBuffer = await adb.takeScreenshot(null);
             debugDevice('adb.takeScreenshot completed');
@@ -520,9 +490,8 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
             debugDevice(`Taking screenshot via adb.takeScreenshot failed or was skipped: ${error}`);
             const screenshotPath = getTmpFile('png');
             try {
-                var _this_options2, _this_options3;
                 debugDevice('Fallback: taking screenshot via shell screencap');
-                const displayId = (null == (_this_options2 = this.options) ? void 0 : _this_options2.usePhysicalDisplayIdForScreenshot) ? await this.getPhysicalDisplayId() : null == (_this_options3 = this.options) ? void 0 : _this_options3.displayId;
+                const displayId = this.options?.usePhysicalDisplayIdForScreenshot ? await this.getPhysicalDisplayId() : this.options?.displayId;
                 const displayArg = displayId ? `-d ${displayId}` : '';
                 try {
                     await adb.shell(`screencap -p ${displayArg} ${androidScreenshotPath}`.trim());
@@ -546,12 +515,11 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
         return result;
     }
     async clearInput(element) {
-        var _this_options;
         if (!element) return;
         await this.ensureYadb();
         const adb = await this.getAdb();
         await this.mouseClick(element.center[0], element.center[1]);
-        const IME_STRATEGY = ((null == (_this_options = this.options) ? void 0 : _this_options.imeStrategy) || globalConfigManager.getEnvConfigValue(MIDSCENE_ANDROID_IME_STRATEGY)) ?? IME_STRATEGY_YADB_FOR_NON_ASCII;
+        const IME_STRATEGY = (this.options?.imeStrategy || globalConfigManager.getEnvConfigValue(MIDSCENE_ANDROID_IME_STRATEGY)) ?? IME_STRATEGY_YADB_FOR_NON_ASCII;
         if (IME_STRATEGY === IME_STRATEGY_YADB_FOR_NON_ASCII) await adb.clearTextField(100);
         else await adb.shell(`app_process${this.getDisplayArg()} -Djava.class.path=/data/local/tmp/yadb /data/local/tmp com.ysbing.yadb.Main -keyboard "~CLEAR~"`);
         if (await adb.isSoftKeyboardPresent()) return;
@@ -701,12 +669,11 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
         }
     }
     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) || globalConfigManager.getEnvConfigValue(MIDSCENE_ANDROID_IME_STRATEGY)) ?? IME_STRATEGY_YADB_FOR_NON_ASCII;
-        const shouldAutoDismissKeyboard = (null == options ? void 0 : options.autoDismissKeyboard) ?? (null == (_this_options1 = this.options) ? void 0 : _this_options1.autoDismissKeyboard) ?? true;
+        const IME_STRATEGY = (this.options?.imeStrategy || globalConfigManager.getEnvConfigValue(MIDSCENE_ANDROID_IME_STRATEGY)) ?? IME_STRATEGY_YADB_FOR_NON_ASCII;
+        const shouldAutoDismissKeyboard = options?.autoDismissKeyboard ?? this.options?.autoDismissKeyboard ?? true;
         if (IME_STRATEGY === IME_STRATEGY_ALWAYS_YADB || IME_STRATEGY === IME_STRATEGY_YADB_FOR_NON_ASCII && isChinese) await this.execYadb(text);
         else await adb.inputText(text);
         if (true === shouldAutoDismissKeyboard) await this.hideKeyboard(options);
@@ -820,7 +787,7 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
         const adb = await this.getAdb();
         await adb.shell(`input${this.getDisplayArg()} keyevent 187`);
     }
-    async longPress(x, y, duration = 1000) {
+    async longPress(x, y, duration = 2000) {
         const adb = await this.getAdb();
         const { x: adjustedX, y: adjustedY } = this.adjustCoordinates(x, y);
         await adb.shell(`input${this.getDisplayArg()} swipe ${adjustedX} ${adjustedY} ${adjustedX} ${adjustedY} ${duration}`);
@@ -866,18 +833,16 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
         await sleep(100);
     }
     getDisplayArg() {
-        var _this_options;
-        return 'number' == typeof (null == (_this_options = this.options) ? void 0 : _this_options.displayId) ? ` -d ${this.options.displayId}` : '';
+        return 'number' == typeof this.options?.displayId ? ` -d ${this.options.displayId}` : '';
     }
     async getPhysicalDisplayId() {
-        var _this_options;
-        if ('number' != typeof (null == (_this_options = this.options) ? void 0 : _this_options.displayId)) return null;
+        if ('number' != typeof this.options?.displayId) return null;
         const adb = await this.getAdb();
         try {
             const stdout = await adb.shell(`dumpsys SurfaceFlinger --display-id ${this.options.displayId}`);
             const regex = new RegExp(`Display (\\d+) \\(HWC display ${this.options.displayId}\\):`);
             const displayMatch = stdout.match(regex);
-            if (null == displayMatch ? void 0 : displayMatch[1]) {
+            if (displayMatch?.[1]) {
                 debugDevice(`Found physical display ID: ${displayMatch[1]} for display ID: ${this.options.displayId}`);
                 return displayMatch[1];
             }
@@ -889,11 +854,10 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
         }
     }
     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 keyboardDismissStrategy = options?.keyboardDismissStrategy ?? this.options?.keyboardDismissStrategy ?? 'esc-first';
         const keyboardStatus = await adb.isSoftKeyboardPresent();
-        const isKeyboardShown = 'boolean' == typeof keyboardStatus ? keyboardStatus : null == keyboardStatus ? void 0 : keyboardStatus.isKeyboardShown;
+        const isKeyboardShown = 'boolean' == typeof keyboardStatus ? keyboardStatus : keyboardStatus?.isKeyboardShown;
         if (!isKeyboardShown) {
             debugDevice('Keyboard has no UI; no closing necessary');
             return false;
@@ -912,7 +876,7 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
             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;
+                const isStillShown = 'boolean' == typeof currentStatus ? currentStatus : currentStatus?.isKeyboardShown;
                 if (!isStillShown) {
                     debugDevice(`Keyboard hidden successfully with keycode ${keyCode}`);
                     return true;
@@ -942,9 +906,53 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
         node_assert(deviceId, 'deviceId is required for AndroidDevice');
         this.deviceId = deviceId;
         this.options = options;
-        this.customActions = null == options ? void 0 : options.customActions;
+        this.customActions = options?.customActions;
     }
 }
+const runAdbShellParamSchema = z.string().describe('ADB shell command to execute');
+const launchParamSchema = z.string().describe('App package name or URL to launch');
+const createPlatformActions = (device)=>({
+        RunAdbShell: defineAction({
+            name: 'RunAdbShell',
+            description: 'Execute ADB shell command on Android device',
+            interfaceAlias: 'runAdbShell',
+            paramSchema: runAdbShellParamSchema,
+            call: async (param)=>{
+                const adb = await device.getAdb();
+                return await adb.shell(param);
+            }
+        }),
+        Launch: defineAction({
+            name: 'Launch',
+            description: 'Launch an Android app or URL',
+            interfaceAlias: 'launch',
+            paramSchema: launchParamSchema,
+            call: async (param)=>{
+                await device.launch(param);
+            }
+        }),
+        AndroidBackButton: defineAction({
+            name: 'AndroidBackButton',
+            description: 'Trigger the system "back" operation on Android devices',
+            call: async ()=>{
+                await device.back();
+            }
+        }),
+        AndroidHomeButton: defineAction({
+            name: 'AndroidHomeButton',
+            description: 'Trigger the system "home" operation on Android devices',
+            call: async ()=>{
+                await device.home();
+            }
+        }),
+        AndroidRecentAppsButton: defineAction({
+            name: 'AndroidRecentAppsButton',
+            description: 'Trigger the system "recent apps" operation on Android devices',
+            call: async ()=>{
+                await device.recentApps();
+            }
+        })
+    });
 const debugUtils = getDebug('android:utils');
 async function getConnectedDevices() {
     try {
@@ -961,35 +969,39 @@ async function getConnectedDevices() {
         });
     }
 }
+function agent_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 debugAgent = getDebug('android:agent');
 class AndroidAgent extends Agent {
-    async launch(uri) {
-        const device = this.page;
-        await device.launch(uri);
-    }
-    async runAdbShell(command) {
-        const adb = await this.page.getAdb();
-        return await adb.shell(command);
+    createActionWrapper(name) {
+        const action = this.wrapActionInActionSpace(name);
+        return (...args)=>action(args[0]);
+    }
+    constructor(device, opts){
+        super(device, opts), agent_define_property(this, "launch", void 0), agent_define_property(this, "runAdbShell", void 0), agent_define_property(this, "back", void 0), agent_define_property(this, "home", void 0), agent_define_property(this, "recentApps", void 0);
+        this.launch = this.createActionWrapper('Launch');
+        this.runAdbShell = this.createActionWrapper('RunAdbShell');
+        this.back = this.createActionWrapper('AndroidBackButton');
+        this.home = this.createActionWrapper('AndroidHomeButton');
+        this.recentApps = this.createActionWrapper('AndroidRecentAppsButton');
     }
 }
 async function agentFromAdbDevice(deviceId, opts) {
     if (!deviceId) {
         const devices = await getConnectedDevices();
+        if (0 === devices.length) throw new Error('No Android devices found. Please connect an Android device and ensure ADB is properly configured. Run `adb devices` to verify device connection.');
         deviceId = devices[0].udid;
         debugAgent('deviceId not specified, will use the first device (id = %s)', deviceId);
     }
-    const device = 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,
-        displayId: null == opts ? void 0 : opts.displayId,
-        usePhysicalDisplayIdForScreenshot: null == opts ? void 0 : opts.usePhysicalDisplayIdForScreenshot,
-        usePhysicalDisplayIdForDisplayLookup: null == opts ? void 0 : opts.usePhysicalDisplayIdForDisplayLookup,
-        screenshotResizeScale: null == opts ? void 0 : opts.screenshotResizeScale,
-        alwaysRefreshScreenInfo: null == opts ? void 0 : opts.alwaysRefreshScreenInfo
-    });
+    const device = new AndroidDevice(deviceId, opts || {});
     await device.connect();
     return new AndroidAgent(device, opts);
 }

package/dist/lib/index.js

@@ -37,10 +37,10 @@ var __webpack_exports__ = {};
 __webpack_require__.r(__webpack_exports__);
 __webpack_require__.d(__webpack_exports__, {
     getConnectedDevices: ()=>getConnectedDevices,
-    agentFromAdbDevice: ()=>agentFromAdbDevice,
-    AndroidDevice: ()=>AndroidDevice,
     overrideAIConfig: ()=>env_namespaceObject.overrideAIConfig,
-    AndroidAgent: ()=>AndroidAgent
+    AndroidAgent: ()=>AndroidAgent,
+    agentFromAdbDevice: ()=>agentFromAdbDevice,
+    AndroidDevice: ()=>AndroidDevice
 });
 const external_node_assert_namespaceObject = require("node:assert");
 var external_node_assert_default = /*#__PURE__*/ __webpack_require__.n(external_node_assert_namespaceObject);
@@ -101,14 +101,13 @@ class AndroidDevice {
                     locate: (0, core_namespaceObject.getMidsceneLocationSchema)().describe('The input field to be filled').optional()
                 }),
                 call: async (param)=>{
-                    var _this_options;
                     const element = param.locate;
                     if (element) {
                         if ('append' !== param.mode) await this.clearInput(element);
                     }
                     if ('clear' === param.mode) return;
                     if (!param || !param.value) return;
-                    const autoDismissKeyboard = param.autoDismissKeyboard ?? (null == (_this_options = this.options) ? void 0 : _this_options.autoDismissKeyboard);
+                    const autoDismissKeyboard = param.autoDismissKeyboard ?? this.options?.autoDismissKeyboard;
                     await this.keyboardType(param.value, {
                         autoDismissKeyboard
                     });
@@ -120,18 +119,18 @@ class AndroidDevice {
                     left: element.center[0],
                     top: element.center[1]
                 } : void 0;
-                const scrollToEventName = null == param ? void 0 : param.scrollType;
-                if ('untilTop' === scrollToEventName) await this.scrollUntilTop(startingPoint);
-                else if ('untilBottom' === scrollToEventName) await this.scrollUntilBottom(startingPoint);
-                else if ('untilRight' === scrollToEventName) await this.scrollUntilRight(startingPoint);
-                else if ('untilLeft' === scrollToEventName) await this.scrollUntilLeft(startingPoint);
-                else if ('once' !== scrollToEventName && scrollToEventName) throw new Error(`Unknown scroll event type: ${scrollToEventName}, param: ${JSON.stringify(param)}`);
+                const scrollToEventName = param?.scrollType;
+                if ('scrollToTop' === scrollToEventName) await this.scrollUntilTop(startingPoint);
+                else if ('scrollToBottom' === scrollToEventName) await this.scrollUntilBottom(startingPoint);
+                else if ('scrollToRight' === scrollToEventName) await this.scrollUntilRight(startingPoint);
+                else if ('scrollToLeft' === scrollToEventName) await this.scrollUntilLeft(startingPoint);
+                else if ('singleAction' !== scrollToEventName && scrollToEventName) throw new Error(`Unknown scroll event type: ${scrollToEventName}, param: ${JSON.stringify(param)}`);
                 else {
-                    if ((null == param ? void 0 : param.direction) !== 'down' && param && param.direction) if ('up' === param.direction) await this.scrollUp(param.distance || void 0, startingPoint);
+                    if (param?.direction !== 'down' && param && param.direction) if ('up' === param.direction) await this.scrollUp(param.distance || void 0, startingPoint);
                     else if ('left' === param.direction) await this.scrollLeft(param.distance || void 0, startingPoint);
                     else if ('right' === param.direction) await this.scrollRight(param.distance || void 0, startingPoint);
                     else throw new Error(`Unknown scroll direction: ${param.direction}`);
-                    else await this.scrollDown((null == param ? void 0 : param.distance) || void 0, startingPoint);
+                    else await this.scrollDown(param?.distance || void 0, startingPoint);
                     await (0, utils_namespaceObject.sleep)(500);
                 }
             }),
@@ -151,30 +150,6 @@ class AndroidDevice {
             (0, device_namespaceObject.defineActionKeyboardPress)(async (param)=>{
                 await this.keyboardPress(param.keyName);
             }),
-            (0, device_namespaceObject.defineAction)({
-                name: 'AndroidBackButton',
-                description: 'Trigger the system "back" operation on Android devices',
-                paramSchema: core_namespaceObject.z.object({}),
-                call: async ()=>{
-                    await this.back();
-                }
-            }),
-            (0, device_namespaceObject.defineAction)({
-                name: 'AndroidHomeButton',
-                description: 'Trigger the system "home" operation on Android devices',
-                paramSchema: core_namespaceObject.z.object({}),
-                call: async ()=>{
-                    await this.home();
-                }
-            }),
-            (0, device_namespaceObject.defineAction)({
-                name: 'AndroidRecentAppsButton',
-                description: 'Trigger the system "recent apps" operation on Android devices',
-                paramSchema: core_namespaceObject.z.object({}),
-                call: async ()=>{
-                    await this.recentApps();
-                }
-            }),
             (0, device_namespaceObject.defineAction)({
                 name: 'AndroidLongPress',
                 description: 'Trigger a long press on the screen at specified coordinates on Android devices',
@@ -186,7 +161,7 @@ class AndroidDevice {
                     const element = param.locate;
                     if (!element) throw new Error('AndroidLongPress requires an element to be located');
                     const [x, y] = element.center;
-                    await this.longPress(x, y, null == param ? void 0 : param.duration);
+                    await this.longPress(x, y, param?.duration);
                 }
             }),
             (0, device_namespaceObject.defineAction)({
@@ -219,9 +194,11 @@ class AndroidDevice {
                 await this.clearInput(element);
             })
         ];
+        const platformSpecificActions = Object.values(createPlatformActions(this));
         const customActions = this.customActions || [];
         return [
             ...defaultActions,
+            ...platformSpecificActions,
             ...customActions
         ];
     }
@@ -239,10 +216,9 @@ class AndroidDevice {
             let error = null;
             debugDevice(`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) || env_namespaceObject.globalConfigManager.getEnvConfigValue(env_namespaceObject.MIDSCENE_ADB_PATH);
-                const remoteAdbHost = (null == (_this_options1 = this.options) ? void 0 : _this_options1.remoteAdbHost) || env_namespaceObject.globalConfigManager.getEnvConfigValue(env_namespaceObject.MIDSCENE_ADB_REMOTE_HOST);
-                const remoteAdbPort = (null == (_this_options2 = this.options) ? void 0 : _this_options2.remoteAdbPort) || env_namespaceObject.globalConfigManager.getEnvConfigValue(env_namespaceObject.MIDSCENE_ADB_REMOTE_PORT);
+                const androidAdbPath = this.options?.androidAdbPath || env_namespaceObject.globalConfigManager.getEnvConfigValue(env_namespaceObject.MIDSCENE_ADB_PATH);
+                const remoteAdbHost = this.options?.remoteAdbHost || env_namespaceObject.globalConfigManager.getEnvConfigValue(env_namespaceObject.MIDSCENE_ADB_REMOTE_HOST);
+                const remoteAdbPort = this.options?.remoteAdbPort || env_namespaceObject.globalConfigManager.getEnvConfigValue(env_namespaceObject.MIDSCENE_ADB_REMOTE_PORT);
                 this.adb = await new external_appium_adb_namespaceObject.ADB({
                     udid: this.deviceId,
                     adbExecTimeout: 60000,
@@ -257,7 +233,7 @@ class AndroidDevice {
                 this.description = `
 DeviceId: ${this.deviceId}
 ScreenSize:
-${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[key]}${'override' === key && size[key] ? " \u2705" : ''}`).join('\n')}
+${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[key]}${'override' === key && size[key] ? ' ✅' : ''}`).join('\n')}
 `;
                 debugDevice('ADB initialized successfully', this.description);
                 return this.adb;
@@ -332,14 +308,12 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
         };
     }
     async getScreenSize() {
-        var _this_options, _this_options1;
-        const shouldCache = !((null == (_this_options = this.options) ? void 0 : _this_options.alwaysRefreshScreenInfo) ?? false);
+        const shouldCache = !(this.options?.alwaysRefreshScreenInfo ?? false);
         if (shouldCache && this.cachedScreenSize) return this.cachedScreenSize;
         const adb = await this.getAdb();
-        if ('number' == typeof (null == (_this_options1 = this.options) ? void 0 : _this_options1.displayId)) try {
-            var _this_options2;
+        if ('number' == typeof this.options?.displayId) try {
             const stdout = await adb.shell('dumpsys display');
-            if (null == (_this_options2 = this.options) ? void 0 : _this_options2.usePhysicalDisplayIdForDisplayLookup) {
+            if (this.options?.usePhysicalDisplayIdForDisplayLookup) {
                 const physicalDisplayId = await this.getPhysicalDisplayId();
                 if (physicalDisplayId) {
                     const lineRegex = new RegExp(`^.*uniqueId \"local:${physicalDisplayId}\".*$
@@ -358,7 +332,8 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
                             const result = {
                                 override: sizeStr,
                                 physical: sizeStr,
-                                orientation: rotation
+                                orientation: rotation,
+                                isCurrentOrientation: true
                             };
                             if (shouldCache) this.cachedScreenSize = result;
                             return result;
@@ -381,7 +356,8 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
                         const result = {
                             override: sizeStr,
                             physical: sizeStr,
-                            orientation: rotation
+                            orientation: rotation,
+                            isCurrentOrientation: true
                         };
                         if (shouldCache) this.cachedScreenSize = result;
                         return result;
@@ -414,7 +390,8 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
         if (size.override || size.physical) {
             const result = {
                 ...size,
-                orientation
+                orientation,
+                isCurrentOrientation: false
             };
             if (shouldCache) this.cachedScreenSize = result;
             return result;
@@ -429,12 +406,10 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
         this.devicePixelRatioInitialized = true;
     }
     async getDisplayDensity() {
-        var _this_options;
         const adb = await this.getAdb();
-        if ('number' == typeof (null == (_this_options = this.options) ? void 0 : _this_options.displayId)) try {
-            var _this_options1;
+        if ('number' == typeof this.options?.displayId) try {
             const stdout = await adb.shell('dumpsys display');
-            if (null == (_this_options1 = this.options) ? void 0 : _this_options1.usePhysicalDisplayIdForDisplayLookup) {
+            if (this.options?.usePhysicalDisplayIdForDisplayLookup) {
                 const physicalDisplayId = await this.getPhysicalDisplayId();
                 if (physicalDisplayId) {
                     const lineRegex = new RegExp(`^.*uniqueId \"local:${physicalDisplayId}\".*$
@@ -466,8 +441,7 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
         return density ?? 160;
     }
     async getDisplayOrientation() {
-        var _this_options;
-        const shouldCache = !((null == (_this_options = this.options) ? void 0 : _this_options.alwaysRefreshScreenInfo) ?? false);
+        const shouldCache = !(this.options?.alwaysRefreshScreenInfo ?? false);
         if (shouldCache && null !== this.cachedOrientation) return this.cachedOrientation;
         const adb = await this.getAdb();
         let orientation = 0;
@@ -494,15 +468,15 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
         return orientation;
     }
     async size() {
-        var _this_options;
         await this.initializeDevicePixelRatio();
         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 scale = (null == (_this_options = this.options) ? void 0 : _this_options.screenshotResizeScale) ?? 1 / this.devicePixelRatio;
+        const shouldSwap = true !== screenSize.isCurrentOrientation && isLandscape;
+        const width = Number.parseInt(match[shouldSwap ? 2 : 1], 10);
+        const height = Number.parseInt(match[shouldSwap ? 1 : 2], 10);
+        const scale = this.options?.screenshotResizeScale ?? 1 / this.devicePixelRatio;
         this.scalingRatio = scale;
         const logicalWidth = Math.round(width * scale);
         const logicalHeight = Math.round(height * scale);
@@ -543,17 +517,13 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
         };
     }
     async screenshotBase64() {
-        var _this_options;
         debugDevice('screenshotBase64 begin');
         const adb = await this.getAdb();
         let screenshotBuffer;
         const androidScreenshotPath = `/data/local/tmp/midscene_screenshot_${(0, shared_utils_namespaceObject.uuid)()}.png`;
-        const useShellScreencap = 'number' == typeof (null == (_this_options = this.options) ? void 0 : _this_options.displayId);
+        const useShellScreencap = 'number' == typeof this.options?.displayId;
         try {
-            if (useShellScreencap) {
-                var _this_options1;
-                throw new Error(`Display ${null == (_this_options1 = this.options) ? void 0 : _this_options1.displayId} requires shell screencap`);
-            }
+            if (useShellScreencap) throw new Error(`Display ${this.options?.displayId} requires shell screencap`);
             debugDevice('Taking screenshot via adb.takeScreenshot');
             screenshotBuffer = await adb.takeScreenshot(null);
             debugDevice('adb.takeScreenshot completed');
@@ -566,9 +536,8 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
             debugDevice(`Taking screenshot via adb.takeScreenshot failed or was skipped: ${error}`);
             const screenshotPath = (0, utils_namespaceObject.getTmpFile)('png');
             try {
-                var _this_options2, _this_options3;
                 debugDevice('Fallback: taking screenshot via shell screencap');
-                const displayId = (null == (_this_options2 = this.options) ? void 0 : _this_options2.usePhysicalDisplayIdForScreenshot) ? await this.getPhysicalDisplayId() : null == (_this_options3 = this.options) ? void 0 : _this_options3.displayId;
+                const displayId = this.options?.usePhysicalDisplayIdForScreenshot ? await this.getPhysicalDisplayId() : this.options?.displayId;
                 const displayArg = displayId ? `-d ${displayId}` : '';
                 try {
                     await adb.shell(`screencap -p ${displayArg} ${androidScreenshotPath}`.trim());
@@ -592,12 +561,11 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
         return result;
     }
     async clearInput(element) {
-        var _this_options;
         if (!element) return;
         await this.ensureYadb();
         const adb = await this.getAdb();
         await this.mouseClick(element.center[0], element.center[1]);
-        const IME_STRATEGY = ((null == (_this_options = this.options) ? void 0 : _this_options.imeStrategy) || env_namespaceObject.globalConfigManager.getEnvConfigValue(env_namespaceObject.MIDSCENE_ANDROID_IME_STRATEGY)) ?? IME_STRATEGY_YADB_FOR_NON_ASCII;
+        const IME_STRATEGY = (this.options?.imeStrategy || env_namespaceObject.globalConfigManager.getEnvConfigValue(env_namespaceObject.MIDSCENE_ANDROID_IME_STRATEGY)) ?? IME_STRATEGY_YADB_FOR_NON_ASCII;
         if (IME_STRATEGY === IME_STRATEGY_YADB_FOR_NON_ASCII) await adb.clearTextField(100);
         else await adb.shell(`app_process${this.getDisplayArg()} -Djava.class.path=/data/local/tmp/yadb /data/local/tmp com.ysbing.yadb.Main -keyboard "~CLEAR~"`);
         if (await adb.isSoftKeyboardPresent()) return;
@@ -747,12 +715,11 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
         }
     }
     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) || env_namespaceObject.globalConfigManager.getEnvConfigValue(env_namespaceObject.MIDSCENE_ANDROID_IME_STRATEGY)) ?? IME_STRATEGY_YADB_FOR_NON_ASCII;
-        const shouldAutoDismissKeyboard = (null == options ? void 0 : options.autoDismissKeyboard) ?? (null == (_this_options1 = this.options) ? void 0 : _this_options1.autoDismissKeyboard) ?? true;
+        const IME_STRATEGY = (this.options?.imeStrategy || env_namespaceObject.globalConfigManager.getEnvConfigValue(env_namespaceObject.MIDSCENE_ANDROID_IME_STRATEGY)) ?? IME_STRATEGY_YADB_FOR_NON_ASCII;
+        const shouldAutoDismissKeyboard = options?.autoDismissKeyboard ?? this.options?.autoDismissKeyboard ?? true;
         if (IME_STRATEGY === IME_STRATEGY_ALWAYS_YADB || IME_STRATEGY === IME_STRATEGY_YADB_FOR_NON_ASCII && isChinese) await this.execYadb(text);
         else await adb.inputText(text);
         if (true === shouldAutoDismissKeyboard) await this.hideKeyboard(options);
@@ -866,7 +833,7 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
         const adb = await this.getAdb();
         await adb.shell(`input${this.getDisplayArg()} keyevent 187`);
     }
-    async longPress(x, y, duration = 1000) {
+    async longPress(x, y, duration = 2000) {
         const adb = await this.getAdb();
         const { x: adjustedX, y: adjustedY } = this.adjustCoordinates(x, y);
         await adb.shell(`input${this.getDisplayArg()} swipe ${adjustedX} ${adjustedY} ${adjustedX} ${adjustedY} ${duration}`);
@@ -912,18 +879,16 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
         await (0, utils_namespaceObject.sleep)(100);
     }
     getDisplayArg() {
-        var _this_options;
-        return 'number' == typeof (null == (_this_options = this.options) ? void 0 : _this_options.displayId) ? ` -d ${this.options.displayId}` : '';
+        return 'number' == typeof this.options?.displayId ? ` -d ${this.options.displayId}` : '';
     }
     async getPhysicalDisplayId() {
-        var _this_options;
-        if ('number' != typeof (null == (_this_options = this.options) ? void 0 : _this_options.displayId)) return null;
+        if ('number' != typeof this.options?.displayId) return null;
         const adb = await this.getAdb();
         try {
             const stdout = await adb.shell(`dumpsys SurfaceFlinger --display-id ${this.options.displayId}`);
             const regex = new RegExp(`Display (\\d+) \\(HWC display ${this.options.displayId}\\):`);
             const displayMatch = stdout.match(regex);
-            if (null == displayMatch ? void 0 : displayMatch[1]) {
+            if (displayMatch?.[1]) {
                 debugDevice(`Found physical display ID: ${displayMatch[1]} for display ID: ${this.options.displayId}`);
                 return displayMatch[1];
             }
@@ -935,11 +900,10 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
         }
     }
     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 keyboardDismissStrategy = options?.keyboardDismissStrategy ?? this.options?.keyboardDismissStrategy ?? 'esc-first';
         const keyboardStatus = await adb.isSoftKeyboardPresent();
-        const isKeyboardShown = 'boolean' == typeof keyboardStatus ? keyboardStatus : null == keyboardStatus ? void 0 : keyboardStatus.isKeyboardShown;
+        const isKeyboardShown = 'boolean' == typeof keyboardStatus ? keyboardStatus : keyboardStatus?.isKeyboardShown;
         if (!isKeyboardShown) {
             debugDevice('Keyboard has no UI; no closing necessary');
             return false;
@@ -958,7 +922,7 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
             while(Date.now() - startTime < timeoutMs){
                 await (0, utils_namespaceObject.sleep)(intervalMs);
                 const currentStatus = await adb.isSoftKeyboardPresent();
-                const isStillShown = 'boolean' == typeof currentStatus ? currentStatus : null == currentStatus ? void 0 : currentStatus.isKeyboardShown;
+                const isStillShown = 'boolean' == typeof currentStatus ? currentStatus : currentStatus?.isKeyboardShown;
                 if (!isStillShown) {
                     debugDevice(`Keyboard hidden successfully with keycode ${keyCode}`);
                     return true;
@@ -988,9 +952,53 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
         external_node_assert_default()(deviceId, 'deviceId is required for AndroidDevice');
         this.deviceId = deviceId;
         this.options = options;
-        this.customActions = null == options ? void 0 : options.customActions;
+        this.customActions = options?.customActions;
     }
 }
+const runAdbShellParamSchema = core_namespaceObject.z.string().describe('ADB shell command to execute');
+const launchParamSchema = core_namespaceObject.z.string().describe('App package name or URL to launch');
+const createPlatformActions = (device)=>({
+        RunAdbShell: (0, device_namespaceObject.defineAction)({
+            name: 'RunAdbShell',
+            description: 'Execute ADB shell command on Android device',
+            interfaceAlias: 'runAdbShell',
+            paramSchema: runAdbShellParamSchema,
+            call: async (param)=>{
+                const adb = await device.getAdb();
+                return await adb.shell(param);
+            }
+        }),
+        Launch: (0, device_namespaceObject.defineAction)({
+            name: 'Launch',
+            description: 'Launch an Android app or URL',
+            interfaceAlias: 'launch',
+            paramSchema: launchParamSchema,
+            call: async (param)=>{
+                await device.launch(param);
+            }
+        }),
+        AndroidBackButton: (0, device_namespaceObject.defineAction)({
+            name: 'AndroidBackButton',
+            description: 'Trigger the system "back" operation on Android devices',
+            call: async ()=>{
+                await device.back();
+            }
+        }),
+        AndroidHomeButton: (0, device_namespaceObject.defineAction)({
+            name: 'AndroidHomeButton',
+            description: 'Trigger the system "home" operation on Android devices',
+            call: async ()=>{
+                await device.home();
+            }
+        }),
+        AndroidRecentAppsButton: (0, device_namespaceObject.defineAction)({
+            name: 'AndroidRecentAppsButton',
+            description: 'Trigger the system "recent apps" operation on Android devices',
+            call: async ()=>{
+                await device.recentApps();
+            }
+        })
+    });
 const agent_namespaceObject = require("@midscene/core/agent");
 const debugUtils = (0, logger_namespaceObject.getDebug)('android:utils');
 async function getConnectedDevices() {
@@ -1008,35 +1016,39 @@ async function getConnectedDevices() {
         });
     }
 }
+function agent_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 debugAgent = (0, logger_namespaceObject.getDebug)('android:agent');
 class AndroidAgent extends agent_namespaceObject.Agent {
-    async launch(uri) {
-        const device = this.page;
-        await device.launch(uri);
+    createActionWrapper(name) {
+        const action = this.wrapActionInActionSpace(name);
+        return (...args)=>action(args[0]);
     }
-    async runAdbShell(command) {
-        const adb = await this.page.getAdb();
-        return await adb.shell(command);
+    constructor(device, opts){
+        super(device, opts), agent_define_property(this, "launch", void 0), agent_define_property(this, "runAdbShell", void 0), agent_define_property(this, "back", void 0), agent_define_property(this, "home", void 0), agent_define_property(this, "recentApps", void 0);
+        this.launch = this.createActionWrapper('Launch');
+        this.runAdbShell = this.createActionWrapper('RunAdbShell');
+        this.back = this.createActionWrapper('AndroidBackButton');
+        this.home = this.createActionWrapper('AndroidHomeButton');
+        this.recentApps = this.createActionWrapper('AndroidRecentAppsButton');
     }
 }
 async function agentFromAdbDevice(deviceId, opts) {
     if (!deviceId) {
         const devices = await getConnectedDevices();
+        if (0 === devices.length) throw new Error('No Android devices found. Please connect an Android device and ensure ADB is properly configured. Run `adb devices` to verify device connection.');
         deviceId = devices[0].udid;
         debugAgent('deviceId not specified, will use the first device (id = %s)', deviceId);
     }
-    const device = 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,
-        displayId: null == opts ? void 0 : opts.displayId,
-        usePhysicalDisplayIdForScreenshot: null == opts ? void 0 : opts.usePhysicalDisplayIdForScreenshot,
-        usePhysicalDisplayIdForDisplayLookup: null == opts ? void 0 : opts.usePhysicalDisplayIdForDisplayLookup,
-        screenshotResizeScale: null == opts ? void 0 : opts.screenshotResizeScale,
-        alwaysRefreshScreenInfo: null == opts ? void 0 : opts.alwaysRefreshScreenInfo
-    });
+    const device = new AndroidDevice(deviceId, opts || {});
     await device.connect();
     return new AndroidAgent(device, opts);
 }
@@ -1045,13 +1057,13 @@ exports.AndroidDevice = __webpack_exports__.AndroidDevice;
 exports.agentFromAdbDevice = __webpack_exports__.agentFromAdbDevice;
 exports.getConnectedDevices = __webpack_exports__.getConnectedDevices;
 exports.overrideAIConfig = __webpack_exports__.overrideAIConfig;
-for(var __webpack_i__ in __webpack_exports__)if (-1 === [
+for(var __rspack_i in __webpack_exports__)if (-1 === [
     "AndroidAgent",
     "AndroidDevice",
     "agentFromAdbDevice",
     "getConnectedDevices",
     "overrideAIConfig"
-].indexOf(__webpack_i__)) exports[__webpack_i__] = __webpack_exports__[__webpack_i__];
+].indexOf(__rspack_i)) exports[__rspack_i] = __webpack_exports__[__rspack_i];
 Object.defineProperty(exports, '__esModule', {
     value: true
 });

package/dist/types/index.d.ts

@@ -1,7 +1,11 @@
 import { AbstractInterface } from '@midscene/core/device';
+import type { ActionParam } from '@midscene/core';
+import type { ActionReturn } from '@midscene/core';
 import { ADB } from 'appium-adb';
 import { Agent } from '@midscene/core/agent';
 import { AgentOpt } from '@midscene/core/agent';
+import { AndroidDeviceInputOpt } from '@midscene/core/device';
+import { AndroidDeviceOpt } from '@midscene/core/device';
 import { Device } from 'appium-adb';
 import { DeviceAction } from '@midscene/core';
 import type { ElementInfo } from '@midscene/shared/extractor';
@@ -9,15 +13,38 @@ import { InterfaceType } from '@midscene/core';
 import { overrideAIConfig } from '@midscene/shared/env';
 import { Point } from '@midscene/core';
 import { Size } from '@midscene/core';
+import { z } from '@midscene/core';
+
+declare type ActionArgs<T extends DeviceAction> = [ActionParam<T>] extends [undefined] ? [] : [ActionParam<T>];
 
 export declare function agentFromAdbDevice(deviceId?: string, opts?: AndroidAgentOpt & AndroidDeviceOpt): Promise<AndroidAgent>;
 
 export declare class AndroidAgent extends Agent<AndroidDevice> {
-    launch(uri: string): Promise<void>;
-    runAdbShell(command: string): Promise<string>;
+    /**
+     * Launch an Android app or URL
+     */
+    launch: WrappedAction<DeviceActionLaunch>;
+    /**
+     * Execute ADB shell command on Android device
+     */
+    runAdbShell: WrappedAction<DeviceActionRunAdbShell>;
+    /**
+     * Trigger the system back operation on Android devices
+     */
+    back: WrappedAction<DeviceActionAndroidBackButton>;
+    /**
+     * Trigger the system home operation on Android devices
+     */
+    home: WrappedAction<DeviceActionAndroidHomeButton>;
+    /**
+     * Trigger the system recent apps operation on Android devices
+     */
+    recentApps: WrappedAction<DeviceActionAndroidRecentAppsButton>;
+    constructor(device: AndroidDevice, opts?: AndroidAgentOpt);
+    private createActionWrapper;
 }
 
-declare type AndroidAgentOpt = AgentOpt;
+export declare type AndroidAgentOpt = AgentOpt;
 
 export declare class AndroidDevice implements AbstractInterface {
     private deviceId;
@@ -49,6 +76,7 @@ export declare class AndroidDevice implements AbstractInterface {
         override: string;
         physical: string;
         orientation: number;
+        isCurrentOrientation?: boolean;
     }>;
     private initializeDevicePixelRatio;
     getDisplayDensity(): Promise<number>;
@@ -114,32 +142,35 @@ export declare class AndroidDevice implements AbstractInterface {
     hideKeyboard(options?: AndroidDeviceInputOpt, timeoutMs?: number): Promise<boolean>;
 }
 
-declare type AndroidDeviceInputOpt = {
-    autoDismissKeyboard?: boolean;
-    keyboardDismissStrategy?: 'esc-first' | 'back-first';
-};
-
-declare type AndroidDeviceOpt = {
-    androidAdbPath?: string;
-    remoteAdbHost?: string;
-    remoteAdbPort?: number;
-    imeStrategy?: ImeStrategy;
-    displayId?: number;
-    usePhysicalDisplayIdForScreenshot?: boolean;
-    usePhysicalDisplayIdForDisplayLookup?: boolean;
-    customActions?: DeviceAction<any>[];
-    screenshotResizeScale?: number;
-    alwaysRefreshScreenInfo?: boolean;
-} & AndroidDeviceInputOpt;
+declare type DeviceActionAndroidBackButton = DeviceAction<undefined, void>;
 
-export declare function getConnectedDevices(): Promise<Device[]>;
+declare type DeviceActionAndroidHomeButton = DeviceAction<undefined, void>;
+
+declare type DeviceActionAndroidRecentAppsButton = DeviceAction<undefined, void>;
 
-declare const IME_STRATEGY_ALWAYS_YADB: "always-yadb";
+declare type DeviceActionLaunch = DeviceAction<LaunchParam, void>;
 
-declare const IME_STRATEGY_YADB_FOR_NON_ASCII: "yadb-for-non-ascii";
+declare type DeviceActionRunAdbShell = DeviceAction<RunAdbShellParam, string>;
+
+export declare function getConnectedDevices(): Promise<Device[]>;
 
-declare type ImeStrategy = typeof IME_STRATEGY_ALWAYS_YADB | typeof IME_STRATEGY_YADB_FOR_NON_ASCII;
+declare type LaunchParam = z.infer<typeof launchParamSchema>;
+
+declare const launchParamSchema: z.ZodString;
 
 export { overrideAIConfig }
 
+declare type RunAdbShellParam = z.infer<typeof runAdbShellParamSchema>;
+
+/**
+ * Platform-specific action definitions for Android
+ * Single source of truth for both runtime behavior and type definitions
+ */
+declare const runAdbShellParamSchema: z.ZodString;
+
+/**
+ * Helper type to convert DeviceAction to wrapped method signature
+ */
+declare type WrappedAction<T extends DeviceAction> = (...args: ActionArgs<T>) => Promise<ActionReturn<T>>;
+
 export { }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@midscene/android",
-  "version": "0.30.10",
+  "version": "0.30.11-beta-20251218071621.0",
   "description": "Android automation library for Midscene",
   "keywords": [
     "Android UI automation",
@@ -27,23 +27,24 @@
   },
   "dependencies": {
     "appium-adb": "12.12.1",
-    "@midscene/core": "0.30.10",
-    "@midscene/shared": "0.30.10"
+    "@midscene/core": "0.30.11-beta-20251218071621.0",
+    "@midscene/shared": "0.30.11-beta-20251218071621.0"
   },
   "devDependencies": {
-    "@rslib/core": "^0.11.2",
+    "@rslib/core": "^0.18.3",
     "@types/node": "^18.0.0",
     "dotenv": "^16.4.5",
     "typescript": "^5.8.3",
     "tsx": "^4.19.2",
     "vitest": "3.0.5",
-    "@midscene/playground": "0.30.10"
+    "zod": "3.24.3",
+    "@midscene/playground": "0.30.11-beta-20251218071621.0"
   },
   "license": "MIT",
   "scripts": {
     "dev": "npm run build:watch",
     "build": "rslib build",
-    "build:watch": "rslib build --watch",
+    "build:watch": "rslib build --watch --no-clean",
     "playground": "DEBUG=midscene:* tsx demo/playground.ts",
     "test": "vitest --run",
     "test:u": "vitest --run -u",