@midscene/ios 1.13.3 → 1.13.4-beta-20260924033639.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 = {
@@ -976,6 +976,9 @@ class MjpegFrameSource {
         this.nowFn = nowFn;
     }
 }
+function assertWdaConnectionOptions(options) {
+    if (options?.wdaBaseUrl !== void 0 && (void 0 !== options.wdaHost || void 0 !== options.wdaPort)) throw new Error('wdaBaseUrl cannot be used with wdaHost or wdaPort. Choose one WDA connection method.');
+}
 function device_define_property(obj, key, value) {
     if (key in obj) Object.defineProperty(obj, key, {
         value: value,
@@ -1644,6 +1647,7 @@ ScreenSize: ${size.width}x${size.height} (DPR: ${size.scale})
                 scroll: (param)=>this.performActionScroll(param)
             }
         });
+        assertWdaConnectionOptions(options);
         this.deviceId = 'pending-connection';
         this.options = options;
         this.customActions = options?.customActions;
@@ -1653,11 +1657,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();
     }
@@ -1866,6 +1873,7 @@ class IOSAgent extends Agent {
     }
 }
 async function agentFromWebDriverAgent(opts) {
+    assertWdaConnectionOptions(opts);
     debugAgent('Creating iOS agent with WebDriverAgent');
     const overrideModule = opts?.iOSDeviceClassOverride?.trim() || process.env[MIDSCENE_IOS_DEVICE_CLASS_OVERRIDE]?.trim();
     let DeviceClass = IOSDevice;
@@ -1910,7 +1918,7 @@ const iosPlaygroundPlatform = definePlaygroundPlatform({
                 const wdaReady = await probeWdaReady('localhost', DEFAULT_WDA_PORT);
                 return {
                     title: 'Connect WebDriverAgent',
-                    description: 'Provide the WebDriverAgent host and port that are already running for your selected iPhone or simulator.',
+                    description: 'Provide a WebDriverAgent base URL, or the host and port for your selected iPhone or simulator.',
                     primaryActionLabel: 'Create Agent',
                     autoSubmitWhenReady: wdaReady,
                     fields: [
@@ -1918,18 +1926,23 @@ const iosPlaygroundPlatform = definePlaygroundPlatform({
                             key: 'host',
                             label: 'WebDriverAgent host',
                             type: 'text',
-                            required: true,
-                            defaultValue: 'localhost',
+                            required: false,
                             placeholder: 'localhost'
                         },
                         {
                             key: 'port',
                             label: 'WebDriverAgent port',
                             type: 'number',
-                            required: true,
-                            defaultValue: DEFAULT_WDA_PORT,
+                            required: false,
                             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 +1954,44 @@ const iosPlaygroundPlatform = definePlaygroundPlatform({
                 };
             },
             async createSession (input) {
+                const baseUrl = 'string' == typeof input?.baseUrl && input.baseUrl.trim() ? normalizeWebDriverBaseUrl(input.baseUrl.trim()) : void 0;
+                const hasHostInput = input?.host !== void 0 && '' !== String(input.host).trim();
+                const hasPortInput = input?.port !== void 0 && '' !== String(input.port).trim();
+                assertWdaConnectionOptions({
+                    ...baseUrl ? {
+                        wdaBaseUrl: baseUrl
+                    } : {},
+                    ...hasHostInput ? {
+                        wdaHost: String(input?.host)
+                    } : {},
+                    ...hasPortInput ? {
+                        wdaPort: Number(input?.port)
+                    } : {}
+                });
                 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 = hasPortInput ? 'number' == typeof input?.port ? input.port : Number.parseInt(String(input?.port), 10) : DEFAULT_WDA_PORT;
                 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({
+                const connectAgent = async ()=>{
+                    const agentOptions = {
                         ...options?.getAgentOptions?.(),
-                        wdaHost: host,
-                        wdaPort: port,
+                        ...baseUrl ? {
+                            wdaBaseUrl: baseUrl
+                        } : {
+                            wdaHost: host,
+                            wdaPort: port
+                        },
                         ...sessionId ? {
                             sessionId
                         } : {}
-                    });
+                    };
+                    assertWdaConnectionOptions(agentOptions);
+                    return agentFromWebDriverAgent(agentOptions);
+                };
                 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 +2000,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";
@@ -976,6 +977,9 @@ class MjpegFrameSource {
         this.nowFn = nowFn;
     }
 }
+function assertWdaConnectionOptions(options) {
+    if (options?.wdaBaseUrl !== void 0 && (void 0 !== options.wdaHost || void 0 !== options.wdaPort)) throw new Error('wdaBaseUrl cannot be used with wdaHost or wdaPort. Choose one WDA connection method.');
+}
 function device_define_property(obj, key, value) {
     if (key in obj) Object.defineProperty(obj, key, {
         value: value,
@@ -1644,6 +1648,7 @@ ScreenSize: ${size.width}x${size.height} (DPR: ${size.scale})
                 scroll: (param)=>this.performActionScroll(param)
             }
         });
+        assertWdaConnectionOptions(options);
         this.deviceId = 'pending-connection';
         this.options = options;
         this.customActions = options?.customActions;
@@ -1653,11 +1658,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();
     }
@@ -1866,6 +1874,7 @@ class IOSAgent extends Agent {
     }
 }
 async function agentFromWebDriverAgent(opts) {
+    assertWdaConnectionOptions(opts);
     debugAgent('Creating iOS agent with WebDriverAgent');
     const overrideModule = opts?.iOSDeviceClassOverride?.trim() || process.env[MIDSCENE_IOS_DEVICE_CLASS_OVERRIDE]?.trim();
     let DeviceClass = IOSDevice;
@@ -1893,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'),
@@ -1903,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';
@@ -1919,6 +1933,7 @@ class IOSMidsceneTools extends BaseMidsceneTools {
         return new IOSDevice({});
     }
     async ensureAgent(opts) {
+        assertWdaConnectionOptions(opts);
         const nextSignature = getAgentInitArgsSignature(opts);
         if (this.agent && shouldRebuildAgentForInitArgs(this.lastOptsSignature, nextSignature)) {
             try {
@@ -1929,7 +1944,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,
@@ -1948,6 +1963,7 @@ class IOSMidsceneTools extends BaseMidsceneTools {
                 cli: this.getAgentInitArgCliMetadata(),
                 handler: async (args)=>{
                     const initArgs = this.extractAgentInitParam(args);
+                    assertWdaConnectionOptions(initArgs);
                     const identity = getTargetIdentity(initArgs);
                     const reportSession = this.createNewCliReportSession(identity);
                     this.commitCliReportSession(reportSession);
@@ -1996,7 +2012,7 @@ class IOSMidsceneTools extends BaseMidsceneTools {
 const tools = new IOSMidsceneTools();
 runToolsCLI(tools, 'midscene-ios', {
     stripPrefix: 'ios_',
-    version: "1.13.3",
+    version: "1.13.4-beta-20260924033639.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";
@@ -797,6 +798,9 @@ class MjpegFrameSource {
         this.nowFn = nowFn;
     }
 }
+function assertWdaConnectionOptions(options) {
+    if (options?.wdaBaseUrl !== void 0 && (void 0 !== options.wdaHost || void 0 !== options.wdaPort)) throw new Error('wdaBaseUrl cannot be used with wdaHost or wdaPort. Choose one WDA connection method.');
+}
 function device_define_property(obj, key, value) {
     if (key in obj) Object.defineProperty(obj, key, {
         value: value,
@@ -1465,6 +1469,7 @@ ScreenSize: ${size.width}x${size.height} (DPR: ${size.scale})
                 scroll: (param)=>this.performActionScroll(param)
             }
         });
+        assertWdaConnectionOptions(options);
         this.deviceId = 'pending-connection';
         this.options = options;
         this.customActions = options?.customActions;
@@ -1474,11 +1479,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();
     }
@@ -1871,6 +1879,7 @@ class IOSAgent extends Agent {
     }
 }
 async function agentFromWebDriverAgent(opts) {
+    assertWdaConnectionOptions(opts);
     debugAgent('Creating iOS agent with WebDriverAgent');
     const overrideModule = opts?.iOSDeviceClassOverride?.trim() || process.env[MIDSCENE_IOS_DEVICE_CLASS_OVERRIDE]?.trim();
     let DeviceClass = IOSDevice;
@@ -1898,6 +1907,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 +1918,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';
@@ -1924,6 +1938,7 @@ class IOSMidsceneTools extends BaseMidsceneTools {
         return new IOSDevice({});
     }
     async ensureAgent(opts) {
+        assertWdaConnectionOptions(opts);
         const nextSignature = getAgentInitArgsSignature(opts);
         if (this.agent && shouldRebuildAgentForInitArgs(this.lastOptsSignature, nextSignature)) {
             try {
@@ -1934,7 +1949,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,
@@ -1953,6 +1968,7 @@ class IOSMidsceneTools extends BaseMidsceneTools {
                 cli: this.getAgentInitArgCliMetadata(),
                 handler: async (args)=>{
                     const initArgs = this.extractAgentInitParam(args);
+                    assertWdaConnectionOptions(initArgs);
                     const identity = getTargetIdentity(initArgs);
                     const reportSession = this.createNewCliReportSession(identity);
                     this.commitCliReportSession(reportSession);
@@ -2073,7 +2089,7 @@ const iosPlaygroundPlatform = definePlaygroundPlatform({
                 const wdaReady = await probeWdaReady('localhost', DEFAULT_WDA_PORT);
                 return {
                     title: 'Connect WebDriverAgent',
-                    description: 'Provide the WebDriverAgent host and port that are already running for your selected iPhone or simulator.',
+                    description: 'Provide a WebDriverAgent base URL, or the host and port for your selected iPhone or simulator.',
                     primaryActionLabel: 'Create Agent',
                     autoSubmitWhenReady: wdaReady,
                     fields: [
@@ -2081,18 +2097,23 @@ const iosPlaygroundPlatform = definePlaygroundPlatform({
                             key: 'host',
                             label: 'WebDriverAgent host',
                             type: 'text',
-                            required: true,
-                            defaultValue: 'localhost',
+                            required: false,
                             placeholder: 'localhost'
                         },
                         {
                             key: 'port',
                             label: 'WebDriverAgent port',
                             type: 'number',
-                            required: true,
-                            defaultValue: DEFAULT_WDA_PORT,
+                            required: false,
                             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 +2125,44 @@ const iosPlaygroundPlatform = definePlaygroundPlatform({
                 };
             },
             async createSession (input) {
+                const baseUrl = 'string' == typeof input?.baseUrl && input.baseUrl.trim() ? normalizeWebDriverBaseUrl(input.baseUrl.trim()) : void 0;
+                const hasHostInput = input?.host !== void 0 && '' !== String(input.host).trim();
+                const hasPortInput = input?.port !== void 0 && '' !== String(input.port).trim();
+                assertWdaConnectionOptions({
+                    ...baseUrl ? {
+                        wdaBaseUrl: baseUrl
+                    } : {},
+                    ...hasHostInput ? {
+                        wdaHost: String(input?.host)
+                    } : {},
+                    ...hasPortInput ? {
+                        wdaPort: Number(input?.port)
+                    } : {}
+                });
                 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 = hasPortInput ? 'number' == typeof input?.port ? input.port : Number.parseInt(String(input?.port), 10) : DEFAULT_WDA_PORT;
                 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({
+                const connectAgent = async ()=>{
+                    const agentOptions = {
                         ...options?.getAgentOptions?.(),
-                        wdaHost: host,
-                        wdaPort: port,
+                        ...baseUrl ? {
+                            wdaBaseUrl: baseUrl
+                        } : {
+                            wdaHost: host,
+                            wdaPort: port
+                        },
                         ...sessionId ? {
                             sessionId
                         } : {}
-                    });
+                    };
+                    assertWdaConnectionOptions(agentOptions);
+                    return agentFromWebDriverAgent(agentOptions);
+                };
                 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 +2171,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,
@@ -1114,6 +1114,9 @@ var __webpack_exports__ = {};
             this.nowFn = nowFn;
         }
     }
+    function assertWdaConnectionOptions(options) {
+        if (options?.wdaBaseUrl !== void 0 && (void 0 !== options.wdaHost || void 0 !== options.wdaPort)) throw new Error('wdaBaseUrl cannot be used with wdaHost or wdaPort. Choose one WDA connection method.');
+    }
     function device_define_property(obj, key, value) {
         if (key in obj) Object.defineProperty(obj, key, {
             value: value,
@@ -1782,6 +1785,7 @@ ScreenSize: ${size.width}x${size.height} (DPR: ${size.scale})
                     scroll: (param)=>this.performActionScroll(param)
                 }
             });
+            assertWdaConnectionOptions(options);
             this.deviceId = 'pending-connection';
             this.options = options;
             this.customActions = options?.customActions;
@@ -1791,11 +1795,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();
         }
@@ -1909,6 +1916,7 @@ ScreenSize: ${size.width}x${size.height} (DPR: ${size.scale})
         }
     }
     async function agentFromWebDriverAgent(opts) {
+        assertWdaConnectionOptions(opts);
         debugAgent('Creating iOS agent with WebDriverAgent');
         const overrideModule = opts?.iOSDeviceClassOverride?.trim() || process.env[env_namespaceObject.MIDSCENE_IOS_DEVICE_CLASS_OVERRIDE]?.trim();
         let DeviceClass = IOSDevice;
@@ -1953,7 +1961,7 @@ ScreenSize: ${size.width}x${size.height} (DPR: ${size.scale})
                     const wdaReady = await probeWdaReady('localhost', constants_namespaceObject.DEFAULT_WDA_PORT);
                     return {
                         title: 'Connect WebDriverAgent',
-                        description: 'Provide the WebDriverAgent host and port that are already running for your selected iPhone or simulator.',
+                        description: 'Provide a WebDriverAgent base URL, or the host and port for your selected iPhone or simulator.',
                         primaryActionLabel: 'Create Agent',
                         autoSubmitWhenReady: wdaReady,
                         fields: [
@@ -1961,18 +1969,23 @@ ScreenSize: ${size.width}x${size.height} (DPR: ${size.scale})
                                 key: 'host',
                                 label: 'WebDriverAgent host',
                                 type: 'text',
-                                required: true,
-                                defaultValue: 'localhost',
+                                required: false,
                                 placeholder: 'localhost'
                             },
                             {
                                 key: 'port',
                                 label: 'WebDriverAgent port',
                                 type: 'number',
-                                required: true,
-                                defaultValue: constants_namespaceObject.DEFAULT_WDA_PORT,
+                                required: false,
                                 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 +1997,44 @@ 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 hasHostInput = input?.host !== void 0 && '' !== String(input.host).trim();
+                    const hasPortInput = input?.port !== void 0 && '' !== String(input.port).trim();
+                    assertWdaConnectionOptions({
+                        ...baseUrl ? {
+                            wdaBaseUrl: baseUrl
+                        } : {},
+                        ...hasHostInput ? {
+                            wdaHost: String(input?.host)
+                        } : {},
+                        ...hasPortInput ? {
+                            wdaPort: Number(input?.port)
+                        } : {}
+                    });
                     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 = hasPortInput ? 'number' == typeof input?.port ? input.port : Number.parseInt(String(input?.port), 10) : constants_namespaceObject.DEFAULT_WDA_PORT;
                     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({
+                    const connectAgent = async ()=>{
+                        const agentOptions = {
                             ...options?.getAgentOptions?.(),
-                            wdaHost: host,
-                            wdaPort: port,
+                            ...baseUrl ? {
+                                wdaBaseUrl: baseUrl
+                            } : {
+                                wdaHost: host,
+                                wdaPort: port
+                            },
                             ...sessionId ? {
                                 sessionId
                             } : {}
-                        });
+                        };
+                        assertWdaConnectionOptions(agentOptions);
+                        return agentFromWebDriverAgent(agentOptions);
+                    };
                     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 +2043,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
                             } : {},