@browserstack/mcp-server 2.3.0-beta.5 → 2.3.0-beta.7

package/capability/mobiledevicecontrol.capability-index.json

@@ -3,7 +3,7 @@
  "version": "1.0",
  "build_id": "6782f7e_2026-10-16T13:54:22Z",
  "mobiledevicecontrol": {
-  "summary": "Mobile device control: run a real Android or iOS device and drive the app on it step by step. The account side lists the devices this account can use, including private ones, uploads and lists app builds, reports parallel-session capacity, and keeps each session's record \u2014 status, shareable link and video \u2014 after the device is released. The session side starts a device with an installed build and drives it: read the UI tree, find and tap elements, type, swipe, screenshot, press keys, rotate, switch between the native app and a web view, move between the native app and a web view, and launch or close apps. Apps are RUN here \u2014 unlike Test Management, which authors cases, and Test Reporting, which records results pushed in from a runner. Browsers are not here \u2014 those are device control, which drives a page rather than an installed app \u2014 and neither is App Live: it has no API an agent can drive, so agent sessions run on App Automate and consume its minutes. A build must exist before a session starts and can only be uploaded from a public link, never a file on disk \u2014 so media for camera injection must come from elsewhere. The default Appium server is 1.x and rejects every `mobile:` command; ask for 2.19.0.",
+  "summary": "Mobile device control: run a real Android or iOS device and drive the app on it step by step. The account side lists the devices this account can use, including private ones, uploads and lists app builds, reports parallel-session capacity, and keeps each session's record \u2014 status, shareable link and video \u2014 after the device is released. The session side starts a device with an installed build and drives it: find elements and read their text, position and attributes, tap them, type, swipe, screenshot, press keys, rotate, switch between the native app and a web view, move between the native app and a web view, and launch or close apps. Apps are RUN here \u2014 unlike Test Management, which authors cases, and Test Reporting, which records results pushed in from a runner. Browsers are not here \u2014 those are device control, which drives a page rather than an installed app \u2014 and neither is App Live: it has no API an agent can drive, so agent sessions run on App Automate and consume its minutes. A build must exist before a session starts and can only be uploaded from a public link, never a file on disk \u2014 so media for camera injection must come from elsewhere. The default Appium server is 1.x and rejects every `mobile:` command; ask for 2.19.0.",
   "routing_terms": [
    "app automate",
    "appium",
@@ -74,15 +74,19 @@
      "Allocation and app install usually take 20\u201330 seconds; the response carries the new session id at value.sessionId \u2014 carry it into every other app_session call.",
      "The session ends itself after idle_timeout seconds with no command (90 by default, 900 at most) and after 2 hours in total. Keep calling, or call get_window_rect as a cheap keep-alive, while deciding the next step.",
      "Every session occupies a device and consumes App Automate minutes until it ends: always finish with set_session_status and then delete_session.",
-     "To let a person watch the device live while the agent drives it, set interactive_debugging true and leave video on; they then open the running session on the App Automate dashboard and start the interactive session there. That window is two-way: a person's taps and scrolls reach the same device, so ask them to watch only, or re-read the page source before every action.",
+     "To let a person watch the device live while the agent drives it, set interactive_debugging true and leave video on; they then open the running session on the App Automate dashboard and start the interactive session there. That window is two-way: a person's taps and scrolls reach the same device, so ask them to watch only, or find the element you are about to act on again before every action.",
      "device_name and platform_version must be a combination mobile device control offers; an unknown pair fails with a session-not-created error naming the capability.",
-     "Set appium_version to 2.19.0 for any session that will use execute_script with a `mobile:` command; the default server is 1.x and answers those with a 404 listing the commands it does know.",
+     "Set appium_version to 2.19.0 for any session that will scroll with scroll_gesture, dismiss an iOS keyboard with dismiss_keyboard_key, or use any other mobile: capability; the default server is 1.x and answers those with a 404 listing the commands it does know.",
      "enable_biometric, enable_camera_image_injection and upload_media only take effect when set here \u2014 none of them can be turned on once the session is running.",
      "Credentials belong in the Authorization header, never inside bstack:options: capabilities are echoed back in session-not-created errors.",
      "device_name and platform_version come from list_devices; get_plan first if sessions are queueing rather than starting.",
      "Treat a response without value.sessionId as a failed start even when the status is 200, and treat a failed call the same way: allocation can outlast the client's own timeout, so BrowserStack may have started a session the answer never named. One is then holding a device and consuming minutes until its idle timeout.",
      "After a start that failed or returned no session id, look for a session left running on the account and end it rather than starting another.",
-     "The response carries no link of any kind \u2014 it is the session id and the negotiated capabilities only. Call get_session for the links: browser_url to watch the run on the dashboard, and public_url to share it with someone who has no BrowserStack account."
+     "The response carries no link of any kind \u2014 it is the session id and the negotiated capabilities only. Call get_session for the links: browser_url to watch the run on the dashboard, and public_url to share it with someone who has no BrowserStack account.",
+     "LANGUAGE AND LOCALE LAND IN DIFFERENT PLACES ON THE TWO PLATFORMS. On Android they change the device, and the app with it \u2014 measured with language de and locale DE: the system's own permission dialog came up in German and the app rendered German throughout. On iOS they leave the device alone \u2014 Settings and General stay in English \u2014 and apply to the app under test at launch. Either way nothing is visible unless the app actually ships that language, so test with an app that does and read the strings back with get_element_text rather than trusting the call's 200.",
+     "Both are accepted without complaint on both platforms, so a 200 says nothing about whether anything changed. There is also no way to confirm the device locale from inside the session: read_device_property refuses getprop persist.sys.locale and ro.product.locale as unsupported commands. Judge it from what is on screen.",
+     "THIS CALL RETURNS NO LINK \u2014 only value.sessionId. Nothing here can open a browser for the user either: this surface makes HTTP requests, and on a remote server there is no browser to open. So never say a live view was opened. If the user may want to watch, call get_session straight after this and give them browser_url in the same reply, which is the session on the dashboard and needs a BrowserStack login. public_url needs no login but carries an auth token, so offer it only when they ask to share outside the team.",
+     "Someone can only WATCH AND INTERACT if interactive_debugging was set true in this call \u2014 it cannot be turned on once the session is running, it is off by default on Android, and it needs video left on. Ask for it up front when a person is going to follow along, because the alternative is restarting the session."
     ],
     "body": [
      {
@@ -209,15 +213,15 @@
       "name": "language",
       "type": "string",
       "json_path": "/capabilities/alwaysMatch/appium:language",
-      "description": "Device language code.",
-      "example": "fr"
+      "description": "Language code applied at session start. On Android it sets the DEVICE language \u2014 the system's own dialogs render in it \u2014 and the app follows. On iOS it does NOT change the device: Settings stays in English, and the code is applied to the app under test at launch instead.",
+      "example": "de"
      },
      {
       "name": "locale",
       "type": "string",
       "json_path": "/capabilities/alwaysMatch/appium:locale",
-      "description": "Device locale.",
-      "example": "fr_CA"
+      "description": "Region applied with `language`, same split: the device on Android, the app under test on iOS. Android takes a bare region code such as DE.",
+      "example": "DE"
      },
      {
       "name": "timezone",
@@ -317,11 +321,7 @@
     "entity": "app_session",
     "intent": "Read the full UI tree of the screen currently shown in the app \u2014 use this to see what is on screen and choose what to tap, type into or scroll before acting.",
     "guidance": [
-     "Returns the whole hierarchy as one XML string in value, unfiltered. On Android each node carries text, content-desc, resource-id, clickable, scrollable and bounds; on iOS name, label, value and x/y/width/height.",
-     "Read it again after every action: the tree is a snapshot, and element ids from find_element go stale once the screen changes.",
-     "Android bounds are \"[x1,y1][x2,y2]\" in device pixels \u2014 the centre of that box is the coordinate to use with perform_actions.",
-     "A product-specific attribute is the best locator: resource-id for find_element using \"id\", content-desc for \"accessibility id\".",
-     "Inside a web view this returns the page's HTML instead of the native tree, and a real page runs to hundreds of kilobytes where a native screen is a few. Switch back to NATIVE_APP before reading the tree again, or search the HTML for what you need rather than reading all of it."
+     "Not published: the whole tree runs to tens of kilobytes, more than a caller can read. Find the elements you need with find_element or find_elements and read them with get_element_text, get_element_rect and get_element_attribute."
     ],
     "path_params": [
      {
@@ -345,7 +345,8 @@
      "404": {
       "$response": "WebDriverError"
      }
-    }
+    },
+    "disabled": true
    },
    {
     "name": "find_element",
@@ -356,8 +357,8 @@
     "intent": "Locate one element on the current screen by id, accessibility id, XPath or UiAutomator selector \u2014 use this to get the element id that click_element and send_keys act on.",
     "guidance": [
      "The element id comes back under the W3C key value[\"element-6066-11e4-a52e-4f735466cecf\"]; pass that string as element_id.",
-     "Take the selector from get_page_source rather than guessing: resource-id \u2192 \"id\", content-desc (Android) or name (iOS) \u2192 \"accessibility id\".",
-     "No match is a 404 with error \"no such element\" \u2014 re-read the page source; the screen may have changed or the element may be off-screen and need a scroll first.",
+     "Locators by platform: resource-id \u2192 \"id\", content-desc (Android) or name (iOS) \u2192 \"accessibility id\", visible text \u2192 xpath such as //*[@text='Submit'] on Android or -ios predicate string label == 'Submit' on iOS. Once you hold an element, get_element_attribute reads its ids and get_element_text what it says.",
+     "No match is a 404 with error \"no such element\" \u2014 the screen may have changed, or the element may be off-screen and need a scroll first; find it again after the scroll. \"No such element\" is also the cheapest way to confirm something is NOT on screen.",
      "\"-android uiautomator\" accepts a UiSelector expression, which can scroll an element into view: new UiScrollable(new UiSelector().scrollable(true)).scrollIntoView(new UiSelector().text(\"Checkout\")).",
      "find_elements answers the same query with a list and never a 404, which is how to ask whether something is present without treating absence as a failure."
     ],
@@ -417,8 +418,8 @@
     "intent": "Tap an element in the app \u2014 use this to press a button, open a menu item, select a list row or focus a field found with find_element.",
     "guidance": [
      "element_id must come from find_element on the current screen; after the screen changes it is stale and fails with \"stale element reference\".",
-     "To tap something that has no usable locator, tap its bounds centre with perform_actions instead.",
-     "Read get_page_source afterwards to confirm the tap had the intended effect \u2014 a 200 only means the tap was delivered.",
+     "To tap something that has no usable locator, take the centre of a nearby element's get_element_rect and tap the coordinates with perform_actions instead.",
+     "Confirm the tap had the intended effect \u2014 a 200 only means it was delivered: find an element the new screen should carry, or read a label with get_element_text before and after.",
      "A keyboard covers the lower part of the screen and a tap aimed underneath it lands on the keyboard while still reporting success. When the target sits low, call is_keyboard_shown and then hide_keyboard before tapping."
     ],
     "path_params": [
@@ -459,12 +460,12 @@
     "entity": "app_session",
     "intent": "Type text into an input field in the app \u2014 use this to fill a search box, login form or any editable field found with find_element.",
     "guidance": [
-     "WHETHER THIS REPLACES OR APPENDS DEPENDS ON THE PLATFORM: on Android it replaces whatever the field already holds, and on iOS it appends to it. Typing twice into one iOS field therefore leaves both values joined. Read the field back from get_page_source whenever the resulting value matters.",
+     "WHETHER THIS REPLACES OR APPENDS DEPENDS ON THE PLATFORM: on Android it replaces whatever the field already holds, and on iOS it appends to it. Typing twice into one iOS field therefore leaves both values joined. Read the field back with get_element_text whenever the resulting value matters.",
      "The element must be an editable field (EditText on Android, TextField on iOS); typing into anything else fails with \"invalid element state\".",
-     "The on-screen keyboard may stay open afterwards and cover lower elements \u2014 re-read the page source before the next tap.",
-     "There is no way to empty a field on this surface: the standard clear endpoint answers 200 without reliably emptying it, so typing the value you want is the way to set it \u2014 and on iOS, where this appends, there is no way to correct a field you have already typed into.",
-     "The keyboard is usually left open afterwards. On Android, hide_keyboard closes it. On iOS it cannot be closed without submitting, so read hide_keyboard's guidance before planning a tap below the field.",
-     "Sending a newline closes the keyboard on iOS by SUBMITTING the field: the field resets to its placeholder and the value moves wherever the app sends it. Use it to dismiss the keyboard only when submitting is what you wanted anyway; see hide_keyboard for what the alternatives do."
+     "The on-screen keyboard may stay open afterwards and cover lower elements \u2014 check is_keyboard_shown, and compare get_element_rect of the next target with the screen's lower part, before the next tap.",
+     "clear_element empties a field, and on iOS \u2014 where this APPENDS \u2014 it is the only way to take back what is already there. It answers 200 whether or not the field changed, so read the field back with get_element_text rather than trusting the status.",
+     "The keyboard is usually left open afterwards. On Android and on an iPad, hide_keyboard closes it. On an iPhone it cannot be closed without submitting, so read hide_keyboard's guidance before planning a tap below the field.",
+     "Sending a newline closes the keyboard on iOS by pressing Return, which an app that commits on editing-ended will treat as a submit \u2014 the field resets and the value moves wherever the app sends it. The commit is the app's doing, not the newline's: dismissing the same field any other way can commit it too. See hide_keyboard."
     ],
     "path_params": [
      {
@@ -504,6 +505,51 @@
      }
     }
    },
+   {
+    "name": "clear_element",
+    "method": "POST",
+    "path": "/wd/hub/session/{session_id}/element/{element_id}/clear",
+    "mode": "write",
+    "entity": "app_session",
+    "intent": "Empty an editable field in the app \u2014 use this before typing when the field already holds something and you need to replace rather than add to it.",
+    "guidance": [
+     "Takes no parameters of its own.",
+     "CONFIRM IT ACTUALLY EMPTIED THE FIELD by reading it back with get_element_text: this endpoint can answer 200 without the field changing, and the status alone does not tell you which happened.",
+     "Needed far more on iOS than on Android: send_keys REPLACES the field's contents on Android, so clearing first is usually unnecessary there, while on iOS it APPENDS and this is the only way to take back what is already in the field.",
+     "The element must be an editable field \u2014 EditText on Android, TextField on iOS. Anything else answers \"invalid element state\".",
+     "The element_id must come from find_element on the current screen; after the screen changes it is stale and fails with \"stale element reference\"."
+    ],
+    "path_params": [
+     {
+      "name": "session_id",
+      "type": "string",
+      "required": true,
+      "example": "0123456789abcdef0123456789abcdef01234567"
+     },
+     {
+      "name": "element_id",
+      "type": "string",
+      "required": true,
+      "description": "Element id from find_element.",
+      "example": "element-6066-11e4-a52e-4f735466cecf"
+     }
+    ],
+    "returns": [
+     "value"
+    ],
+    "responses": {
+     "200": {
+      "description": "Field emptied; value is null. The null says the call was accepted, not that the field changed \u2014 read the field back to know that.",
+      "schema": {
+       "$schema": "NullValueResponse"
+      }
+     },
+     "404": {
+      "$response": "WebDriverError"
+     }
+    },
+    "send_empty_body": true
+   },
    {
     "name": "perform_actions",
     "method": "POST",
@@ -512,11 +558,11 @@
     "entity": "app_session",
     "intent": "Perform touch gestures on the device screen by coordinates \u2014 tap a point, swipe or scroll a list, long-press, or drag \u2014 using W3C pointer actions.",
     "guidance": [
-     "Coordinates are device pixels in the same space as the page-source bounds; take them from there rather than from a screenshot, whose height can include the system bars.",
+     "Coordinates are device pixels on Android and points on iOS \u2014 the space get_element_rect and get_window_rect report in; take them from there rather than from a screenshot, whose height can include the system bars.",
      "Tap: one touch pointer with pointerMove(duration 0, x, y), pointerDown(button 0), pause(100), pointerUp(button 0).",
-     "Swipe up to scroll content down: pointerMove to a low point, pointerDown, pointerMove(duration 600) to a higher point, pointerUp. Keep the start and end inside the scrollable element's bounds.",
+     "Swipe up to scroll content down: pointerMove to a low point, pointerDown, pointerMove(duration 600) to a higher point, pointerUp. Keep the start and end inside the scrollable element's get_element_rect. For a plain scroll or swipe, scroll_gesture (Android) and scroll_view (iOS) need no coordinates at all.",
      "Long-press: replace the pause duration with 1000 or more.",
-     "For a scroll without computing coordinates, execute_script with \"mobile: scrollGesture\" is simpler and reports whether more content remains.",
+     "For a scroll without computing coordinates, scroll_gesture is simpler on Android and reports whether more content remains; on iOS use scroll_view; compute a swipe here only when neither fits.",
      "To go back on an iOS screen that ignores press_back, swipe in from the left edge: a pointer sequence starting at exactly x=0 and moving right in several short steps. A single long move does not register."
     ],
     "path_params": [
@@ -607,6 +653,203 @@
      }
     }
    },
+   {
+    "name": "scroll_gesture",
+    "method": "POST",
+    "path": "/wd/hub/session/{session_id}/execute/sync",
+    "mode": "write",
+    "entity": "app_session",
+    "intent": "Swipe or scroll a region of the screen in a direction \u2014 use this to move through a list or page, or to swipe left and right through a carousel of cards, without working out start and end coordinates yourself.",
+    "guidance": [
+     "ANDROID ONLY. On iOS this is a 405 \"unknown method\"; scroll_view is the iOS counterpart.",
+     "The returned value is true when the view can still scroll further in that direction and false when it cannot \u2014 but the FIRST scroll of a freshly opened list can answer false while the screen moved and more content followed, so treat false as a hint and confirm by finding the element you expect before deciding you are at the end.",
+     "A HORIZONTAL SWIPE IS THE SAME CALL with direction left or right: a rectangle covering the carousel's band of the screen, taken from get_window_rect, is enough \u2014 no element bounds are needed, and perform_actions is the harder way to do the same thing. DIRECTION NAMES WHERE THE CONTENT COMES FROM, as with a list: down brings what is below into view (the finger moves up), so right brings the NEXT card and left the previous one.",
+     "The area is a rectangle in screen pixels \u2014 get_window_rect gives the screen size to base it on \u2014 and percent is how far to scroll within it, 0 to 1.",
+     "Needs Appium 2.x: set appium_version to 2.19.0 at session start, since the default 1.x server answers mobile: commands with a 404 listing what it does know."
+    ],
+    "path_params": [
+     {
+      "name": "session_id",
+      "type": "string",
+      "required": true,
+      "example": "0123456789abcdef0123456789abcdef01234567"
+     }
+    ],
+    "body": [
+     {
+      "name": "script",
+      "type": "string",
+      "required": true,
+      "example": "mobile: scrollGesture",
+      "values": [
+       "mobile: scrollGesture"
+      ]
+     },
+     {
+      "name": "args",
+      "type": "array",
+      "required": true,
+      "description": "Exactly one object: the rectangle to scroll inside, the direction (up, down, left or right), and how far.",
+      "example": [
+       {
+        "left": 100,
+        "top": 500,
+        "width": 880,
+        "height": 1500,
+        "direction": "down",
+        "percent": 0.8
+       }
+      ]
+     }
+    ],
+    "returns": [
+     "value"
+    ],
+    "responses": {
+     "200": {
+      "description": "Command result; its shape depends on the command.",
+      "schema": {
+       "$schema": "AnyValueResponse"
+      }
+     },
+     "404": {
+      "$response": "WebDriverError"
+     },
+     "500": {
+      "$response": "WebDriverError"
+     }
+    }
+   },
+   {
+    "name": "scroll_view",
+    "method": "POST",
+    "path": "/wd/hub/session/{session_id}/execute/sync",
+    "mode": "write",
+    "entity": "app_session",
+    "intent": "Swipe or scroll a scrollable view on iOS in a direction, or until a named element is visible \u2014 use this to move through a list or a long screen, or to swipe left and right through a carousel.",
+    "guidance": [
+     "iOS ONLY, and the counterpart of scroll_gesture. On Android the same command exists with a different shape and answers 400 \"invalid argument\" naming strategy and selector as missing; use scroll_gesture there.",
+     "Scroll by direction with {\"direction\":\"down\"}, or stop when something comes into view with {\"predicateString\":\"name == 'Submit'\", \"toVisible\": true} \u2014 the second is the reliable way to reach a known control without guessing how far to go.",
+     "A HORIZONTAL SWIPE IS THE SAME CALL with direction left or right, optionally with elementId naming the carousel; no coordinates are needed.",
+     "Pass elementId in args to scroll inside that view rather than the whole screen; without one it scrolls the first scrollable view it finds, which may not be the one you meant.",
+     "Needs Appium 2.x: set appium_version to 2.19.0 at session start, since the default 1.x server answers mobile: commands with a 404 listing what it does know.",
+     "Confirm the screen actually moved \u2014 find the element you were scrolling toward, or compare get_element_rect of one element before and after \u2014 since this answers 200 even on a screen with nothing scrollable: a 200 only says the gesture was delivered."
+    ],
+    "path_params": [
+     {
+      "name": "session_id",
+      "type": "string",
+      "required": true,
+      "example": "0123456789abcdef0123456789abcdef01234567"
+     }
+    ],
+    "body": [
+     {
+      "name": "script",
+      "type": "string",
+      "required": true,
+      "values": [
+       "mobile: scroll"
+      ],
+      "example": "mobile: scroll"
+     },
+     {
+      "name": "args",
+      "type": "array",
+      "required": true,
+      "description": "Exactly one object: a direction, or a predicateString with toVisible, optionally with elementId naming the view to scroll inside.",
+      "example": [
+       {
+        "direction": "down"
+       }
+      ]
+     }
+    ],
+    "returns": [
+     "value"
+    ],
+    "responses": {
+     "200": {
+      "description": "Command result; its shape depends on the command.",
+      "schema": {
+       "$schema": "AnyValueResponse"
+      }
+     },
+     "404": {
+      "$response": "WebDriverError"
+     },
+     "500": {
+      "$response": "WebDriverError"
+     }
+    }
+   },
+   {
+    "name": "dismiss_keyboard_key",
+    "method": "POST",
+    "path": "/wd/hub/session/{session_id}/execute/sync",
+    "mode": "write",
+    "entity": "app_session",
+    "intent": "Close the on-screen keyboard by pressing one of its own keys \u2014 use this on an iPhone, where the plain hide_keyboard is refused.",
+    "guidance": [
+     "hide_keyboard already presses these keys on an iPhone when its plain call is refused \u2014 Done-type keys first, then Return \u2014 and reports each attempt. Call this directly to press exactly the key you choose: Return alone, or every key but Return when a submit must not happen.",
+     "The key must EXIST on that keyboard or this returns the same 400: list the keyboard's keys with find_elements using class name XCUIElementTypeKey and read each with get_element_text, then pick from the keys that are really there. An iPad carries \"Hide keyboard\"; an iPhone keyboard of this kind usually offers only Return.",
+     "Several candidates may be listed in one call and it costs nothing, but it still fails when the keyboard carries none of them \u2014 measured with [\"Done\",\"done\",\"Hide keyboard\",\"Dismiss\"].",
+     "PRESSING RETURN SUBMITS. An app that commits when the field stops being edited will commit however the keyboard is closed, so check the field afterwards rather than assuming only the keyboard moved.",
+     "Confirm with is_keyboard_shown; on Android and on an iPad hide_keyboard closes it on its own."
+    ],
+    "path_params": [
+     {
+      "name": "session_id",
+      "type": "string",
+      "required": true,
+      "example": "0123456789abcdef0123456789abcdef01234567"
+     }
+    ],
+    "body": [
+     {
+      "name": "script",
+      "type": "string",
+      "required": true,
+      "example": "mobile: hideKeyboard",
+      "values": [
+       "mobile: hideKeyboard"
+      ]
+     },
+     {
+      "name": "args",
+      "type": "array",
+      "required": true,
+      "description": "Exactly one object whose keys field lists the key names to try, in order.",
+      "example": [
+       {
+        "keys": [
+         "Done",
+         "done",
+         "Hide keyboard",
+         "Dismiss"
+        ]
+       }
+      ]
+     }
+    ],
+    "returns": [
+     "value"
+    ],
+    "responses": {
+     "200": {
+      "description": "Command result; its shape depends on the command.",
+      "schema": {
+       "$schema": "AnyValueResponse"
+      }
+     },
+     "404": {
+      "$response": "WebDriverError"
+     },
+     "500": {
+      "$response": "WebDriverError"
+     }
+    }
+   },
    {
     "name": "execute_script",
     "method": "POST",
@@ -670,7 +913,8 @@
      "500": {
       "$response": "WebDriverError"
      }
-    }
+    },
+    "disabled": true
    },
    {
     "name": "get_window_rect",
@@ -680,7 +924,7 @@
     "entity": "app_session",
     "intent": "Get the device screen size in pixels \u2014 use this to plan gesture coordinates, or as a cheap keep-alive so an idle session is not ended while deciding the next step.",
     "guidance": [
-     "On Android the height excludes the system bars, so it can be smaller than a screenshot's height; page-source bounds use this same space."
+     "On Android the height is the WHOLE screen including the status bar \u2014 2340 on a Galaxy S24 whose usable area starts 91px down \u2014 so the top strip of that rectangle is not the app's. On iOS it is the app's window in points."
     ],
     "path_params": [
      {
@@ -718,7 +962,7 @@
     "guidance": [
      "There is no way to resume an ended session; any further step needs create_session again, which reinstalls the app.",
      "The session's video, logs and pass/fail status stay on the App Automate dashboard after it ends.",
-     "Call setSessionStatus through execute_script first \u2014 once the session has ended that route is gone."
+     "Mark the result with set_session_status first \u2014 it also works after the session has ended, so this is an ordering preference rather than a last chance."
     ],
     "path_params": [
      {
@@ -729,23 +973,14 @@
      }
     ],
     "returns": [
+     "state",
      "value"
     ],
     "responses": {
      "200": {
-      "description": "Session ended; state is \"success\" and value is empty.",
+      "description": "state is \"success\" and value an empty string; the body is the hub's own, not the W3C null.",
       "schema": {
-       "type": "object",
-       "properties": {
-        "state": {
-         "type": "string",
-         "description": "\"success\" when the session was ended."
-        },
-        "value": {
-         "type": "string",
-         "description": "Empty string."
-        }
-       }
+       "$schema": "SessionDeletedResponse"
       }
      },
      "404": {
@@ -860,13 +1095,14 @@
     "entity": "app_build",
     "intent": "Upload an app build to App Automate from a public download link and get back the bs:// URL a session installs \u2014 use this to make a new .apk, .aab or .ipa available to devices.",
     "guidance": [
-     "Only the download-link form can be used here. The same endpoint also accepts a multipart upload carrying the file itself, which this surface cannot send \u2014 so for a build that exists only on the caller's own machine, give them that multipart request to run themselves and take the bs:// url it returns. There is no way to hand the bytes over from here.",
+     "Only the download-link form can be used here. The same endpoint also accepts a multipart upload carrying the file itself, which this surface cannot send \u2014 so for a build that exists only on the caller's own machine, give them that multipart request to run themselves and take the bs:// url it returns. The upload answers with the bs:// url directly: there is no intermediate storage, no presigned url and no second call. There is no way to hand the bytes over from here.",
      "The url must be https and reachable by BrowserStack without credentials; a link behind a login fails on their side, not the caller's.",
      "Pass custom_id to give the build a stable name, then later sessions can use that name in place of the bs:// URL and always get the newest build under it.",
      "Re-uploading under the same custom_id adds a new build rather than replacing the old one; both stay listed.",
      "Builds expire after 30 days, so a bs:// URL held from an earlier run can stop working.",
      "Uploading a large build can take minutes \u2014 the call does not return until BrowserStack has fetched the whole file.",
-     "upload_app_build_from_file takes a build that is on this machine instead, where the server runs beside the user. It is not offered on a remote server, where a path would name the operator's disk rather than theirs."
+     "upload_app_build_from_file takes a build that is on this machine instead, where the server runs beside the user. It is not offered on a remote server, where a path would name the operator's disk rather than theirs.",
+     "Before uploading at all, check list_app_builds \u2014 a build from an earlier run is still usable for 30 days, and on a remote server reusing one is the only route that needs nothing from the user."
     ],
     "body": [
      {
@@ -913,7 +1149,8 @@
     "guidance": [
      "An account with no uploads answers with a message object or a 404 rather than an empty array; treat both as 'nothing uploaded yet'.",
      "This is only the calling user's own uploads \u2014 use list_team_app_builds for everyone on the team.",
-     "app_url is what create_session takes; app_id is an internal identifier and is not accepted there."
+     "app_url is what create_session takes; app_id is an internal identifier and is not accepted there.",
+     "On a remote server this is the first thing to try: uploading from a path is not offered there, so an existing build is the only app a session can install without either a public link or the user running an upload by hand."
     ],
     "query": [
      {
@@ -1097,8 +1334,7 @@
      "Works after the session has ended as well as during it, so the verdict can be set once the result is known.",
      "Only 'passed' and 'failed' are accepted; any other value is rejected with a 422.",
      "reason is truncated at 255 characters.",
-     "An unset session shows as neither passed nor failed on the dashboard, which reads as an abandoned run.",
-     "The same thing can be done from inside a running session with execute_script and the browserstack_executor setSessionStatus action; this way needs no open session."
+     "An unset session shows as neither passed nor failed on the dashboard, which reads as an abandoned run."
     ],
     "path_params": [
      {
@@ -1216,7 +1452,7 @@
     "entity": "app_session",
     "intent": "Take a screenshot of what is on the device right now, as a base64 PNG \u2014 use this to see the screen as a user would, including anything the UI tree does not describe.",
     "guidance": [
-     "The image is returned inline as base64 in value and a phone screen runs to hundreds of kilobytes, so fetch it only when the picture is needed and prefer get_page_source for deciding what to act on.",
+     "The image is returned inline as base64 in value and a phone screen runs to hundreds of kilobytes, so fetch it only when the picture is needed and prefer find_element with get_element_text for deciding what to act on.",
      "Screenshot pixels are the device's full resolution and can be taller than the rectangle get_window_rect reports, because that excludes the system bars; scale before reusing screenshot coordinates for gestures.",
      "A screen the app marks secure comes back black, which is the app's doing and not a failure."
     ],
@@ -1252,8 +1488,8 @@
     "intent": "Go back one screen \u2014 use this to leave a detail page, close a dialog, or undo a navigation step.",
     "guidance": [
      "On Android this is the system back button and is the reliable way back.",
-     "On iOS this works on a screen that uses a standard navigation bar, where it acts on the bar's own back control. A screen that draws its own header instead is left where it was, and the call still answers 200 \u2014 so confirm from the page source rather than from the status.",
-     "Pressing back on the first screen of an app can send the app to the background and show the home screen; read the page source afterwards to confirm where you are.",
+     "On iOS this works on a screen that uses a standard navigation bar, where it acts on the bar's own back control. A screen that draws its own header instead is left where it was, and the call still answers 200 \u2014 so confirm by finding an element of the screen you expect rather than from the status.",
+     "Pressing back on the first screen of an app can send the app to the background and show the home screen; find one of the app's own elements afterwards to confirm where you are \u2014 \"no such element\" means it went to the background.",
      "The response is null on success and says nothing about whether the screen actually changed.",
      "When an iOS screen ignores it, swipe in from the left edge with perform_actions: start at exactly x=0 and move in several short steps. One long move, or a start at x=2, is ignored."
     ],
@@ -1323,7 +1559,7 @@
     "guidance": [
      "An app that locks its orientation refuses the rotation with a 400 'invalid element state' saying the screen could not be changed; that is the app's choice, not a broken call.",
      "The value must be upper case, PORTRAIT or LANDSCAPE.",
-     "Element positions and the window rectangle change after a rotation, so re-read the page source before acting on coordinates.",
+     "Element positions and the window rectangle change after a rotation, so re-read get_element_rect and get_window_rect before acting on coordinates.",
      "The response carries the new orientation on Android and null on iOS, so treat a 200 rather than the value as the sign it worked, and read get_orientation if the value matters."
     ],
     "path_params": [
@@ -1404,7 +1640,7 @@
     "intent": "Switch between the native app and a web view \u2014 use this when the part of the screen you need to drive is web content inside the app.",
     "guidance": [
      "Use a name exactly as list_contexts returned it; an invented WEBVIEW name is rejected.",
-     "In a web view, selectors change: find_element then takes css selector and the page source is HTML rather than the native UI tree.",
+     "In a web view, selectors change: find_element then takes css selector and get_element_text reads the page's text rather than a native label.",
      "Switch back to NATIVE_APP before driving native controls again.",
      "A web view's name carries the process id of the app that owns it, so it differs between sessions and after the app restarts. Read it from list_contexts each time rather than reusing one seen earlier."
     ],
@@ -1448,12 +1684,13 @@
     "entity": "app_session",
     "intent": "Close the on-screen keyboard \u2014 use this when it covers a button or field you need to tap after typing.",
     "guidance": [
-     "The response is true when a keyboard was dismissed and false when none was showing; false is not an error.",
+     "On a plain success the response is true when a keyboard was dismissed and false when none was showing; false is not an error. A success reached through the chain below carries the key press's own null value instead.",
      "A tap aimed at a control hidden behind the keyboard lands on the keyboard instead and reports success, so close it first rather than afterwards.",
-     "On iOS this FAILS rather than quietly doing nothing: 400 \"invalid element state\", message \"Did not know how to dismiss the keyboard\". The keyboard stays up and the field keeps what was typed, so treat the 400 as the normal answer on iOS and not as a broken call.",
-     "What does close it on iOS closes it BY SUBMITTING: send_keys with a newline, or execute_script with 'mobile: hideKeyboard' and args [{\"keys\":[\"return\"]}]. Both press Return, so the field is submitted and cleared to its placeholder and the value moves wherever the app sends it \u2014 that is a change to the app, not just to the keyboard.",
-     "The keys argument names a key on the APP'S OWN keyboard, so it fails the same way when that key is absent: [\"Done\"] returns the same 400 on a keyboard that offers only Return. Omitting keys fails too, and tapping an empty area above the keyboard with perform_actions returns 200 and changes nothing.",
-     "So on iOS there may be no way to put the keyboard away without submitting. Prefer a flow that does not need to tap underneath it \u2014 read values from get_page_source rather than tapping a control the keyboard covers. On Android this capability works normally.",
+     "ON AN iPHONE THE PLAIN CALL IS REFUSED AND A CHAIN RUNS INSTEAD. That keyboard has no dismiss key, so the product answers 400 \"Did not know how to dismiss the keyboard\"; this then presses a key the keyboard actually carries \u2014 Done, Hide keyboard or Dismiss where one exists, and failing that Return. On an iPad the plain call closes it, because that keyboard carries \"Hide keyboard\"; on Android it closes it; neither runs the chain.",
+     "THE RESPONSE LISTS EVERY ATTEMPT WITH ITS STATUS under fallback.attempts, so read which one closed it. When the last attempt's keys include Return, Return is what was pressed \u2014 and in many apps that is a submit: a search runs, a form goes. Read the field and the screen back before assuming only the keyboard moved.",
+     "When no attempt answers 200 the keyboard stays up and the last 400 is the answer: the app offers no way to close it from outside, which a person on the phone would hit too. dismiss_keyboard_key is the same key press on its own, for trying exactly the key you choose \u2014 Return alone, or everything but Return.",
+     "GESTURES DO NOT DISMISS IT. Tapping an empty area above the keyboard returns 200 and changes nothing, and so does a drag downward over it \u2014 including one that starts well above the keyboard's top and moves through it in short steps, which is the form that works on a screen whose scroll view dismisses on drag. This app's does not, and neither gesture moved it.",
+     "WHETHER THE FIELD SURVIVES IS THE APP'S BUSINESS, NOT THE KEYBOARD'S. An app that commits on editing-ended will commit however the keyboard is dismissed \u2014 closing an iPad keyboard this way still moved the text out of the field. So do not expect any dismissal to be side-effect free; check the app's own behaviour. On Android it closes the keyboard, answers true, and leaves the field as it was.",
      "is_keyboard_shown reports the state this changes, and is the reliable way to tell whether the keyboard actually went away."
     ],
     "path_params": [
@@ -1464,6 +1701,50 @@
       "example": "0123456789abcdef0123456789abcdef01234567"
      }
     ],
+    "fallbacks": [
+     {
+      "when": {
+       "status": 400
+      },
+      "capability": "dismiss_keyboard_key",
+      "body": {
+       "script": "mobile: hideKeyboard",
+       "args": [
+        {
+         "keys": [
+          "Done",
+          "done",
+          "Hide keyboard",
+          "Dismiss"
+         ]
+        }
+       ]
+      }
+     },
+     {
+      "when": {
+       "status": 400
+      },
+      "capability": "dismiss_keyboard_key",
+      "body": {
+       "script": "mobile: hideKeyboard",
+       "args": [
+        {
+         "keys": [
+          "Return",
+          "return",
+          "Go",
+          "go",
+          "Next",
+          "next",
+          "Search",
+          "search"
+         ]
+        }
+       ]
+      }
+     }
+    ],
     "returns": [
      "value"
     ],
@@ -1692,11 +1973,11 @@
     "entity": "app_session",
     "intent": "Press a hardware or system key on an Android device by its key code \u2014 use this for home, enter, delete, volume or any key with no on-screen control.",
     "guidance": [
-     "Android only. iOS has no equivalent: use press_back to go back, and execute_script with 'mobile: pressButton' for home and the volume keys.",
+     "Android only. iOS has no equivalent: use press_back to go back, and press_button for home and the volume keys.",
      "Common codes: 3 home, 4 back, 66 enter, 67 delete, 61 tab, 82 menu, 84 search, 187 app switch, 24 volume up, 25 volume down, 26 power.",
      "press_back is the clearer way to send 4.",
      "The response is null on success and says nothing about what the key did.",
-     "Called on iOS this is a 405 \"unknown method\" rather than a silent no-op; use press_back or 'mobile: pressButton' there."
+     "Called on iOS this is a 405 \"unknown method\" rather than a silent no-op; use press_back or press_button there."
     ],
     "path_params": [
      {
@@ -1754,7 +2035,7 @@
      "Returns the Android package name; it answers with the launcher's package when the app has been sent to the background.",
      "This is the quickest way to learn the app under test's own package id, which launch_app and terminate_app both need.",
      "Android only; get_active_app_info is the iOS equivalent and returns an object rather than a string.",
-     "Called on iOS this is a 405 \"unknown method\" rather than a silent no-op; use 'mobile: activeAppInfo' there."
+     "Called on iOS this is a 405 \"unknown method\" rather than a silent no-op; use get_active_app_info there."
     ],
     "path_params": [
      {
@@ -1809,7 +2090,7 @@
     "entity": "app_session",
     "intent": "Bring an app to the foreground, starting it if it is not running \u2014 use this to open the app under test, return to it, or switch to another installed app.",
     "guidance": [
-     "Android takes appId and iOS takes bundleId \u2014 send exactly the one for the platform. The wrong name is refused with a 400 \"invalid argument\" that names the parameter it wanted, and no action is taken.",
+     "The app is named INSIDE `args`, which is the one object there: args [{\"appId\": \"com.example.app\"}] on Android, args [{\"bundleId\": \"com.example.app\"}] on iOS. Sending appId or bundleId as a top-level body field is refused here before anything is sent \u2014 \"unknown body: bundleId. accepted: args, script\" \u2014 and sending the wrong one for the platform is refused by the product with a 400 \"invalid argument\" naming the parameter it wanted, with no action taken.",
      "Launching an app that is already in the foreground does nothing and still reports success.",
      "To restart an app from a clean state, call terminate_app first and then this.",
      "Succeeding means the app was activated, not that it finished drawing, so give it a moment and confirm before acting. An app that cannot be brought forward at all answers 400 rather than reporting success, and get_app_state reads 4 once it really is in front \u2014 sampled too early it can still report the home screen mid-switch.",
@@ -1882,7 +2163,7 @@
     "entity": "app_session",
     "intent": "Close an app and stop it running \u2014 use this to end a session inside the app, or as the first half of a restart.",
     "guidance": [
-     "Android takes appId and iOS takes bundleId \u2014 send exactly the one for the platform. The wrong name is refused with a 400 \"invalid argument\" that names the parameter it wanted, and no action is taken.",
+     "The app is named INSIDE `args`, which is the one object there: args [{\"appId\": \"com.example.app\"}] on Android, args [{\"bundleId\": \"com.example.app\"}] on iOS. Sending appId or bundleId as a top-level body field is refused here before anything is sent \u2014 \"unknown body: bundleId. accepted: args, script\" \u2014 and sending the wrong one for the platform is refused by the product with a 400 \"invalid argument\" naming the parameter it wanted, with no action taken.",
      "Returns true when the app was running and false when it was not; false is not an error.",
      "The app stays installed and keeps its data; only the running process is stopped.",
      "This does not clear state between runs \u2014 relaunching shows the app where it was unless the app itself resets."
@@ -1954,7 +2235,7 @@
     "entity": "app_session",
     "intent": "Check whether an app is installed, running or in the foreground \u2014 use this to confirm a launch or a close actually took effect.",
     "guidance": [
-     "Android takes appId and iOS takes bundleId \u2014 send exactly the one for the platform. The wrong name is refused with a 400 \"invalid argument\" that names the parameter it wanted, and no action is taken.",
+     "The app is named INSIDE `args`, which is the one object there: args [{\"appId\": \"com.example.app\"}] on Android, args [{\"bundleId\": \"com.example.app\"}] on iOS. Sending appId or bundleId as a top-level body field is refused here before anything is sent \u2014 \"unknown body: bundleId. accepted: args, script\" \u2014 and sending the wrong one for the platform is refused by the product with a 400 \"invalid argument\" naming the parameter it wanted, with no action taken.",
      "The value is a number: 0 not installed, 1 installed but not running, 2 running in the background and suspended, 3 running in the background, 4 running in the foreground.",
      "4 is the only state in which the app is on screen and can be driven.",
      "The same scale applies on both platforms. Sending an app to the background leaves it at 3 or 2 \u2014 the system suspends it a moment after it stops being visible \u2014 so treat anything below 4 as not on screen rather than waiting for one number. Launching it again returns it to 4."
@@ -2174,7 +2455,7 @@
      "The session must have been started with enable_biometric true; it cannot be turned on once the session is running.",
      "Call it only while the prompt is actually on screen \u2014 with no prompt showing it fails with BROWSERSTACK_COMMAND_EXECUTION_FAILED.",
      "biometricMatch takes \"pass\" or \"fail\"; \"fail\" is how to exercise the app's rejection path.",
-     "Read the page source afterwards to see what the app did with the answer.",
+     "Afterwards, find the element the app shows on success or on failure to see what it did with the answer.",
      "Every failure seen so far reports the same BROWSERSTACK_COMMAND_EXECUTION_FAILED regardless of cause, so it does not distinguish 'no prompt on screen' from 'the session was not started with enable_biometric'. Check both."
     ],
     "path_params": [
@@ -2367,7 +2648,7 @@
     "guidance": [
      "iOS only; press_keycode is the Android equivalent and the two are not interchangeable.",
      "The button names carry no separator: home, volumeup, volumedown.",
-     "Pressing home sends the app to the background \u2014 bring it back with launch_app, passing bundleId rather than appId, and confirm from the page source that the app is in front again.",
+     "Pressing home sends the app to the background \u2014 bring it back with launch_app, whose args object takes bundleId rather than appId on iOS, and confirm the app is in front again by finding one of its elements.",
      "The response is null on success and says nothing about what the button did."
     ],
     "path_params": [
@@ -2549,7 +2830,8 @@
      "Only `getprop <property>` can be expressed: the accepted form is fixed, and a command that lists apps or system state cannot be sent through this capability. A public phone is shared between customers, and commands such as `pm list packages` or `dumpsys` report what other people's sessions left behind.",
      "BrowserStack applies its own allow-list on top of this one and accepts only some properties on a shared phone; ro.build.version.release and ro.product.manufacturer are accepted, while a bare getprop is not. A property it refuses comes back as an execution failure rather than an empty value.",
      "The device name and OS version are already in the session record, so get_session answers those without this.",
-     "The whole line must be sent exactly as shown, with no extra spaces: it is matched against a fixed form."
+     "The whole line must be sent exactly as shown, with no extra spaces: it is matched against a fixed form.",
+     "The allowed property list is narrow and locale is not on it: getprop persist.sys.locale and getprop ro.product.locale both come back HTTP 500, \"BROWSERSTACK_UNSUPPORTED_ADB_SHELL_COMMAND ... is not supported on BrowserStack currently\". ro.build.version.release and ro.product.manufacturer do work, so treat the refusal as a per-property allow-list rather than a broken capability."
     ],
     "path_params": [
      {
@@ -2601,14 +2883,25 @@
     "encoding": "multipart",
     "local_only": true,
     "intent": "Upload an app build that is on this machine to App Automate and get back the bs:// URL a session installs \u2014 use this when the .apk, .aab or .ipa is a local file rather than a download link.",
-    "guidance": [
-     "The file must sit inside the directory MCP_UPLOAD_BASE_DIR names. When that is not set the upload is refused and nothing is sent: tell the user to set it to the folder holding their builds and restart the server, then move the build there.",
-     "When it is set but the build is somewhere else, the refusal names the directory the file has to be inside. Tell the user to move it there rather than trying another path.",
-     "Only .apk, .aab and .ipa are accepted, and no part of the path may be a hidden folder, so a build under a dot-directory has to be moved out of it.",
-     "The path is checked before anything is uploaded and before the user is asked to approve, so a refusal costs nothing and means the file was never read.",
-     "upload_app_build takes a public https link instead and is the one to use when the build is not on this machine.",
-     "A large build takes minutes, because the call does not return until the whole file has been sent."
-    ],
+    "guidance": {
+     "shared": [
+      "Only .apk, .aab and .ipa are accepted.",
+      "A large build takes minutes, because the upload does not return until the whole file has been sent.",
+      "upload_app_build takes a public https link instead, and list_app_builds reuses a build already on the account \u2014 builds last 30 days."
+     ],
+     "local": [
+      "The file must sit inside the directory MCP_UPLOAD_BASE_DIR names. When that is not set the upload is refused and nothing is sent: tell the user to set it to the folder holding their builds and restart the server.",
+      "When it is set but the build is somewhere else, the refusal names the directory the file has to be inside. Tell the user to move it there rather than trying another path.",
+      "No part of the path may be a hidden folder, so a build under a dot-directory has to be moved out of it.",
+      "The path is checked before anything is uploaded and before the user is asked to approve, so a refusal costs nothing and means the file was never read."
+     ],
+     "remote": [
+      "Cheapest route first: list_app_builds or list_team_app_builds, if the build was uploaded before.",
+      "Then upload_app_build, if the build sits at a public https link \u2014 the only route that needs nothing from the user.",
+      "Otherwise the user uploads it themselves. The asset-upload helper PRINTS a curl command and nothing more \u2014 it reads no file and sends no request \u2014 so the user runs that command, and it answers with the bs:// url directly from /app-automate/upload. There is no intermediate storage and no second step.",
+      "Take the bs:// url back from them and pass it as the app for create_session."
+     ]
+    },
     "body": [
      {
       "name": "file",
@@ -2640,8 +2933,7 @@
      "401": {
       "$response": "Unauthorized"
      }
-    },
-    "unavailable_note": "This server does not run on your own machine, so it cannot read a file you name \u2014 a path sent here would point at the machine hosting the server. Upload the build yourself with a multipart request carrying the file to the same endpoint, which the asset-upload helper will write out for you, and then use the bs:// url it returns as the app for create_session. upload_app_build does the same thing from a public download link, if the build is reachable at one."
+    }
    },
    {
     "name": "find_elements",
@@ -2703,6 +2995,144 @@
       "$response": "WebDriverError"
      }
     }
+   },
+   {
+    "name": "get_element_text",
+    "method": "GET",
+    "path": "/wd/hub/session/{session_id}/element/{element_id}/text",
+    "mode": "read",
+    "entity": "app_session",
+    "intent": "Read the visible text of an element on the screen \u2014 use this to check a label, a title, a price, a field's current contents or an error message without reading the whole screen.",
+    "guidance": [
+     "THIS IS HOW TO READ THE SCREEN: find_element gives the id, this gives what it says \u2014 one line per call, nothing to wade through.",
+     "On Android it is the text of the view; a container answers with an empty string, not its children's text, so aim at the TextView itself (class name android.widget.TextView, or the element by its own text).",
+     "On iOS it is the element's label or value \u2014 a text field answers with what it currently holds, or its placeholder when empty.",
+     "To confirm an action did something, read the same element before and after, or find the text you expect with find_element by text and treat \"no such element\" as the answer."
+    ],
+    "path_params": [
+     {
+      "name": "session_id",
+      "type": "string",
+      "required": true,
+      "example": "0123456789abcdef0123456789abcdef01234567"
+     },
+     {
+      "name": "element_id",
+      "type": "string",
+      "required": true,
+      "description": "Element id from find_element or find_elements.",
+      "example": "00000000-0000-0001-ffff-ffff00000012"
+     }
+    ],
+    "returns": [
+     "value"
+    ],
+    "responses": {
+     "200": {
+      "description": "The element's visible text.",
+      "schema": {
+       "$schema": "StringValueResponse"
+      }
+     },
+     "404": {
+      "$response": "WebDriverError"
+     }
+    }
+   },
+   {
+    "name": "get_element_rect",
+    "method": "GET",
+    "path": "/wd/hub/session/{session_id}/element/{element_id}/rect",
+    "mode": "read",
+    "entity": "app_session",
+    "intent": "Get an element's position and size on the screen \u2014 use this to aim a swipe, drag or tap with perform_actions, or to tell whether something sits under the keyboard.",
+    "guidance": [
+     "The coordinates are in the same space perform_actions uses: device pixels on Android, points on iOS \u2014 so x + width / 2 and y + height / 2 is the element's centre, ready to press.",
+     "One call per element: the coordinates to aim at, without reading the whole screen.",
+     "An element that is off screen still has a rect \u2014 one outside get_window_rect's size \u2014 so compare the two before tapping; scroll_gesture or scroll_view brings it on."
+    ],
+    "path_params": [
+     {
+      "name": "session_id",
+      "type": "string",
+      "required": true,
+      "example": "0123456789abcdef0123456789abcdef01234567"
+     },
+     {
+      "name": "element_id",
+      "type": "string",
+      "required": true,
+      "description": "Element id from find_element or find_elements.",
+      "example": "00000000-0000-0001-ffff-ffff00000012"
+     }
+    ],
+    "returns": [
+     "value.x",
+     "value.y",
+     "value.width",
+     "value.height"
+    ],
+    "responses": {
+     "200": {
+      "description": "The element's rectangle on screen.",
+      "schema": {
+       "$schema": "RectResponse"
+      }
+     },
+     "404": {
+      "$response": "WebDriverError"
+     }
+    }
+   },
+   {
+    "name": "get_element_attribute",
+    "method": "GET",
+    "path": "/wd/hub/session/{session_id}/element/{element_id}/attribute/{name}",
+    "mode": "read",
+    "entity": "app_session",
+    "intent": "Read one attribute of an element \u2014 use this for its resource id, content description, enabled, checked, selected or displayed state, or on iOS its name, label, value or visibility.",
+    "guidance": [
+     "The attribute names are the platform's own: on Android text, content-desc, resource-id, class, package, bounds, checked, checkable, clickable, enabled, focused, selected, displayed, scrollable, long-clickable, password; on iOS name, label, value, type, enabled, visible, accessible, focused, index, rect.",
+     "Booleans come back as the strings \"true\" and \"false\", not JSON booleans, so compare as text.",
+     "An attribute the element does not carry answers the STRING \"null\" on Android \u2014 not a JSON null and not an error \u2014 so compare as text; measured on an ImageView's resource-id.",
+     "For the element's text use get_element_text and for its position get_element_rect; this is for everything else."
+    ],
+    "path_params": [
+     {
+      "name": "session_id",
+      "type": "string",
+      "required": true,
+      "example": "0123456789abcdef0123456789abcdef01234567"
+     },
+     {
+      "name": "element_id",
+      "type": "string",
+      "required": true,
+      "description": "Element id from find_element or find_elements.",
+      "example": "00000000-0000-0001-ffff-ffff00000012"
+     },
+     {
+      "name": "name",
+      "type": "string",
+      "required": true,
+      "description": "The attribute to read, as named in the UI tree.",
+      "example": "content-desc"
+     }
+    ],
+    "returns": [
+     "value"
+    ],
+    "responses": {
+     "200": {
+      "description": "The attribute's value as a string; an absent one is the string \"null\" on Android.",
+      "schema": {
+       "$schema": "NullableStringResponse"
+      }
+     },
+     "404": {
+      "$response": "WebDriverError"
+     }
+    }
    }
   ],
   "schemas": {
@@ -3147,6 +3577,33 @@
       }
      }
     }
+   },
+   "SessionDeletedResponse": {
+    "type": "object",
+    "description": "What the hub returns when a session is closed. Not the W3C null: state says whether it closed and value is an empty string.",
+    "properties": {
+     "state": {
+      "type": "string",
+      "description": "\"success\" when the session was closed."
+     },
+     "status": {
+      "type": "integer",
+      "description": "The hub's own legacy status code; 0 on success."
+     },
+     "value": {
+      "type": "string",
+      "description": "Always empty on success."
+     }
+    }
+   },
+   "NullableStringResponse": {
+    "type": "object",
+    "properties": {
+     "value": {
+      "type": "string",
+      "description": "Null when the attribute is absent."
+     }
+    }
    }
   },
   "responses": {
@@ -3222,7 +3679,14 @@
      "get_simulated_location",
      "get_active_app_info",
      "read_device_property",
-     "find_elements"
+     "find_elements",
+     "get_element_text",
+     "get_element_rect",
+     "get_element_attribute",
+     "clear_element",
+     "scroll_gesture",
+     "dismiss_keyboard_key",
+     "scroll_view"
     ]
    },
    "device": {