@midscene/ios 0.30.9 → 0.30.11-beta-20251218071621.0

package/dist/lib/index.js

@@ -34,11 +34,11 @@ var __webpack_exports__ = {};
 __webpack_require__.r(__webpack_exports__);
 __webpack_require__.d(__webpack_exports__, {
     overrideAIConfig: ()=>env_namespaceObject.overrideAIConfig,
+    IOSAgent: ()=>IOSAgent,
+    checkIOSEnvironment: ()=>checkIOSEnvironment,
     IOSDevice: ()=>IOSDevice,
     IOSWebDriverClient: ()=>IOSWebDriverClient,
-    agentFromWebDriverAgent: ()=>agentFromWebDriverAgent,
-    IOSAgent: ()=>IOSAgent,
-    checkIOSEnvironment: ()=>checkIOSEnvironment
+    agentFromWebDriverAgent: ()=>agentFromWebDriverAgent
 });
 const external_node_assert_namespaceObject = require("node:assert");
 var external_node_assert_default = /*#__PURE__*/ __webpack_require__.n(external_node_assert_namespaceObject);
@@ -188,6 +188,48 @@ class IOSWebDriverClient extends webdriver_namespaceObject.WebDriverClient {
         debugIOS(`Warning: Key "${key}" is not supported on iOS platform`);
         throw new Error(`Key "${key}" is not supported on iOS platform`);
     }
+    async getActiveElement() {
+        this.ensureSession();
+        debugIOS('Getting active element');
+        try {
+            const response = await this.makeRequest('GET', `/session/${this.sessionId}/element/active`);
+            const elementId = response.value?.ELEMENT || response.value?.['element-6066-11e4-a52e-4f735466cecf'] || response.ELEMENT || response['element-6066-11e4-a52e-4f735466cecf'];
+            if (elementId) {
+                debugIOS(`Got active element ID: ${elementId}`);
+                return elementId;
+            }
+            debugIOS('No active element found');
+            return null;
+        } catch (error) {
+            debugIOS(`Failed to get active element: ${error}`);
+            return null;
+        }
+    }
+    async clearElement(elementId) {
+        this.ensureSession();
+        debugIOS(`Clearing element: ${elementId}`);
+        try {
+            await this.makeRequest('POST', `/session/${this.sessionId}/element/${elementId}/clear`);
+            debugIOS('Element cleared successfully');
+        } catch (error) {
+            debugIOS(`Failed to clear element: ${error}`);
+            throw new Error(`Failed to clear element: ${error}`);
+        }
+    }
+    async clearActiveElement() {
+        try {
+            const elementId = await this.getActiveElement();
+            if (!elementId) {
+                debugIOS('No active element to clear');
+                return false;
+            }
+            await this.clearElement(elementId);
+            return true;
+        } catch (error) {
+            debugIOS(`Failed to clear active element: ${error}`);
+            return false;
+        }
+    }
     normalizeKeyName(key) {
         return key.charAt(0).toUpperCase() + key.slice(1).toLowerCase();
     }
@@ -228,8 +270,17 @@ class IOSWebDriverClient extends webdriver_namespaceObject.WebDriverClient {
             });
             debugIOS(`Tapped at coordinates (${x}, ${y})`);
         } catch (error) {
-            debugIOS(`Failed to tap at (${x}, ${y}): ${error}`);
-            throw new Error(`Failed to tap at coordinates: ${error}`);
+            debugIOS(`New tap endpoint failed, trying legacy endpoint: ${error}`);
+            try {
+                await this.makeRequest('POST', `/session/${this.sessionId}/wda/tap/0`, {
+                    x,
+                    y
+                });
+                debugIOS(`Tapped at coordinates (${x}, ${y}) using legacy endpoint`);
+            } catch (fallbackError) {
+                debugIOS(`Failed to tap at (${x}, ${y}): ${fallbackError}`);
+                throw new Error(`Failed to tap at coordinates: ${fallbackError}`);
+            }
         }
     }
     async swipe(fromX, fromY, toX, toY, duration = 500) {
@@ -302,13 +353,34 @@ class IOSWebDriverClient extends webdriver_namespaceObject.WebDriverClient {
         debugIOS(`Triple tapped at coordinates (${x}, ${y})`);
     }
     async getScreenScale() {
-        var _screenResponse_value;
-        const screenResponse = await this.makeRequest('GET', '/wda/screen');
-        if (null == screenResponse ? void 0 : null == (_screenResponse_value = screenResponse.value) ? void 0 : _screenResponse_value.scale) {
-            debugIOS(`Got screen scale from WDA screen endpoint: ${screenResponse.value.scale}`);
-            return screenResponse.value.scale;
+        this.ensureSession();
+        try {
+            const screenResponse = await this.makeRequest('GET', `/session/${this.sessionId}/wda/screen`);
+            if (screenResponse?.value?.scale) {
+                debugIOS(`Got screen scale from WDA screen endpoint: ${screenResponse.value.scale}`);
+                return screenResponse.value.scale;
+            }
+        } catch (error) {
+            debugIOS(`Failed to get screen scale from /wda/screen: ${error}`);
+        }
+        try {
+            debugIOS('Calculating screen scale from screenshot and window size');
+            const [screenshotBase64, windowSize] = await Promise.all([
+                this.takeScreenshot(),
+                this.getWindowSize()
+            ]);
+            const { jimpFromBase64 } = await import("@midscene/shared/img");
+            const screenshotImg = await jimpFromBase64(screenshotBase64);
+            const screenshotWidth = screenshotImg.bitmap.width;
+            const screenshotHeight = screenshotImg.bitmap.height;
+            const scale = Math.max(screenshotWidth, screenshotHeight) / Math.max(windowSize.width, windowSize.height);
+            const roundedScale = Math.round(scale);
+            debugIOS(`Calculated screen scale: ${roundedScale} (screenshot: ${screenshotWidth}x${screenshotHeight}, window: ${windowSize.width}x${windowSize.height})`);
+            return roundedScale;
+        } catch (error) {
+            debugIOS(`Failed to calculate screen scale: ${error}`);
         }
-        debugIOS('No screen scale found in WDA screen response');
+        debugIOS('No screen scale found');
         return null;
     }
     async createSession(capabilities) {
@@ -335,6 +407,10 @@ class IOSWebDriverClient extends webdriver_namespaceObject.WebDriverClient {
             debugIOS(`Failed to apply iOS session configuration: ${error}`);
         }
     }
+    async executeRequest(method, endpoint, data) {
+        this.ensureSession();
+        return this.makeRequest(method, endpoint, data);
+    }
 }
 function _define_property(obj, key, value) {
     if (key in obj) Object.defineProperty(obj, key, {
@@ -347,7 +423,12 @@ function _define_property(obj, key, value) {
     return obj;
 }
 const debugDevice = (0, logger_namespaceObject.getDebug)('ios:device');
-const BackspaceChar = '\u0008';
+const WDA_HTTP_METHODS = [
+    'GET',
+    'POST',
+    'DELETE',
+    'PUT'
+];
 class IOSDevice {
     actionSpace() {
         const defaultActions = [
@@ -367,7 +448,7 @@ class IOSDevice {
                 interfaceAlias: 'aiInput',
                 paramSchema: core_namespaceObject.z.object({
                     value: core_namespaceObject.z.string().describe('The text to input. Provide the final content for replace/append modes, or an empty string when using clear mode to remove existing text.'),
-                    autoDismissKeyboard: core_namespaceObject.z.boolean().optional().describe('If true, the keyboard will be dismissed after the input is completed. Do not set it unless the user asks you to do so.'),
+                    autoDismissKeyboard: core_namespaceObject.z.boolean().optional().describe('Whether to dismiss the keyboard after input. Defaults to true if not specified. Set to false to keep the keyboard visible after input.'),
                     mode: core_namespaceObject.z["enum"]([
                         'replace',
                         'clear',
@@ -376,14 +457,13 @@ class IOSDevice {
                     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.typeText(param.value, {
                         autoDismissKeyboard
                     });
@@ -395,18 +475,18 @@ class IOSDevice {
                     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);
                 }
             }),
@@ -420,22 +500,6 @@ class IOSDevice {
             (0, device_namespaceObject.defineActionKeyboardPress)(async (param)=>{
                 await this.pressKey(param.keyName);
             }),
-            (0, device_namespaceObject.defineAction)({
-                name: 'IOSHomeButton',
-                description: 'Trigger the system "home" operation on iOS devices',
-                paramSchema: core_namespaceObject.z.object({}),
-                call: async ()=>{
-                    await this.home();
-                }
-            }),
-            (0, device_namespaceObject.defineAction)({
-                name: 'IOSAppSwitcher',
-                description: 'Trigger the system "app switcher" operation on iOS devices',
-                paramSchema: core_namespaceObject.z.object({}),
-                call: async ()=>{
-                    await this.appSwitcher();
-                }
-            }),
             (0, device_namespaceObject.defineAction)({
                 name: 'IOSLongPress',
                 description: 'Trigger a long press on the screen at specified coordinates on iOS devices',
@@ -447,7 +511,7 @@ class IOSDevice {
                     const element = param.locate;
                     external_node_assert_default()(element, 'IOSLongPress 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.defineActionClearInput)(async (param)=>{
@@ -456,9 +520,11 @@ class IOSDevice {
                 await this.clearInput(element);
             })
         ];
+        const platformSpecificActions = Object.values(createPlatformActions(this));
         const customActions = this.customActions || [];
         return [
             ...defaultActions,
+            ...platformSpecificActions,
             ...customActions
         ];
     }
@@ -475,7 +541,7 @@ class IOSDevice {
             await this.wdaManager.start();
             await this.wdaBackend.createSession();
             const deviceInfo = await this.wdaBackend.getDeviceInfo();
-            if (null == deviceInfo ? void 0 : deviceInfo.udid) {
+            if (deviceInfo?.udid) {
                 this.deviceId = deviceInfo.udid;
                 debugDevice(`Updated device ID to real UDID: ${this.deviceId}`);
             }
@@ -556,19 +622,9 @@ ScreenSize: ${size.width}x${size.height} (DPR: ${size.scale})
         if (!element) return;
         await this.tap(element.center[0], element.center[1]);
         await (0, utils_namespaceObject.sleep)(100);
-        try {
-            await this.tripleTap(element.center[0], element.center[1]);
-            await (0, utils_namespaceObject.sleep)(200);
-            await this.wdaBackend.typeText(BackspaceChar);
-        } catch (error2) {
-            debugDevice(`Method 1 failed, trying method 2: ${error2}`);
-            try {
-                const backspaces = Array(100).fill(BackspaceChar).join('');
-                await this.wdaBackend.typeText(backspaces);
-            } catch (error3) {
-                debugDevice(`All clear methods failed: ${error3}`);
-            }
-        }
+        debugDevice('Attempting to clear input with WebDriver Clear API');
+        const cleared = await this.wdaBackend.clearActiveElement();
+        cleared ? debugDevice('Successfully cleared input with WebDriver Clear API') : debugDevice('WebDriver Clear API returned false (no active element or clear failed)');
     }
     async url() {
         return '';
@@ -593,9 +649,8 @@ ScreenSize: ${size.width}x${size.height} (DPR: ${size.scale})
         await this.wdaBackend.swipe(Math.round(fromX), Math.round(fromY), Math.round(toX), Math.round(toY), duration);
     }
     async typeText(text, options) {
-        var _this_options;
         if (!text) return;
-        const shouldAutoDismissKeyboard = (null == options ? void 0 : options.autoDismissKeyboard) ?? (null == (_this_options = this.options) ? void 0 : _this_options.autoDismissKeyboard) ?? true;
+        const shouldAutoDismissKeyboard = options?.autoDismissKeyboard ?? this.options?.autoDismissKeyboard ?? true;
         debugDevice(`Typing text: "${text}"`);
         try {
             await (0, utils_namespaceObject.sleep)(200);
@@ -797,20 +852,30 @@ ScreenSize: ${size.width}x${size.height} (DPR: ${size.scale})
     }
     async hideKeyboard(keyNames) {
         try {
-            if (keyNames && keyNames.length > 0) {
-                debugDevice(`Using keyNames to dismiss keyboard: ${keyNames.join(', ')}`);
-                await this.wdaBackend.dismissKeyboard(keyNames);
-                debugDevice('Dismissed keyboard using provided keyNames');
-                await (0, utils_namespaceObject.sleep)(300);
+            const dismissKeys = keyNames && keyNames.length > 0 ? keyNames : [
+                'return',
+                'done',
+                'go',
+                'search',
+                'next',
+                'send'
+            ];
+            debugDevice(`Attempting to dismiss keyboard using WDA API with keys: ${dismissKeys.join(', ')}`);
+            try {
+                await this.wdaBackend.dismissKeyboard(dismissKeys);
+                debugDevice('Successfully dismissed keyboard using WDA API');
+                await (0, utils_namespaceObject.sleep)(500);
                 return true;
+            } catch (wdaError) {
+                debugDevice(`WDA dismissKeyboard failed, falling back to swipe gesture: ${wdaError}`);
             }
             const windowSize = await this.wdaBackend.getWindowSize();
             const centerX = Math.round(windowSize.width / 2);
-            const startY = Math.round(0.33 * windowSize.height);
-            const endY = Math.round(0.33 * windowSize.height + 10);
-            await this.swipe(centerX, startY, centerX, endY, 50);
-            debugDevice('Dismissed keyboard with swipe down gesture at screen one-third position');
-            await (0, utils_namespaceObject.sleep)(300);
+            const startY = Math.round(0.9 * windowSize.height);
+            const endY = Math.round(0.5 * windowSize.height);
+            await this.swipe(centerX, startY, centerX, endY, 300);
+            debugDevice('Dismissed keyboard with swipe up gesture from bottom of screen');
+            await (0, utils_namespaceObject.sleep)(500);
             return true;
         } catch (error) {
             debugDevice(`Failed to hide keyboard: ${error}`);
@@ -839,6 +904,7 @@ ScreenSize: ${size.width}x${size.height} (DPR: ${size.scale})
     async openUrlViaSafari(url) {
         try {
             debugDevice(`Opening URL via Safari: ${url}`);
+            await this.wdaBackend.terminateApp('com.apple.mobilesafari');
             await this.wdaBackend.launchApp('com.apple.mobilesafari');
             await (0, utils_namespaceObject.sleep)(2000);
             await this.typeText(url);
@@ -856,6 +922,9 @@ ScreenSize: ${size.width}x${size.height} (DPR: ${size.scale})
             throw new Error(`Failed to open URL via Safari: ${error}`);
         }
     }
+    async runWdaRequest(method, endpoint, data) {
+        return await this.wdaBackend.executeRequest(method, endpoint, data);
+    }
     async destroy() {
         if (this.destroyed) return;
         try {
@@ -881,9 +950,9 @@ ScreenSize: ${size.width}x${size.height} (DPR: ${size.scale})
         _define_property(this, "options", void 0);
         this.deviceId = 'pending-connection';
         this.options = options;
-        this.customActions = null == options ? void 0 : options.customActions;
-        const wdaPort = (null == options ? void 0 : options.wdaPort) || constants_namespaceObject.DEFAULT_WDA_PORT;
-        const wdaHost = (null == options ? void 0 : options.wdaHost) || 'localhost';
+        this.customActions = options?.customActions;
+        const wdaPort = options?.wdaPort || constants_namespaceObject.DEFAULT_WDA_PORT;
+        const wdaHost = options?.wdaHost || 'localhost';
         this.wdaBackend = new IOSWebDriverClient({
             port: wdaPort,
             host: wdaHost
@@ -891,6 +960,44 @@ ScreenSize: ${size.width}x${size.height} (DPR: ${size.scale})
         this.wdaManager = webdriver_namespaceObject.WDAManager.getInstance(wdaPort, wdaHost);
     }
 }
+const runWdaRequestParamSchema = core_namespaceObject.z.object({
+    method: core_namespaceObject.z["enum"](WDA_HTTP_METHODS).describe('HTTP method (GET, POST, DELETE, PUT)'),
+    endpoint: core_namespaceObject.z.string().describe('WebDriver API endpoint'),
+    data: core_namespaceObject.z.object({}).passthrough().optional().describe('Optional request body data as JSON object')
+});
+const launchParamSchema = core_namespaceObject.z.string().describe('App bundle ID or URL to launch');
+const createPlatformActions = (device)=>({
+        RunWdaRequest: (0, device_namespaceObject.defineAction)({
+            name: 'RunWdaRequest',
+            description: 'Execute WebDriverAgent API request directly on iOS device',
+            interfaceAlias: 'runWdaRequest',
+            paramSchema: runWdaRequestParamSchema,
+            call: async (param)=>await device.runWdaRequest(param.method, param.endpoint, param.data)
+        }),
+        Launch: (0, device_namespaceObject.defineAction)({
+            name: 'Launch',
+            description: 'Launch an iOS app or URL',
+            interfaceAlias: 'launch',
+            paramSchema: launchParamSchema,
+            call: async (param)=>{
+                await device.launch(param);
+            }
+        }),
+        IOSHomeButton: (0, device_namespaceObject.defineAction)({
+            name: 'IOSHomeButton',
+            description: 'Trigger the system "home" operation on iOS devices',
+            call: async ()=>{
+                await device.home();
+            }
+        }),
+        IOSAppSwitcher: (0, device_namespaceObject.defineAction)({
+            name: 'IOSAppSwitcher',
+            description: 'Trigger the system "app switcher" operation on iOS devices',
+            call: async ()=>{
+                await device.appSwitcher();
+            }
+        })
+    });
 const agent_namespaceObject = require("@midscene/core/agent");
 const external_node_child_process_namespaceObject = require("node:child_process");
 const external_node_os_namespaceObject = require("node:os");
@@ -941,24 +1048,35 @@ async function checkIOSEnvironment() {
         };
     }
 }
+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)('ios:agent');
 class IOSAgent 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]);
+    }
+    constructor(device, opts){
+        super(device, opts), agent_define_property(this, "launch", void 0), agent_define_property(this, "runWdaRequest", void 0), agent_define_property(this, "home", void 0), agent_define_property(this, "appSwitcher", void 0);
+        this.launch = this.createActionWrapper('Launch');
+        this.runWdaRequest = this.createActionWrapper('RunWdaRequest');
+        this.home = this.createActionWrapper('IOSHomeButton');
+        this.appSwitcher = this.createActionWrapper('IOSAppSwitcher');
     }
 }
 async function agentFromWebDriverAgent(opts) {
     debugAgent('Creating iOS agent with WebDriverAgent auto-detection');
     const envCheck = await checkIOSEnvironment();
     if (!envCheck.available) throw new Error(`iOS environment not available: ${envCheck.error}`);
-    const device = new IOSDevice({
-        autoDismissKeyboard: null == opts ? void 0 : opts.autoDismissKeyboard,
-        customActions: null == opts ? void 0 : opts.customActions,
-        wdaPort: null == opts ? void 0 : opts.wdaPort,
-        wdaHost: null == opts ? void 0 : opts.wdaHost,
-        useWDA: null == opts ? void 0 : opts.useWDA
-    });
+    const device = new IOSDevice(opts || {});
     await device.connect();
     return new IOSAgent(device, opts);
 }
@@ -969,14 +1087,14 @@ exports.IOSWebDriverClient = __webpack_exports__.IOSWebDriverClient;
 exports.agentFromWebDriverAgent = __webpack_exports__.agentFromWebDriverAgent;
 exports.checkIOSEnvironment = __webpack_exports__.checkIOSEnvironment;
 exports.overrideAIConfig = __webpack_exports__.overrideAIConfig;
-for(var __webpack_i__ in __webpack_exports__)if (-1 === [
+for(var __rspack_i in __webpack_exports__)if (-1 === [
     "IOSAgent",
     "IOSDevice",
     "IOSWebDriverClient",
     "agentFromWebDriverAgent",
     "checkIOSEnvironment",
     "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,13 +1,20 @@
 import { AbstractInterface } from '@midscene/core/device';
+import type { ActionParam } from '@midscene/core';
+import type { ActionReturn } from '@midscene/core';
 import { Agent } from '@midscene/core/agent';
 import { AgentOpt } from '@midscene/core/agent';
 import { DeviceAction } from '@midscene/core';
 import type { ElementInfo } from '@midscene/shared/extractor';
 import { InterfaceType } from '@midscene/core';
+import { IOSDeviceInputOpt } from '@midscene/core/device';
+import { IOSDeviceOpt } from '@midscene/core/device';
 import { overrideAIConfig } from '@midscene/shared/env';
 import { Point } from '@midscene/core';
 import { Size } from '@midscene/core';
 import { WebDriverClient } from '@midscene/webdriver';
+import { z } from '@midscene/core';
+
+declare type ActionArgs<T extends DeviceAction> = [ActionParam<T>] extends [undefined] ? [] : [ActionParam<T>];
 
 export declare function agentFromWebDriverAgent(opts?: IOSAgentOpt & IOSDeviceOpt): Promise<IOSAgent>;
 
@@ -16,11 +23,38 @@ export declare function checkIOSEnvironment(): Promise<{
     error?: string;
 }>;
 
+declare type DeviceActionIOSAppSwitcher = DeviceAction<undefined, void>;
+
+declare type DeviceActionIOSHomeButton = DeviceAction<undefined, void>;
+
+declare type DeviceActionLaunch = DeviceAction<LaunchParam, void>;
+
+declare type DeviceActionRunWdaRequest = DeviceAction<RunWdaRequestParam, RunWdaRequestReturn>;
+
 export declare class IOSAgent extends Agent<IOSDevice> {
-    launch(uri: string): Promise<void>;
+    /**
+     * Launch an iOS app or URL
+     * Type-safe wrapper around the Launch action from actionSpace
+     */
+    launch: WrappedAction<DeviceActionLaunch>;
+    /**
+     * Execute WebDriverAgent API request directly
+     * Type-safe wrapper around the RunWdaRequest action from actionSpace
+     */
+    runWdaRequest: WrappedAction<DeviceActionRunWdaRequest>;
+    /**
+     * Trigger the system home operation on iOS devices
+     */
+    home: WrappedAction<DeviceActionIOSHomeButton>;
+    /**
+     * Trigger the system app switcher operation on iOS devices
+     */
+    appSwitcher: WrappedAction<DeviceActionIOSAppSwitcher>;
+    constructor(device: IOSDevice, opts?: IOSAgentOpt);
+    private createActionWrapper;
 }
 
-declare type IOSAgentOpt = AgentOpt;
+export declare type IOSAgentOpt = AgentOpt;
 
 export declare class IOSDevice implements AbstractInterface {
     private deviceId;
@@ -91,21 +125,18 @@ export declare class IOSDevice implements AbstractInterface {
      * @param url The URL to open
      */
     openUrlViaSafari(url: string): Promise<void>;
+    /**
+     * Execute a WebDriverAgent API request directly
+     * This is the iOS equivalent of Android's runAdbShell
+     * @param method HTTP method (GET, POST, DELETE, PUT)
+     * @param endpoint WebDriver API endpoint
+     * @param data Optional request body data
+     * @returns Response from the WebDriver API
+     */
+    runWdaRequest<TResult = any>(method: WDAHttpMethod, endpoint: string, data?: any): Promise<TResult>;
     destroy(): Promise<void>;
 }
 
-declare type IOSDeviceInputOpt = {
-    autoDismissKeyboard?: boolean;
-};
-
-declare type IOSDeviceOpt = {
-    deviceId?: string;
-    customActions?: DeviceAction<any>[];
-    wdaPort?: number;
-    wdaHost?: string;
-    useWDA?: boolean;
-} & IOSDeviceInputOpt;
-
 export declare class IOSWebDriverClient extends WebDriverClient {
     launchApp(bundleId: string): Promise<void>;
     activateApp(bundleId: string): Promise<void>;
@@ -114,6 +145,21 @@ export declare class IOSWebDriverClient extends WebDriverClient {
     pressHomeButton(): Promise<void>;
     appSwitcher(): Promise<void>;
     pressKey(key: string): Promise<void>;
+    /**
+     * Get the currently focused element's WebDriver ID
+     * @returns WebDriver element ID or null if no element is focused
+     */
+    getActiveElement(): Promise<string | null>;
+    /**
+     * Clear an element using WebDriver's clear endpoint
+     * @param elementId WebDriver element ID
+     */
+    clearElement(elementId: string): Promise<void>;
+    /**
+     * Clear the currently focused input field using WebDriver Clear API
+     * @returns true if successful, false otherwise
+     */
+    clearActiveElement(): Promise<boolean>;
     private normalizeKeyName;
     dismissKeyboard(keyNames?: string[]): Promise<boolean>;
     typeText(text: string): Promise<void>;
@@ -125,8 +171,51 @@ export declare class IOSWebDriverClient extends WebDriverClient {
     getScreenScale(): Promise<number | null>;
     createSession(capabilities?: any): Promise<any>;
     private setupIOSSession;
+    /**
+     * Execute a WebDriverAgent API request directly
+     * This is the iOS equivalent of Android's runAdbShell
+     * @param method HTTP method (GET, POST, DELETE, etc.)
+     * @param endpoint WebDriver API endpoint
+     * @param data Optional request body data
+     * @returns Response from the WebDriver API
+     */
+    executeRequest<TResult = any>(method: string, endpoint: string, data?: any): Promise<TResult>;
 }
 
+declare type LaunchParam = z.infer<typeof launchParamSchema>;
+
+declare const launchParamSchema: z.ZodString;
+
 export { overrideAIConfig }
 
+declare type RunWdaRequestParam = z.infer<typeof runWdaRequestParamSchema>;
+
+declare const runWdaRequestParamSchema: z.ZodObject<{
+    method: z.ZodEnum<["GET", "POST", "DELETE", "PUT"]>;
+    endpoint: z.ZodString;
+    data: z.ZodOptional<z.ZodObject<{}, "passthrough", z.ZodTypeAny, z.objectOutputType<{}, z.ZodTypeAny, "passthrough">, z.objectInputType<{}, z.ZodTypeAny, "passthrough">>>;
+}, "strip", z.ZodTypeAny, {
+    method: "POST" | "GET" | "DELETE" | "PUT";
+    endpoint: string;
+    data?: z.objectOutputType<{}, z.ZodTypeAny, "passthrough"> | undefined;
+}, {
+    method: "POST" | "GET" | "DELETE" | "PUT";
+    endpoint: string;
+    data?: z.objectInputType<{}, z.ZodTypeAny, "passthrough"> | undefined;
+}>;
+
+declare type RunWdaRequestReturn = Awaited<ReturnType<IOSDevice['runWdaRequest']>>;
+
+/**
+ * HTTP methods supported by WebDriverAgent API
+ */
+declare const WDA_HTTP_METHODS: readonly ["GET", "POST", "DELETE", "PUT"];
+
+declare type WDAHttpMethod = (typeof WDA_HTTP_METHODS)[number];
+
+/**
+ * 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/ios",
-  "version": "0.30.9",
+  "version": "0.30.11-beta-20251218071621.0",
   "description": "iOS automation library for Midscene",
   "keywords": [
     "iOS UI automation",
@@ -38,24 +38,25 @@
   "dependencies": {
     "@inquirer/prompts": "^7.8.6",
     "open": "10.1.0",
-    "@midscene/core": "0.30.9",
-    "@midscene/shared": "0.30.9",
-    "@midscene/webdriver": "0.30.9"
+    "@midscene/shared": "0.30.11-beta-20251218071621.0",
+    "@midscene/webdriver": "0.30.11-beta-20251218071621.0",
+    "@midscene/core": "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.9"
+    "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",