appium-xcuitest-driver 10.12.1 → 10.13.0

package/build/lib/commands/web.js

@@ -74,6 +74,7 @@ const support_1 = require("appium/support");
 const asyncbox_1 = require("asyncbox");
 const bluebird_1 = __importStar(require("bluebird"));
 const lodash_1 = __importDefault(require("lodash"));
+const utils_1 = require("../utils");
 const IPHONE_TOP_BAR_HEIGHT = 71;
 const IPHONE_SCROLLED_TOP_BAR_HEIGHT = 41;
 const IPHONE_X_SCROLLED_OFFSET = 55;
@@ -113,10 +114,12 @@ const TAB_BAR_POSITION_TOP = 'top';
 const TAB_BAR_POSITION_BOTTOM = 'bottom';
 const TAB_BAR_POSSITIONS = [TAB_BAR_POSITION_TOP, TAB_BAR_POSITION_BOTTOM];
 /**
- * @this {XCUITestDriver}
+ * Sets the current web frame context.
+ *
+ * @param frame - Frame identifier (number, string, or null to return to default content)
  * @group Mobile Web Only
- * @param {number|string|null} frame
- * @returns {Promise<void>}
+ * @throws {errors.NotImplementedError} If not in a web context
+ * @throws {errors.NoSuchFrameError} If the specified frame is not found
  */
 async function setFrame(frame) {
     if (!this.isWebContext()) {
@@ -144,11 +147,12 @@ async function setFrame(frame) {
     }
 }
 /**
- * @this {XCUITestDriver}
+ * Gets the value of a CSS property for an element.
+ *
+ * @param propertyName - Name of the CSS property
+ * @param el - Element to get the property from
  * @group Mobile Web Only
- * @param {string} propertyName
- * @param {Element | string} el
- * @returns {Promise<string>}
+ * @throws {errors.NotImplementedError} If not in a web context
  */
 async function getCssProperty(propertyName, el) {
     if (!this.isWebContext()) {
@@ -158,11 +162,11 @@ async function getCssProperty(propertyName, el) {
     return await this.executeAtom('get_value_of_css_property', [atomsElement, propertyName]);
 }
 /**
- * Submit the form an element is in
+ * Submits the form that contains the specified element.
  *
- * @param {string|Element} el - the element ID
+ * @param el - The element ID or element object
  * @group Mobile Web Only
- * @this {XCUITestDriver}
+ * @throws {errors.NotImplementedError} If not in a web context
  */
 async function submit(el) {
     if (!this.isWebContext()) {
@@ -172,48 +176,55 @@ async function submit(el) {
     await this.executeAtom('submit', [atomsElement]);
 }
 /**
- * @this {XCUITestDriver}
+ * Refreshes the current page.
+ *
  * @group Mobile Web Only
+ * @throws {errors.NotImplementedError} If not in a web context
  */
 async function refresh() {
     if (!this.isWebContext()) {
         throw new driver_1.errors.NotImplementedError();
     }
-    await ( /** @type {RemoteDebugger} */(this.remote)).execute('window.location.reload()');
+    await this.remote.execute('window.location.reload()');
 }
 /**
- * @this {XCUITestDriver}
+ * Gets the current page URL.
+ *
  * @group Mobile Web Only
- * @returns {Promise<string>}
+ * @throws {errors.NotImplementedError} If not in a web context
  */
 async function getUrl() {
     if (!this.isWebContext()) {
         throw new driver_1.errors.NotImplementedError();
     }
-    return await ( /** @type {RemoteDebugger} */(this.remote)).execute('window.location.href');
+    return await this.remote.execute('window.location.href');
 }
 /**
- * @this {XCUITestDriver}
+ * Gets the current page title.
+ *
  * @group Mobile Web Only
- * @returns {Promise<string>}
+ * @throws {errors.NotImplementedError} If not in a web context
  */
 async function title() {
     if (!this.isWebContext()) {
         throw new driver_1.errors.NotImplementedError();
     }
-    return await ( /** @type {RemoteDebugger} */(this.remote)).execute('window.document.title');
+    return await this.remote.execute('window.document.title');
 }
 /**
- * @this {XCUITestDriver}
+ * Gets all cookies for the current page.
+ *
+ * Cookie values are automatically URI-decoded.
+ *
  * @group Mobile Web Only
- * @returns {Promise<import('@appium/types').Cookie[]>}
+ * @throws {errors.NotImplementedError} If not in a web context
  */
 async function getCookies() {
     if (!this.isWebContext()) {
         throw new driver_1.errors.NotImplementedError();
     }
     // get the cookies from the remote debugger, or an empty object
-    const { cookies } = await ( /** @type {RemoteDebugger} */(this.remote)).getCookies();
+    const { cookies } = await this.remote.getCookies();
     // the value is URI encoded, so decode it safely
     return cookies.map((cookie) => {
         if (!lodash_1.default.isEmpty(cookie.value)) {
@@ -230,10 +241,13 @@ async function getCookies() {
     });
 }
 /**
- * @this {XCUITestDriver}
+ * Sets a cookie for the current page.
+ *
+ * If the cookie's path is not specified, it defaults to '/'.
+ *
+ * @param cookie - Cookie object to set
  * @group Mobile Web Only
- * @param {import('@appium/types').Cookie} cookie
- * @returns {Promise<void>}
+ * @throws {errors.NotImplementedError} If not in a web context
  */
 async function setCookie(cookie) {
     if (!this.isWebContext()) {
@@ -257,10 +271,13 @@ async function setCookie(cookie) {
     await this.executeAtom('execute_script', [script, []]);
 }
 /**
- * @this {XCUITestDriver}
- * @param {string} cookieName
- * @returns {Promise<void>}
+ * Deletes a cookie by name.
+ *
+ * If the cookie is not found, the operation is silently ignored.
+ *
+ * @param cookieName - Name of the cookie to delete
  * @group Mobile Web Only
+ * @throws {errors.NotImplementedError} If not in a web context
  */
 async function deleteCookie(cookieName) {
     if (!this.isWebContext()) {
@@ -275,9 +292,10 @@ async function deleteCookie(cookieName) {
     await _deleteCookie.bind(this)(cookie);
 }
 /**
- * @this {XCUITestDriver}
+ * Deletes all cookies for the current page.
+ *
  * @group Mobile Web Only
- * @returns {Promise<void>}
+ * @throws {errors.NotImplementedError} If not in a web context
  */
 async function deleteCookies() {
     if (!this.isWebContext()) {
@@ -287,9 +305,10 @@ async function deleteCookies() {
     await bluebird_1.default.all(cookies.map((cookie) => _deleteCookie.bind(this)(cookie)));
 }
 /**
- * @this {XCUITestDriver}
- * @param {Element | string} el
- * @returns {Element | string}
+ * Caches a web element for later use.
+ *
+ * @param el - Element to cache
+ * @returns The cached element wrapper
  */
 function cacheWebElement(el) {
     if (!lodash_1.default.isPlainObject(el)) {
@@ -306,17 +325,18 @@ function cacheWebElement(el) {
     return support_1.util.wrapElement(cacheId);
 }
 /**
- * @this {XCUITestDriver}
- * @param {any} response
- * @returns {any}
+ * Recursively caches all web elements in a response object.
+ *
+ * @param response - Response object that may contain web elements
+ * @returns Response with cached element wrappers
  */
 function cacheWebElements(response) {
-    const toCached = (/** @type {any} */ v) => (lodash_1.default.isArray(v) || lodash_1.default.isPlainObject(v)) ? this.cacheWebElements(v) : v;
+    const toCached = (v) => (lodash_1.default.isArray(v) || lodash_1.default.isPlainObject(v)) ? this.cacheWebElements(v) : v;
     if (lodash_1.default.isArray(response)) {
         return response.map(toCached);
     }
     else if (lodash_1.default.isPlainObject(response)) {
-        const result = { ...response, ...( /** @type {Element} */(this.cacheWebElement(response))) };
+        const result = { ...response, ...this.cacheWebElement(response) };
         return lodash_1.default.toPairs(result).reduce((acc, [key, value]) => {
             acc[key] = toCached(value);
             return acc;
@@ -325,35 +345,39 @@ function cacheWebElements(response) {
     return response;
 }
 /**
- * @param {string} atom
- * @param {unknown[]} args
- * @returns {Promise<any>}
+ * Executes a Selenium atom script in the current web context.
+ *
+ * @param atom - Name of the atom to execute
+ * @param args - Arguments to pass to the atom
+ * @param alwaysDefaultFrame - If true, always use the default frame instead of current frames
  * @privateRemarks This should return `Promise<T>` where `T` extends `unknown`, but that's going to cause a lot of things to break.
- * @this {XCUITestDriver}
  */
 async function executeAtom(atom, args, alwaysDefaultFrame = false) {
-    let frames = alwaysDefaultFrame === true ? [] : this.curWebFrames;
-    let promise = ( /** @type {RemoteDebugger} */(this.remote)).executeAtom(atom, args, frames);
+    const frames = alwaysDefaultFrame === true ? [] : this.curWebFrames;
+    const promise = this.remote.executeAtom(atom, args, frames);
     return await this.waitForAtom(promise);
 }
 /**
- * @this {XCUITestDriver}
- * @param {string} atom
- * @param {any[]} args
+ * Executes a Selenium atom script asynchronously.
+ *
+ * @param atom - Name of the atom to execute
+ * @param args - Arguments to pass to the atom
  */
 async function executeAtomAsync(atom, args) {
     // save the resolve and reject methods of the promise to be waited for
-    let promise = new bluebird_1.default((resolve, reject) => {
+    const promise = new bluebird_1.default((resolve, reject) => {
         this.asyncPromise = { resolve, reject };
     });
-    await ( /** @type {RemoteDebugger} */(this.remote)).executeAtomAsync(atom, args, this.curWebFrames);
+    await this.remote.executeAtomAsync(atom, args, this.curWebFrames);
     return await this.waitForAtom(promise);
 }
 /**
- * @template {string} S
- * @param {S|Element<S>} elOrId
- * @returns {import('./types').AtomsElement<S>}
- * @this {XCUITestDriver}
+ * Gets the atoms-compatible element representation.
+ *
+ * @template S - Element identifier type
+ * @param elOrId - Element or element ID
+ * @returns Atoms-compatible element object
+ * @throws {errors.StaleElementReferenceError} If the element is not in the cache
  */
 function getAtomsElement(elOrId) {
     const elId = support_1.util.unwrapElement(elOrId);
@@ -363,8 +387,10 @@ function getAtomsElement(elOrId) {
     return { ELEMENT: this.webElementsCache.get(elId) };
 }
 /**
- * @param {readonly any[]} [args]
- * @this {XCUITestDriver}
+ * Converts elements in an argument array to atoms-compatible format.
+ *
+ * @param args - Array of arguments that may contain elements
+ * @returns Array with elements converted to atoms format
  */
 function convertElementsForAtoms(args = []) {
     return args.map((arg) => {
@@ -383,28 +409,33 @@ function convertElementsForAtoms(args = []) {
     });
 }
 /**
+ * Extracts the element ID from an element object.
  *
- * @param {any} element
- * @returns {string | undefined}
+ * @param element - Element object
+ * @returns Element ID if found, undefined otherwise
  */
 function getElementId(element) {
     return element?.ELEMENT || element?.[W3C_WEB_ELEMENT_IDENTIFIER];
 }
 /**
- * @param {any} element
- * @returns {element is Element}
+ * Checks if an object has an element ID (type guard).
+ *
+ * @param element - Object to check
+ * @returns True if the object has an element ID
  */
 function hasElementId(element) {
     return (support_1.util.hasValue(element) &&
         (support_1.util.hasValue(element.ELEMENT) || support_1.util.hasValue(element[W3C_WEB_ELEMENT_IDENTIFIER])));
 }
 /**
- * @this {XCUITestDriver}
- * @param {string} strategy
- * @param {string} selector
- * @param {boolean} [many]
- * @param {Element | string | null} [ctx]
- * @returns {Promise<Element | Element[]>}
+ * Finds one or more web elements using the specified strategy.
+ *
+ * @param strategy - Locator strategy (e.g., 'id', 'css selector')
+ * @param selector - Selector value
+ * @param many - If true, returns array of elements; if false, returns single element
+ * @param ctx - Optional context element to search within
+ * @returns Element or array of elements
+ * @throws {errors.NoSuchElementError} If element not found and many is false
  */
 async function findWebElementOrElements(strategy, selector, many, ctx) {
     const contextElement = lodash_1.default.isNil(ctx) ? null : this.getAtomsElement(ctx);
@@ -435,24 +466,30 @@ async function findWebElementOrElements(strategy, selector, many, ctx) {
     return this.cacheWebElements(element);
 }
 /**
- * @this {XCUITestDriver}
- * @param {number} x
- * @param {number} y
+ * Clicks at the specified web coordinates.
+ *
+ * Coordinates are automatically translated from web to native coordinates.
+ *
+ * @param x - X coordinate in web space
+ * @param y - Y coordinate in web space
  */
 async function clickWebCoords(x, y) {
     const { x: translatedX, y: translatedY } = await this.translateWebCoords(x, y);
     await this.mobileTap(translatedX, translatedY);
 }
 /**
- * @this {XCUITestDriver}
- * @returns {Promise<boolean>}
+ * Determines if the current Safari session is running on an iPhone.
+ *
+ * The result is cached after the first call.
+ *
+ * @returns True if running on iPhone, false otherwise
  */
 async function getSafariIsIphone() {
     if (lodash_1.default.isBoolean(this._isSafariIphone)) {
         return this._isSafariIphone;
     }
     try {
-        const userAgent = /** @type {string} */ (await this.execute('return navigator.userAgent'));
+        const userAgent = await this.execute('return navigator.userAgent');
         this._isSafariIphone = userAgent.toLowerCase().includes('iphone');
     }
     catch (err) {
@@ -462,12 +499,15 @@ async function getSafariIsIphone() {
     return this._isSafariIphone ?? true;
 }
 /**
- * @this {XCUITestDriver}
- * @returns {Promise<import('@appium/types').Size>}
+ * Gets the device size from Safari's perspective.
+ *
+ * Returns normalized dimensions (width <= height).
+ *
+ * @returns Device size with width and height
  */
 async function getSafariDeviceSize() {
     const script = 'return {height: window.screen.availHeight * window.devicePixelRatio, width: window.screen.availWidth * window.devicePixelRatio};';
-    const { width, height } = /** @type {import('@appium/types').Size} */ (await this.execute(script));
+    const { width, height } = await this.execute(script);
     const [normHeight, normWidth] = height > width ? [height, width] : [width, height];
     return {
         width: normWidth,
@@ -475,8 +515,11 @@ async function getSafariDeviceSize() {
     };
 }
 /**
- * @this {XCUITestDriver}
- * @returns {Promise<boolean>}
+ * Determines if the current device has a notch (iPhone X and later).
+ *
+ * The result is cached after the first call.
+ *
+ * @returns True if device has a notch, false otherwise
  */
 async function getSafariIsNotched() {
     if (lodash_1.default.isBoolean(this._isSafariNotched)) {
@@ -497,7 +540,14 @@ async function getSafariIsNotched() {
     return this._isSafariNotched ?? false;
 }
 /**
- * @this {XCUITestDriver}
+ * Calculates and applies extra offset for web coordinate translation.
+ *
+ * Takes into account Safari UI elements like tab bars, smart app banners, and device notches.
+ * Modifies wvPos and realDims in place.
+ *
+ * @param wvPos - WebView position object (modified in place)
+ * @param realDims - Real dimensions object (modified in place)
+ * @throws {errors.InvalidArgumentError} If Safari tab bar position is invalid
  */
 async function getExtraTranslateWebCoordsOffset(wvPos, realDims) {
     let topOffset = 0;
@@ -505,7 +555,7 @@ async function getExtraTranslateWebCoordsOffset(wvPos, realDims) {
     const isIphone = await this.getSafariIsIphone();
     // No need to check whether the Smart App Banner or Tab Bar is visible or not
     // if already defined by nativeWebTapTabBarVisibility or nativeWebTapSmartAppBannerVisibility in settings.
-    const { nativeWebTapTabBarVisibility, nativeWebTapSmartAppBannerVisibility, safariTabBarPosition = support_1.util.compareVersions(/** @type {string} */ (this.opts.platformVersion), '>=', '15.0') &&
+    const { nativeWebTapTabBarVisibility, nativeWebTapSmartAppBannerVisibility, safariTabBarPosition = support_1.util.compareVersions(this.opts.platformVersion, '>=', '15.0') &&
         isIphone
         ? TAB_BAR_POSITION_BOTTOM
         : TAB_BAR_POSITION_TOP, } = this.settings.getSettings();
@@ -524,7 +574,7 @@ async function getExtraTranslateWebCoordsOffset(wvPos, realDims) {
     const isNotched = isIphone && (await this.getSafariIsNotched());
     const orientation = realDims.h > realDims.w ? 'PORTRAIT' : 'LANDSCAPE';
     const notchOffset = isNotched
-        ? support_1.util.compareVersions(/** @type {string} */ (this.opts.platformVersion), '=', '13.0')
+        ? support_1.util.compareVersions(this.opts.platformVersion, '=', '13.0')
             ? IPHONE_X_NOTCH_OFFSET_IOS_13
             : IPHONE_X_NOTCH_OFFSET_IOS
         : 0;
@@ -573,10 +623,11 @@ async function getExtraTranslateWebCoordsOffset(wvPos, realDims) {
     realDims.h -= topOffset + bottomOffset;
 }
 /**
- * @this {XCUITestDriver}
- * @param {boolean} isIphone
- * @param {string} bannerVisibility
- * @returns {Promise<number>}
+ * Calculates additional offset for native web tap based on smart app banner visibility.
+ *
+ * @param isIphone - Whether the device is an iPhone
+ * @param bannerVisibility - Banner visibility setting ('visible', 'invisible', or 'detect')
+ * @returns Additional offset in pixels
  */
 async function getExtraNativeWebTapOffset(isIphone, bannerVisibility) {
     let offset = 0;
@@ -587,7 +638,7 @@ async function getExtraNativeWebTapOffset(isIphone, bannerVisibility) {
     }
     else if (bannerVisibility === DETECT) {
         // try to see if there is an Smart App Banner
-        const banners = /** @type {import('@appium/types').Element[]} */ (await this.findNativeElementOrElements('accessibility id', 'Close app download offer', true));
+        const banners = await this.findNativeElementOrElements('accessibility id', 'Close app download offer', true);
         if (banners?.length) {
             offset += isIphone
                 ? IPHONE_WEB_COORD_SMART_APP_BANNER_OFFSET
@@ -598,9 +649,11 @@ async function getExtraNativeWebTapOffset(isIphone, bannerVisibility) {
     return offset;
 }
 /**
- * @this {XCUITestDriver}
- * @param {any} el
- * @returns {Promise<void>}
+ * Performs a native tap on a web element.
+ *
+ * Attempts to use a simple native tap first, falling back to coordinate-based tapping if needed.
+ *
+ * @param el - Element to tap
  */
 async function nativeWebTap(el) {
     const atomsElement = this.getAtomsElement(el);
@@ -610,20 +663,23 @@ async function nativeWebTap(el) {
         return;
     }
     this.log.warn('Unable to do simple native web tap. Attempting to convert coordinates');
-    const [size, coordinates] = 
-    /** @type {[import('@appium/types').Size, import('@appium/types').Position]} */ (await bluebird_1.default.Promise.all([
+    const [size, coordinates] = await bluebird_1.default.Promise.all([
         this.executeAtom('get_size', [atomsElement]),
         this.executeAtom('get_top_left_coordinates', [atomsElement]),
-    ]));
+    ]);
     const { width, height } = size;
     const { x, y } = coordinates;
     await this.clickWebCoords(x + width / 2, y + height / 2);
 }
 /**
- * @this {XCUITestDriver}
- * @param {number} x
- * @param {number} y
- * @returns {Promise<import('@appium/types').Position>}
+ * Translates web coordinates to native screen coordinates.
+ *
+ * Uses calibration data if available, otherwise falls back to legacy algorithm.
+ *
+ * @param x - X coordinate in web space
+ * @param y - Y coordinate in web space
+ * @returns Translated position in native coordinates
+ * @throws {Error} If no WebView is found or if translation fails
  */
 async function translateWebCoords(x, y) {
     this.log.debug(`Translating web coordinates (${JSON.stringify({ x, y })}) to native coordinates`);
@@ -632,7 +688,7 @@ async function translateWebCoords(x, y) {
         const { offsetX, offsetY, pixelRatioX, pixelRatioY } = this.webviewCalibrationResult;
         const cmd = '(function () {return {innerWidth: window.innerWidth, innerHeight: window.innerHeight, ' +
             'outerWidth: window.outerWidth, outerHeight: window.outerHeight}; })()';
-        const wvDims = await ( /** @type {RemoteDebugger} */(this.remote)).execute(cmd);
+        const wvDims = await this.remote.execute(cmd);
         // https://tripleodeon.com/2011/12/first-understand-your-screen/
         const shouldApplyPixelRatio = wvDims.innerWidth > wvDims.outerWidth
             || wvDims.innerHeight > wvDims.outerHeight;
@@ -646,21 +702,20 @@ async function translateWebCoords(x, y) {
             `Invoke 'mobile: calibrateWebToRealCoordinatesTranslation' to change that.`);
     }
     // absolutize web coords
-    /** @type {import('@appium/types').Element|undefined|string} */
     let webview;
     try {
-        webview = /** @type {import('@appium/types').Element|undefined} */ (await (0, asyncbox_1.retryInterval)(5, 100, async () => await this.findNativeElementOrElements('class name', 'XCUIElementTypeWebView', false)));
+        webview = await (0, asyncbox_1.retryInterval)(5, 100, async () => await this.findNativeElementOrElements('class name', 'XCUIElementTypeWebView', false));
     }
     catch { }
     if (!webview) {
         throw new Error(`No WebView found. Unable to translate web coordinates for native web tap.`);
     }
     webview = support_1.util.unwrapElement(webview);
-    const rect = /** @type {Rect} */ (await this.proxyCommand(`/element/${webview}/rect`, 'GET'));
+    const rect = await this.proxyCommand(`/element/${webview}/rect`, 'GET');
     const wvPos = { x: rect.x, y: rect.y };
     const realDims = { w: rect.width, h: rect.height };
     const cmd = '(function () { return {w: window.innerWidth, h: window.innerHeight}; })()';
-    const wvDims = await ( /** @type {RemoteDebugger} */(this.remote)).execute(cmd);
+    const wvDims = await this.remote.execute(cmd);
     // keep track of implicit wait, and set locally to 0
     // https://github.com/appium/appium/issues/14988
     const implicitWaitMs = this.implicitWaitMs;
@@ -695,15 +750,20 @@ async function translateWebCoords(x, y) {
     return newCoords;
 }
 /**
- * @this {XCUITestDriver}
- * @returns {Promise<boolean>}
+ * Checks if an alert is currently present.
+ *
+ * @returns True if an alert is present, false otherwise
  */
 async function checkForAlert() {
     return lodash_1.default.isString(await this.getAlertText());
 }
 /**
- * @param {Promise<any>} promise
- * @this {XCUITestDriver}
+ * Waits for an atom promise to resolve, monitoring for alerts during execution.
+ *
+ * @param promise - Promise returned by atom execution
+ * @returns The result of the atom execution
+ * @throws {errors.UnexpectedAlertOpenError} If an alert appears during execution
+ * @throws {errors.TimeoutError} If the atom execution times out
  */
 async function waitForAtom(promise) {
     const timer = new support_1.timing.Timer().start();
@@ -775,21 +835,23 @@ async function waitForAtom(promise) {
     }
 }
 /**
- * @param {string} navType
- * @this {XCUITestDriver}
+ * Performs browser navigation (back, forward, etc.) using history API.
+ *
+ * @param navType - Navigation type (e.g., 'back', 'forward')
  */
 async function mobileWebNav(navType) {
-    ( /** @type {RemoteDebugger} */(this.remote)).allowNavigationWithoutReload = true;
+    this.remote.allowNavigationWithoutReload = true;
     try {
         await this.executeAtom('execute_script', [`history.${navType}();`, null]);
     }
     finally {
-        ( /** @type {RemoteDebugger} */(this.remote)).allowNavigationWithoutReload = false;
+        this.remote.allowNavigationWithoutReload = false;
     }
 }
 /**
- * @this {XCUITestDriver}
- * @returns {string} The base url which could be used to access WDA HTTP endpoints.
+ * Gets the base URL for accessing WDA HTTP endpoints.
+ *
+ * @returns The base URL (e.g., 'http://127.0.0.1:8100')
  */
 function getWdaLocalhostRoot() {
     const remotePort = ((this.isRealDevice() ? this.opts.wdaRemotePort : null)
@@ -809,8 +871,8 @@ function getWdaLocalhostRoot() {
  * The returned value could also be used to manually transform web coordinates
  * to real devices ones in client scripts.
  *
- * @this {XCUITestDriver}
- * @returns {Promise<import('../types').CalibrationData>}
+ * @returns Calibration data with offset and pixel ratio information
+ * @throws {errors.NotImplementedError} If not in a web context
  */
 async function mobileCalibrateWebToRealCoordinatesTranslation() {
     if (!this.isWebContext()) {
@@ -818,12 +880,11 @@ async function mobileCalibrateWebToRealCoordinatesTranslation() {
     }
     const currentUrl = await this.getUrl();
     await this.setUrl(`${this.getWdaLocalhostRoot()}/calibrate`);
-    const { width, height } = /** @type {import('@appium/types').Rect} */ (await this.proxyCommand('/window/rect', 'GET'));
+    const { width, height } = await this.proxyCommand('/window/rect', 'GET');
     const [centerX, centerY] = [width / 2, height / 2];
     const errorPrefix = 'Cannot determine web view coordinates offset. Are you in Safari context?';
-    const performCalibrationTap = async (/** @type {number} */ tapX, /** @type {number} */ tapY) => {
+    const performCalibrationTap = async (tapX, tapY) => {
         await this.mobileTap(tapX, tapY);
-        /** @type {import('@appium/types').Position} */
         let result;
         try {
             const title = await this.title();
@@ -855,30 +916,17 @@ async function mobileCalibrateWebToRealCoordinatesTranslation() {
         // restore the previous url
         await this.setUrl(currentUrl);
     }
-    const result = /** @type {import('../types').CalibrationData} */ (this.webviewCalibrationResult);
+    const result = this.webviewCalibrationResult;
     return {
         ...result,
         offsetX: Math.round(result.offsetX),
         offsetY: Math.round(result.offsetY),
     };
 }
-/**
- * @typedef {Object} SafariOpts
- * @property {object} preferences An object containing Safari settings to be updated.
- * The list of available setting names and their values could be retrieved by
- * changing the corresponding Safari settings in the UI and then inspecting
- * 'Library/Preferences/com.apple.mobilesafari.plist' file inside of
- * com.apple.mobilesafari app container.
- * The full path to the Mobile Safari's container could be retrieved from
- * `xcrun simctl get_app_container <sim_udid> com.apple.mobilesafari data`
- * command output.
- * Use the `xcrun simctl spawn <sim_udid> defaults read <path_to_plist>` command
- * to print the plist content to the Terminal.
- */
 /**
  * Updates Mobile Safari preferences on an iOS Simulator
  *
- * @param {import('@appium/types').StringRecord} preferences - An object containing Safari settings to be updated.
+ * @param preferences - An object containing Safari settings to be updated.
  * The list of available setting names and their values can be retrieved by changing the
  * corresponding Safari settings in the UI and then inspecting
  * `Library/Preferences/com.apple.mobilesafari.plist` file inside of the `com.apple.mobilesafari`
@@ -888,29 +936,27 @@ async function mobileCalibrateWebToRealCoordinatesTranslation() {
  * the plist content to the Terminal.
  *
  * @group Simulator Only
- * @returns {Promise<void>}
- * @throws {Error} if run on a real device or if the preferences argument is invalid
- * @this {XCUITestDriver}
+ * @throws {Error} If run on a real device
+ * @throws {errors.InvalidArgumentError} If the preferences argument is invalid
  */
 async function mobileUpdateSafariPreferences(preferences) {
-    if (!this.isSimulator()) {
-        throw new Error('This extension is only available for Simulator');
-    }
+    const simulator = utils_1.assertSimulator.call(this, 'Updating Safari preferences');
     if (!lodash_1.default.isPlainObject(preferences)) {
         throw new driver_1.errors.InvalidArgumentError('"preferences" argument must be a valid object');
     }
     this.log.debug(`About to update Safari preferences: ${JSON.stringify(preferences)}`);
-    await /** @type {import('appium-ios-simulator').Simulator} */ (this.device).updateSafariSettings(preferences);
+    await simulator.updateSafariSettings(preferences);
 }
 /**
- * @this {XCUITestDriver}
- * @param {timing.Timer} timer
- * @returns {Promise<InstanceType<typeof errors.TimeoutError>>}
+ * Generates a timeout error with detailed information about atom execution failure.
+ *
+ * @param timer - Timer instance to get duration from
+ * @returns Timeout error with descriptive message
  */
 async function generateAtomTimeoutError(timer) {
     let message = (`The remote Safari debugger did not respond to the requested ` +
         `command after ${timer.getDuration().asMilliSeconds}ms. `);
-    message += (await this.remote?.isJavascriptExecutionBlocked()) ? (`It appears that JavaScript execution is blocked, ` +
+    message += (await this._remote?.isJavascriptExecutionBlocked()) ? (`It appears that JavaScript execution is blocked, ` +
         `which could be caused by either a modal dialog obstructing the current page, ` +
         `or a JavaScript routine monopolizing the event loop.`) : (`However, the debugger still responds to JavaScript commands, ` +
         `which suggests that the provided atom script is taking too long to execute.`);
@@ -921,9 +967,12 @@ async function generateAtomTimeoutError(timer) {
     return new driver_1.errors.TimeoutError(message);
 }
 /**
- * @this {XCUITestDriver}
- * @param {any} atomsElement
- * @returns {Promise<boolean>}
+ * Attempts to tap a web element using native element matching.
+ *
+ * Tries to find a native element by matching text content, then taps it directly.
+ *
+ * @param atomsElement - Atoms-compatible element to tap
+ * @returns True if the native tap was successful, false otherwise
  */
 async function tapWebElementNatively(atomsElement) {
     // try to get the text of the element, which will be accessible in the
@@ -943,10 +992,10 @@ async function tapWebElementNatively(atomsElement) {
         }
         const el = els[0];
         // use tap because on iOS 11.2 and below `nativeClick` crashes WDA
-        const rect = /** @type {import('@appium/types').Rect} */ (await this.proxyCommand(`/element/${support_1.util.unwrapElement(el)}/rect`, 'GET'));
+        const rect = await this.proxyCommand(`/element/${support_1.util.unwrapElement(el)}/rect`, 'GET');
         if (els.length > 1) {
             const el2 = els[1];
-            const rect2 = /** @type {import('@appium/types').Rect} */ (await this.proxyCommand(`/element/${support_1.util.unwrapElement(el2)}/rect`, 'GET'));
+            const rect2 = await this.proxyCommand(`/element/${support_1.util.unwrapElement(el2)}/rect`, 'GET');
             if (rect.x !== rect2.x || rect.y !== rect2.y
                 || rect.width !== rect2.width || rect.height !== rect2.height) {
                 // These 2 native elements are not referring to the same web element
@@ -964,8 +1013,10 @@ async function tapWebElementNatively(atomsElement) {
     return false;
 }
 /**
- * @param {any} id
- * @returns {boolean}
+ * Validates if a value is a valid element identifier.
+ *
+ * @param id - Value to validate
+ * @returns True if the value is a valid element identifier
  */
 function isValidElementIdentifier(id) {
     if (!lodash_1.default.isString(id) && !lodash_1.default.isNumber(id)) {
@@ -980,12 +1031,12 @@ function isValidElementIdentifier(id) {
     return true;
 }
 /**
- * Creates a JavaScript Cookie
+ * Creates a JavaScript cookie string.
  *
- * @param {string} key
- * @param {string} value
- * @param {CookieOptions} [options={}]
- * @returns {string}
+ * @param key - Cookie name
+ * @param value - Cookie value
+ * @param options - Cookie options (expires, path, domain, secure, httpOnly)
+ * @returns Cookie string suitable for document.cookie
  */
 function createJSCookie(key, value, options = {}) {
     return [
@@ -999,31 +1050,12 @@ function createJSCookie(key, value, options = {}) {
     ].join('');
 }
 /**
- * @this {XCUITestDriver}
- * @param {import('@appium/types').Cookie} cookie
- * @returns {Promise<any>}
+ * Deletes a cookie via the remote debugger.
+ *
+ * @param cookie - Cookie object to delete
  */
 async function _deleteCookie(cookie) {
     const url = `http${cookie.secure ? 's' : ''}://${cookie.domain}${cookie.path}`;
-    return await ( /** @type {RemoteDebugger} */(this.remote)).deleteCookie(cookie.name, url);
+    return await this.remote.deleteCookie(cookie.name, url);
 }
-/**
- * @typedef {Object} CookieOptions
- * @property {string} [expires]
- * @property {string} [path]
- * @property {string} [domain]
- * @property {boolean} [secure]
- * @property {boolean} [httpOnly]
- */
-/**
- * @typedef {import('../driver').XCUITestDriver} XCUITestDriver
- * @typedef {import('@appium/types').Rect} Rect
- */
-/**
- * @template {string} [S=string]
- * @typedef {import('@appium/types').Element<S>} Element
- */
-/**
- * @typedef {import('appium-remote-debugger').RemoteDebugger} RemoteDebugger
- */ 
 //# sourceMappingURL=web.js.map