@midscene/ios 1.13.3 → 1.13.4-beta-20260924030824.0

package/dist/es/bin.mjs

@@ -2,6 +2,7 @@ import node_path from "node:path";
 import { createMjpegPreviewDescriptor, definePlaygroundPlatform, launchPreparedPlaygroundPlatform } from "@midscene/playground";
 import { DEFAULT_WDA_PORT, PLAYGROUND_SERVER_PORT } from "@midscene/shared/constants";
 import { findAvailablePort } from "@midscene/shared/node";
+import { WDAManager, WebDriverClient, normalizeWebDriverBaseUrl } from "@midscene/webdriver";
 import { Agent } from "@midscene/core/agent";
 import { MIDSCENE_IOS_DEVICE_CLASS_OVERRIDE } from "@midscene/shared/env";
 import { getDebug } from "@midscene/shared/logger";
@@ -11,7 +12,6 @@ import { z } from "@midscene/core";
 import { createDefaultMobileActions, defineAction, resolveTextInputOptions, sendTextSequentially, shouldInputSequentially } from "@midscene/core/device";
 import { sleep } from "@midscene/core/utils";
 import { createImgBase64ByFormat } from "@midscene/shared/img";
-import { WDAManager, WebDriverClient } from "@midscene/webdriver";
 import { createAgentTestRunnerNodeDefinition } from "@midscene/core/agent/test";
 import { z as v4_z } from "zod/v4";
 const defaultAppNameMapping = {
@@ -1653,11 +1653,14 @@ ScreenSize: ${size.width}x${size.height} (DPR: ${size.scale})
         this.wdaBackend = new IOSWebDriverClient({
             port: wdaPort,
             host: wdaHost,
+            ...options?.wdaBaseUrl !== void 0 ? {
+                baseUrl: options.wdaBaseUrl
+            } : {},
             ...options?.sessionId ? {
                 sessionId: options.sessionId
             } : {}
         });
-        this.wdaManager = WDAManager.getInstance(wdaPort, wdaHost);
+        this.wdaManager = WDAManager.getInstance(wdaPort, wdaHost, options?.wdaBaseUrl);
         this.mjpegStreamUrl = `http://${wdaHost}:${mjpegPort}`;
         if (options?.wdaMjpegFrameSource?.enabled) this.openFrameSource = ()=>this.openMjpegFrameSource();
     }
@@ -1930,6 +1933,13 @@ const iosPlaygroundPlatform = definePlaygroundPlatform({
                             defaultValue: DEFAULT_WDA_PORT,
                             placeholder: DEFAULT_WDA_PORT.toString()
                         },
+                        {
+                            key: 'baseUrl',
+                            label: 'WebDriverAgent base URL (optional)',
+                            type: 'text',
+                            required: false,
+                            placeholder: 'https://gateway.example/device/wda'
+                        },
                         {
                             key: 'sessionId',
                             label: 'WebDriverAgent session ID',
@@ -1941,21 +1951,26 @@ const iosPlaygroundPlatform = definePlaygroundPlatform({
                 };
             },
             async createSession (input) {
+                const baseUrl = 'string' == typeof input?.baseUrl && input.baseUrl.trim() ? normalizeWebDriverBaseUrl(input.baseUrl.trim()) : void 0;
                 const host = 'string' == typeof input?.host && input.host.trim() ? input.host.trim().replace(/^https?:\/\//, '') : 'localhost';
-                const port = 'number' == typeof input?.port ? input.port : Number.parseInt(String(input?.port ?? DEFAULT_WDA_PORT), 10);
+                const port = baseUrl ? DEFAULT_WDA_PORT : 'number' == typeof input?.port ? input.port : Number.parseInt(String(input?.port ?? DEFAULT_WDA_PORT), 10);
                 if (Number.isNaN(port) || port < 1 || port > 65535) throw new Error(`Invalid WebDriverAgent port: ${String(input?.port)}`);
                 const sessionId = 'string' == typeof input?.sessionId && input.sessionId.trim() ? input.sessionId.trim() : void 0;
                 const connectAgent = async ()=>agentFromWebDriverAgent({
                         ...options?.getAgentOptions?.(),
                         wdaHost: host,
                         wdaPort: port,
+                        ...baseUrl ? {
+                            wdaBaseUrl: baseUrl
+                        } : {},
                         ...sessionId ? {
                             sessionId
                         } : {}
                     });
                 const agent = await connectAgent();
                 const deviceInfo = await agent.interface.getConnectedDeviceInfo?.();
-                const displayName = deviceInfo ? `${deviceInfo.name} (${deviceInfo.model})` : `${host}:${port}`;
+                const gatewayUrl = baseUrl ? new URL(baseUrl) : void 0;
+                const displayName = deviceInfo ? `${deviceInfo.name} (${deviceInfo.model})` : gatewayUrl ? `${gatewayUrl.host} (WDA gateway)` : `${host}:${port}`;
                 return {
                     agent,
                     agentFactory: connectAgent,
@@ -1964,8 +1979,8 @@ const iosPlaygroundPlatform = definePlaygroundPlatform({
                     }),
                     displayName,
                     metadata: {
-                        wdaHost: host,
-                        wdaPort: port,
+                        wdaHost: gatewayUrl?.hostname ?? host,
+                        wdaPort: gatewayUrl ? Number(gatewayUrl.port || ('https:' === gatewayUrl.protocol ? 443 : 80)) : port,
                         ...sessionId ? {
                             sessionId
                         } : {},

package/dist/es/cli.mjs

@@ -1,5 +1,6 @@
 import { createReportCliCommands, z } from "@midscene/core";
 import { reportCLIError, runToolsCLI } from "@midscene/shared/cli";
+import { createHash } from "node:crypto";
 import { agentBehaviorInitArgShape, getAgentInitArgsSignature, shouldRebuildAgentForInitArgs } from "@midscene/shared/agent-tools/agent-behavior-init-args";
 import { BaseMidsceneTools } from "@midscene/shared/agent-tools/base-tools";
 import { getDebug } from "@midscene/shared/logger";
@@ -1653,11 +1654,14 @@ ScreenSize: ${size.width}x${size.height} (DPR: ${size.scale})
         this.wdaBackend = new IOSWebDriverClient({
             port: wdaPort,
             host: wdaHost,
+            ...options?.wdaBaseUrl !== void 0 ? {
+                baseUrl: options.wdaBaseUrl
+            } : {},
             ...options?.sessionId ? {
                 sessionId: options.sessionId
             } : {}
         });
-        this.wdaManager = WDAManager.getInstance(wdaPort, wdaHost);
+        this.wdaManager = WDAManager.getInstance(wdaPort, wdaHost, options?.wdaBaseUrl);
         this.mjpegStreamUrl = `http://${wdaHost}:${mjpegPort}`;
         if (options?.wdaMjpegFrameSource?.enabled) this.openFrameSource = ()=>this.openMjpegFrameSource();
     }
@@ -1893,6 +1897,7 @@ function agent_tools_define_property(obj, key, value) {
 }
 const agent_tools_debug = getDebug('agent-tools:ios');
 const iosInitArgShape = {
+    wdaBaseUrl: z.string().optional().describe('Full WebDriverAgent API base URL, including gateway path prefix'),
     wdaHost: z.string().optional().describe('WebDriverAgent host, defaults to localhost'),
     wdaPort: z.number().optional().describe('WebDriverAgent port'),
     sessionId: z.string().optional().describe('Existing WebDriverAgent session ID to reuse'),
@@ -1903,6 +1908,10 @@ const iosInitArgShape = {
     ...agentBehaviorInitArgShape
 };
 function getTargetIdentity(initArgs) {
+    if (initArgs?.wdaBaseUrl) {
+        const fingerprint = createHash('sha256').update(`${initArgs.wdaBaseUrl}\0${initArgs.sessionId ?? ''}`).digest('hex').slice(0, 12);
+        return `wda-${fingerprint}`;
+    }
     if (initArgs?.wdaHost || initArgs?.wdaPort || initArgs?.sessionId) {
         const wdaHost = initArgs.wdaHost ?? 'localhost';
         const wdaPort = initArgs.wdaPort ?? 'default';
@@ -1929,7 +1938,7 @@ class IOSMidsceneTools extends BaseMidsceneTools {
             this.agent = void 0;
         }
         if (this.agent) return this.agent;
-        agent_tools_debug('Creating iOS agent with WebDriverAgent options:', opts || {});
+        agent_tools_debug('Creating iOS agent with WebDriverAgent options');
         const reportOptions = this.readCliReportAgentOptions();
         this.agent = await agentFromWebDriverAgent({
             autoDismissKeyboard: false,
@@ -1996,7 +2005,7 @@ class IOSMidsceneTools extends BaseMidsceneTools {
 const tools = new IOSMidsceneTools();
 runToolsCLI(tools, 'midscene-ios', {
     stripPrefix: 'ios_',
-    version: "1.13.3",
+    version: "1.13.4-beta-20260924030824.0",
     extraCommands: createReportCliCommands()
 }).catch((e)=>{
     process.exit(reportCLIError(e));

package/dist/es/index.mjs

@@ -6,11 +6,12 @@ import { DEFAULT_WDA_PORT, PLAYGROUND_SERVER_PORT } from "@midscene/shared/const
 import { createImgBase64ByFormat } from "@midscene/shared/img";
 import { getDebug } from "@midscene/shared/logger";
 import { mergeAndNormalizeAppNameMapping, normalizeForComparison } from "@midscene/shared/utils";
-import { WDAManager, WebDriverClient } from "@midscene/webdriver";
+import { WDAManager, WebDriverClient, normalizeWebDriverBaseUrl } from "@midscene/webdriver";
 import { Agent } from "@midscene/core/agent";
 import { MIDSCENE_IOS_DEVICE_CLASS_OVERRIDE, overrideAIConfig } from "@midscene/shared/env";
 import { createAgentTestRunnerNodeDefinition } from "@midscene/core/agent/test";
 import { z as v4_z } from "zod/v4";
+import { createHash } from "node:crypto";
 import { agentBehaviorInitArgShape, getAgentInitArgsSignature, shouldRebuildAgentForInitArgs } from "@midscene/shared/agent-tools/agent-behavior-init-args";
 import { BaseMidsceneTools } from "@midscene/shared/agent-tools/base-tools";
 import { exec } from "node:child_process";
@@ -1474,11 +1475,14 @@ ScreenSize: ${size.width}x${size.height} (DPR: ${size.scale})
         this.wdaBackend = new IOSWebDriverClient({
             port: wdaPort,
             host: wdaHost,
+            ...options?.wdaBaseUrl !== void 0 ? {
+                baseUrl: options.wdaBaseUrl
+            } : {},
             ...options?.sessionId ? {
                 sessionId: options.sessionId
             } : {}
         });
-        this.wdaManager = WDAManager.getInstance(wdaPort, wdaHost);
+        this.wdaManager = WDAManager.getInstance(wdaPort, wdaHost, options?.wdaBaseUrl);
         this.mjpegStreamUrl = `http://${wdaHost}:${mjpegPort}`;
         if (options?.wdaMjpegFrameSource?.enabled) this.openFrameSource = ()=>this.openMjpegFrameSource();
     }
@@ -1898,6 +1902,7 @@ function agent_tools_define_property(obj, key, value) {
 }
 const agent_tools_debug = getDebug('agent-tools:ios');
 const iosInitArgShape = {
+    wdaBaseUrl: z.string().optional().describe('Full WebDriverAgent API base URL, including gateway path prefix'),
     wdaHost: z.string().optional().describe('WebDriverAgent host, defaults to localhost'),
     wdaPort: z.number().optional().describe('WebDriverAgent port'),
     sessionId: z.string().optional().describe('Existing WebDriverAgent session ID to reuse'),
@@ -1908,6 +1913,10 @@ const iosInitArgShape = {
     ...agentBehaviorInitArgShape
 };
 function getTargetIdentity(initArgs) {
+    if (initArgs?.wdaBaseUrl) {
+        const fingerprint = createHash('sha256').update(`${initArgs.wdaBaseUrl}\0${initArgs.sessionId ?? ''}`).digest('hex').slice(0, 12);
+        return `wda-${fingerprint}`;
+    }
     if (initArgs?.wdaHost || initArgs?.wdaPort || initArgs?.sessionId) {
         const wdaHost = initArgs.wdaHost ?? 'localhost';
         const wdaPort = initArgs.wdaPort ?? 'default';
@@ -1934,7 +1943,7 @@ class IOSMidsceneTools extends BaseMidsceneTools {
             this.agent = void 0;
         }
         if (this.agent) return this.agent;
-        agent_tools_debug('Creating iOS agent with WebDriverAgent options:', opts || {});
+        agent_tools_debug('Creating iOS agent with WebDriverAgent options');
         const reportOptions = this.readCliReportAgentOptions();
         this.agent = await agentFromWebDriverAgent({
             autoDismissKeyboard: false,
@@ -2093,6 +2102,13 @@ const iosPlaygroundPlatform = definePlaygroundPlatform({
                             defaultValue: DEFAULT_WDA_PORT,
                             placeholder: DEFAULT_WDA_PORT.toString()
                         },
+                        {
+                            key: 'baseUrl',
+                            label: 'WebDriverAgent base URL (optional)',
+                            type: 'text',
+                            required: false,
+                            placeholder: 'https://gateway.example/device/wda'
+                        },
                         {
                             key: 'sessionId',
                             label: 'WebDriverAgent session ID',
@@ -2104,21 +2120,26 @@ const iosPlaygroundPlatform = definePlaygroundPlatform({
                 };
             },
             async createSession (input) {
+                const baseUrl = 'string' == typeof input?.baseUrl && input.baseUrl.trim() ? normalizeWebDriverBaseUrl(input.baseUrl.trim()) : void 0;
                 const host = 'string' == typeof input?.host && input.host.trim() ? input.host.trim().replace(/^https?:\/\//, '') : 'localhost';
-                const port = 'number' == typeof input?.port ? input.port : Number.parseInt(String(input?.port ?? DEFAULT_WDA_PORT), 10);
+                const port = baseUrl ? DEFAULT_WDA_PORT : 'number' == typeof input?.port ? input.port : Number.parseInt(String(input?.port ?? DEFAULT_WDA_PORT), 10);
                 if (Number.isNaN(port) || port < 1 || port > 65535) throw new Error(`Invalid WebDriverAgent port: ${String(input?.port)}`);
                 const sessionId = 'string' == typeof input?.sessionId && input.sessionId.trim() ? input.sessionId.trim() : void 0;
                 const connectAgent = async ()=>agentFromWebDriverAgent({
                         ...options?.getAgentOptions?.(),
                         wdaHost: host,
                         wdaPort: port,
+                        ...baseUrl ? {
+                            wdaBaseUrl: baseUrl
+                        } : {},
                         ...sessionId ? {
                             sessionId
                         } : {}
                     });
                 const agent = await connectAgent();
                 const deviceInfo = await agent.interface.getConnectedDeviceInfo?.();
-                const displayName = deviceInfo ? `${deviceInfo.name} (${deviceInfo.model})` : `${host}:${port}`;
+                const gatewayUrl = baseUrl ? new URL(baseUrl) : void 0;
+                const displayName = deviceInfo ? `${deviceInfo.name} (${deviceInfo.model})` : gatewayUrl ? `${gatewayUrl.host} (WDA gateway)` : `${host}:${port}`;
                 return {
                     agent,
                     agentFactory: connectAgent,
@@ -2127,8 +2148,8 @@ const iosPlaygroundPlatform = definePlaygroundPlatform({
                     }),
                     displayName,
                     metadata: {
-                        wdaHost: host,
-                        wdaPort: port,
+                        wdaHost: gatewayUrl?.hostname ?? host,
+                        wdaPort: gatewayUrl ? Number(gatewayUrl.port || ('https:' === gatewayUrl.protocol ? 443 : 80)) : port,
                         ...sessionId ? {
                             sessionId
                         } : {},

package/dist/lib/bin.js

@@ -141,6 +141,7 @@ var __webpack_exports__ = {};
     const playground_namespaceObject = require("@midscene/playground");
     const constants_namespaceObject = require("@midscene/shared/constants");
     const node_namespaceObject = require("@midscene/shared/node");
+    const webdriver_namespaceObject = require("@midscene/webdriver");
     const agent_namespaceObject = require("@midscene/core/agent");
     const env_namespaceObject = require("@midscene/shared/env");
     const logger_namespaceObject = require("@midscene/shared/logger");
@@ -335,7 +336,6 @@ var __webpack_exports__ = {};
     const device_namespaceObject = require("@midscene/core/device");
     const core_utils_namespaceObject = require("@midscene/core/utils");
     const img_namespaceObject = require("@midscene/shared/img");
-    const webdriver_namespaceObject = require("@midscene/webdriver");
     const keyboardAccessoryToolbarGeometry = {
         minHeight: 24,
         maxHeight: 80,
@@ -1791,11 +1791,14 @@ ScreenSize: ${size.width}x${size.height} (DPR: ${size.scale})
             this.wdaBackend = new IOSWebDriverClient({
                 port: wdaPort,
                 host: wdaHost,
+                ...options?.wdaBaseUrl !== void 0 ? {
+                    baseUrl: options.wdaBaseUrl
+                } : {},
                 ...options?.sessionId ? {
                     sessionId: options.sessionId
                 } : {}
             });
-            this.wdaManager = webdriver_namespaceObject.WDAManager.getInstance(wdaPort, wdaHost);
+            this.wdaManager = webdriver_namespaceObject.WDAManager.getInstance(wdaPort, wdaHost, options?.wdaBaseUrl);
             this.mjpegStreamUrl = `http://${wdaHost}:${mjpegPort}`;
             if (options?.wdaMjpegFrameSource?.enabled) this.openFrameSource = ()=>this.openMjpegFrameSource();
         }
@@ -1973,6 +1976,13 @@ ScreenSize: ${size.width}x${size.height} (DPR: ${size.scale})
                                 defaultValue: constants_namespaceObject.DEFAULT_WDA_PORT,
                                 placeholder: constants_namespaceObject.DEFAULT_WDA_PORT.toString()
                             },
+                            {
+                                key: 'baseUrl',
+                                label: 'WebDriverAgent base URL (optional)',
+                                type: 'text',
+                                required: false,
+                                placeholder: 'https://gateway.example/device/wda'
+                            },
                             {
                                 key: 'sessionId',
                                 label: 'WebDriverAgent session ID',
@@ -1984,21 +1994,26 @@ ScreenSize: ${size.width}x${size.height} (DPR: ${size.scale})
                     };
                 },
                 async createSession (input) {
+                    const baseUrl = 'string' == typeof input?.baseUrl && input.baseUrl.trim() ? (0, webdriver_namespaceObject.normalizeWebDriverBaseUrl)(input.baseUrl.trim()) : void 0;
                     const host = 'string' == typeof input?.host && input.host.trim() ? input.host.trim().replace(/^https?:\/\//, '') : 'localhost';
-                    const port = 'number' == typeof input?.port ? input.port : Number.parseInt(String(input?.port ?? constants_namespaceObject.DEFAULT_WDA_PORT), 10);
+                    const port = baseUrl ? constants_namespaceObject.DEFAULT_WDA_PORT : 'number' == typeof input?.port ? input.port : Number.parseInt(String(input?.port ?? constants_namespaceObject.DEFAULT_WDA_PORT), 10);
                     if (Number.isNaN(port) || port < 1 || port > 65535) throw new Error(`Invalid WebDriverAgent port: ${String(input?.port)}`);
                     const sessionId = 'string' == typeof input?.sessionId && input.sessionId.trim() ? input.sessionId.trim() : void 0;
                     const connectAgent = async ()=>agentFromWebDriverAgent({
                             ...options?.getAgentOptions?.(),
                             wdaHost: host,
                             wdaPort: port,
+                            ...baseUrl ? {
+                                wdaBaseUrl: baseUrl
+                            } : {},
                             ...sessionId ? {
                                 sessionId
                             } : {}
                         });
                     const agent = await connectAgent();
                     const deviceInfo = await agent.interface.getConnectedDeviceInfo?.();
-                    const displayName = deviceInfo ? `${deviceInfo.name} (${deviceInfo.model})` : `${host}:${port}`;
+                    const gatewayUrl = baseUrl ? new URL(baseUrl) : void 0;
+                    const displayName = deviceInfo ? `${deviceInfo.name} (${deviceInfo.model})` : gatewayUrl ? `${gatewayUrl.host} (WDA gateway)` : `${host}:${port}`;
                     return {
                         agent,
                         agentFactory: connectAgent,
@@ -2007,8 +2022,8 @@ ScreenSize: ${size.width}x${size.height} (DPR: ${size.scale})
                         }),
                         displayName,
                         metadata: {
-                            wdaHost: host,
-                            wdaPort: port,
+                            wdaHost: gatewayUrl?.hostname ?? host,
+                            wdaPort: gatewayUrl ? Number(gatewayUrl.port || ('https:' === gatewayUrl.protocol ? 443 : 80)) : port,
                             ...sessionId ? {
                                 sessionId
                             } : {},

package/dist/lib/cli.js

@@ -138,6 +138,7 @@ var __webpack_exports__ = {};
 (()=>{
     const core_namespaceObject = require("@midscene/core");
     const cli_namespaceObject = require("@midscene/shared/cli");
+    const external_node_crypto_namespaceObject = require("node:crypto");
     const agent_behavior_init_args_namespaceObject = require("@midscene/shared/agent-tools/agent-behavior-init-args");
     const base_tools_namespaceObject = require("@midscene/shared/agent-tools/base-tools");
     const logger_namespaceObject = require("@midscene/shared/logger");
@@ -1790,11 +1791,14 @@ ScreenSize: ${size.width}x${size.height} (DPR: ${size.scale})
             this.wdaBackend = new IOSWebDriverClient({
                 port: wdaPort,
                 host: wdaHost,
+                ...options?.wdaBaseUrl !== void 0 ? {
+                    baseUrl: options.wdaBaseUrl
+                } : {},
                 ...options?.sessionId ? {
                     sessionId: options.sessionId
                 } : {}
             });
-            this.wdaManager = webdriver_namespaceObject.WDAManager.getInstance(wdaPort, wdaHost);
+            this.wdaManager = webdriver_namespaceObject.WDAManager.getInstance(wdaPort, wdaHost, options?.wdaBaseUrl);
             this.mjpegStreamUrl = `http://${wdaHost}:${mjpegPort}`;
             if (options?.wdaMjpegFrameSource?.enabled) this.openFrameSource = ()=>this.openMjpegFrameSource();
         }
@@ -1935,6 +1939,7 @@ ScreenSize: ${size.width}x${size.height} (DPR: ${size.scale})
     }
     const agent_tools_debug = (0, logger_namespaceObject.getDebug)('agent-tools:ios');
     const iosInitArgShape = {
+        wdaBaseUrl: core_namespaceObject.z.string().optional().describe('Full WebDriverAgent API base URL, including gateway path prefix'),
         wdaHost: core_namespaceObject.z.string().optional().describe('WebDriverAgent host, defaults to localhost'),
         wdaPort: core_namespaceObject.z.number().optional().describe('WebDriverAgent port'),
         sessionId: core_namespaceObject.z.string().optional().describe('Existing WebDriverAgent session ID to reuse'),
@@ -1945,6 +1950,10 @@ ScreenSize: ${size.width}x${size.height} (DPR: ${size.scale})
         ...agent_behavior_init_args_namespaceObject.agentBehaviorInitArgShape
     };
     function getTargetIdentity(initArgs) {
+        if (initArgs?.wdaBaseUrl) {
+            const fingerprint = (0, external_node_crypto_namespaceObject.createHash)('sha256').update(`${initArgs.wdaBaseUrl}\0${initArgs.sessionId ?? ''}`).digest('hex').slice(0, 12);
+            return `wda-${fingerprint}`;
+        }
         if (initArgs?.wdaHost || initArgs?.wdaPort || initArgs?.sessionId) {
             const wdaHost = initArgs.wdaHost ?? 'localhost';
             const wdaPort = initArgs.wdaPort ?? 'default';
@@ -1971,7 +1980,7 @@ ScreenSize: ${size.width}x${size.height} (DPR: ${size.scale})
                 this.agent = void 0;
             }
             if (this.agent) return this.agent;
-            agent_tools_debug('Creating iOS agent with WebDriverAgent options:', opts || {});
+            agent_tools_debug('Creating iOS agent with WebDriverAgent options');
             const reportOptions = this.readCliReportAgentOptions();
             this.agent = await agentFromWebDriverAgent({
                 autoDismissKeyboard: false,
@@ -2038,7 +2047,7 @@ ScreenSize: ${size.width}x${size.height} (DPR: ${size.scale})
     const tools = new IOSMidsceneTools();
     (0, cli_namespaceObject.runToolsCLI)(tools, 'midscene-ios', {
         stripPrefix: 'ios_',
-        version: "1.13.3",
+        version: "1.13.4-beta-20260924030824.0",
         extraCommands: (0, core_namespaceObject.createReportCliCommands)()
     }).catch((e)=>{
         process.exit((0, cli_namespaceObject.reportCLIError)(e));

package/dist/lib/index.js

@@ -1631,11 +1631,14 @@ ScreenSize: ${size.width}x${size.height} (DPR: ${size.scale})
             this.wdaBackend = new IOSWebDriverClient({
                 port: wdaPort,
                 host: wdaHost,
+                ...options?.wdaBaseUrl !== void 0 ? {
+                    baseUrl: options.wdaBaseUrl
+                } : {},
                 ...options?.sessionId ? {
                     sessionId: options.sessionId
                 } : {}
             });
-            this.wdaManager = webdriver_namespaceObject.WDAManager.getInstance(wdaPort, wdaHost);
+            this.wdaManager = webdriver_namespaceObject.WDAManager.getInstance(wdaPort, wdaHost, options?.wdaBaseUrl);
             this.mjpegStreamUrl = `http://${wdaHost}:${mjpegPort}`;
             if (options?.wdaMjpegFrameSource?.enabled) this.openFrameSource = ()=>this.openMjpegFrameSource();
         }
@@ -1950,6 +1953,7 @@ ScreenSize: ${size.width}x${size.height} (DPR: ${size.scale})
         await device.connect();
         return new IOSAgent(device, opts);
     }
+    const external_node_crypto_namespaceObject = require("node:crypto");
     const agent_behavior_init_args_namespaceObject = require("@midscene/shared/agent-tools/agent-behavior-init-args");
     const base_tools_namespaceObject = require("@midscene/shared/agent-tools/base-tools");
     function agent_tools_define_property(obj, key, value) {
@@ -1964,6 +1968,7 @@ ScreenSize: ${size.width}x${size.height} (DPR: ${size.scale})
     }
     const agent_tools_debug = (0, logger_namespaceObject.getDebug)('agent-tools:ios');
     const iosInitArgShape = {
+        wdaBaseUrl: core_namespaceObject.z.string().optional().describe('Full WebDriverAgent API base URL, including gateway path prefix'),
         wdaHost: core_namespaceObject.z.string().optional().describe('WebDriverAgent host, defaults to localhost'),
         wdaPort: core_namespaceObject.z.number().optional().describe('WebDriverAgent port'),
         sessionId: core_namespaceObject.z.string().optional().describe('Existing WebDriverAgent session ID to reuse'),
@@ -1974,6 +1979,10 @@ ScreenSize: ${size.width}x${size.height} (DPR: ${size.scale})
         ...agent_behavior_init_args_namespaceObject.agentBehaviorInitArgShape
     };
     function getTargetIdentity(initArgs) {
+        if (initArgs?.wdaBaseUrl) {
+            const fingerprint = (0, external_node_crypto_namespaceObject.createHash)('sha256').update(`${initArgs.wdaBaseUrl}\0${initArgs.sessionId ?? ''}`).digest('hex').slice(0, 12);
+            return `wda-${fingerprint}`;
+        }
         if (initArgs?.wdaHost || initArgs?.wdaPort || initArgs?.sessionId) {
             const wdaHost = initArgs.wdaHost ?? 'localhost';
             const wdaPort = initArgs.wdaPort ?? 'default';
@@ -2000,7 +2009,7 @@ ScreenSize: ${size.width}x${size.height} (DPR: ${size.scale})
                 this.agent = void 0;
             }
             if (this.agent) return this.agent;
-            agent_tools_debug('Creating iOS agent with WebDriverAgent options:', opts || {});
+            agent_tools_debug('Creating iOS agent with WebDriverAgent options');
             const reportOptions = this.readCliReportAgentOptions();
             this.agent = await agentFromWebDriverAgent({
                 autoDismissKeyboard: false,
@@ -2166,6 +2175,13 @@ ScreenSize: ${size.width}x${size.height} (DPR: ${size.scale})
                                 defaultValue: constants_namespaceObject.DEFAULT_WDA_PORT,
                                 placeholder: constants_namespaceObject.DEFAULT_WDA_PORT.toString()
                             },
+                            {
+                                key: 'baseUrl',
+                                label: 'WebDriverAgent base URL (optional)',
+                                type: 'text',
+                                required: false,
+                                placeholder: 'https://gateway.example/device/wda'
+                            },
                             {
                                 key: 'sessionId',
                                 label: 'WebDriverAgent session ID',
@@ -2177,21 +2193,26 @@ ScreenSize: ${size.width}x${size.height} (DPR: ${size.scale})
                     };
                 },
                 async createSession (input) {
+                    const baseUrl = 'string' == typeof input?.baseUrl && input.baseUrl.trim() ? (0, webdriver_namespaceObject.normalizeWebDriverBaseUrl)(input.baseUrl.trim()) : void 0;
                     const host = 'string' == typeof input?.host && input.host.trim() ? input.host.trim().replace(/^https?:\/\//, '') : 'localhost';
-                    const port = 'number' == typeof input?.port ? input.port : Number.parseInt(String(input?.port ?? constants_namespaceObject.DEFAULT_WDA_PORT), 10);
+                    const port = baseUrl ? constants_namespaceObject.DEFAULT_WDA_PORT : 'number' == typeof input?.port ? input.port : Number.parseInt(String(input?.port ?? constants_namespaceObject.DEFAULT_WDA_PORT), 10);
                     if (Number.isNaN(port) || port < 1 || port > 65535) throw new Error(`Invalid WebDriverAgent port: ${String(input?.port)}`);
                     const sessionId = 'string' == typeof input?.sessionId && input.sessionId.trim() ? input.sessionId.trim() : void 0;
                     const connectAgent = async ()=>agentFromWebDriverAgent({
                             ...options?.getAgentOptions?.(),
                             wdaHost: host,
                             wdaPort: port,
+                            ...baseUrl ? {
+                                wdaBaseUrl: baseUrl
+                            } : {},
                             ...sessionId ? {
                                 sessionId
                             } : {}
                         });
                     const agent = await connectAgent();
                     const deviceInfo = await agent.interface.getConnectedDeviceInfo?.();
-                    const displayName = deviceInfo ? `${deviceInfo.name} (${deviceInfo.model})` : `${host}:${port}`;
+                    const gatewayUrl = baseUrl ? new URL(baseUrl) : void 0;
+                    const displayName = deviceInfo ? `${deviceInfo.name} (${deviceInfo.model})` : gatewayUrl ? `${gatewayUrl.host} (WDA gateway)` : `${host}:${port}`;
                     return {
                         agent,
                         agentFactory: connectAgent,
@@ -2200,8 +2221,8 @@ ScreenSize: ${size.width}x${size.height} (DPR: ${size.scale})
                         }),
                         displayName,
                         metadata: {
-                            wdaHost: host,
-                            wdaPort: port,
+                            wdaHost: gatewayUrl?.hostname ?? host,
+                            wdaPort: gatewayUrl ? Number(gatewayUrl.port || ('https:' === gatewayUrl.protocol ? 443 : 80)) : port,
                             ...sessionId ? {
                                 sessionId
                             } : {},

package/dist/types/index.d.ts

@@ -221,7 +221,7 @@ export declare class IOSDevice implements AbstractInterface {
     destroy(): Promise<void>;
 }
 
-declare type IOSInitArgs = AgentBehaviorInitArgs & Pick<IOSDeviceOpt, 'wdaHost' | 'wdaPort' | 'sessionId' | 'wdaMjpegPort' | 'wdaMjpegFrameSource'>;
+declare type IOSInitArgs = AgentBehaviorInitArgs & Pick<IOSDeviceOpt, 'wdaBaseUrl' | 'wdaHost' | 'wdaPort' | 'sessionId' | 'wdaMjpegPort' | 'wdaMjpegFrameSource'>;
 
 /**
  * iOS-specific tools manager

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@midscene/ios",
-  "version": "1.13.3",
+  "version": "1.13.4-beta-20260924030824.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/web-infra-dev/midscene.git",
@@ -49,10 +49,10 @@
     "@inquirer/prompts": "^7.8.6",
     "open": "10.1.0",
     "zod": "^3.25.1",
-    "@midscene/shared": "1.13.3",
-    "@midscene/core": "1.13.3",
-    "@midscene/playground": "1.13.3",
-    "@midscene/webdriver": "1.13.3"
+    "@midscene/core": "1.13.4-beta-20260924030824.0",
+    "@midscene/webdriver": "1.13.4-beta-20260924030824.0",
+    "@midscene/shared": "1.13.4-beta-20260924030824.0",
+    "@midscene/playground": "1.13.4-beta-20260924030824.0"
   },
   "devDependencies": {
     "@rslib/core": "^0.18.3",

package/static/index.html

@@ -1 +1 @@
-<!doctype html><html><head><link rel="icon" href="/favicon.ico"><title>Midscene Playground</title><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><script defer src="/static/js/lib-react.8bb5dc6e.js"></script><script defer src="/static/js/652.6a7cf351.js"></script><script defer src="/static/js/index.0723f7fd.js"></script><link href="/static/css/index.67caac18.css" rel="stylesheet"></head><body><div id="root"></div></body></html>
+<!doctype html><html><head><link rel="icon" href="/favicon.ico"><title>Midscene Playground</title><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><script defer src="/static/js/lib-react.8bb5dc6e.js"></script><script defer src="/static/js/652.6a7cf351.js"></script><script defer src="/static/js/index.e149e49f.js"></script><link href="/static/css/index.67caac18.css" rel="stylesheet"></head><body><div id="root"></div></body></html>