device-devtools-mcp 0.1.0

package/scripts/ios/lib.sh

@@ -0,0 +1,864 @@
+#!/usr/bin/env bash
+# DeviceTools — iOS adapter internals: everything that knows about WebDriverAgent.
+#
+# Sourced by the scripts in this directory, never by anything above it. The
+# platform-neutral half lives in ../lib.sh and is sourced from here, so an
+# adapter script sources exactly one file.
+
+source "$(dirname "${BASH_SOURCE[0]}")/../lib.sh"
+
+wda_base() {
+  printf 'http://%s:%s' "$(cfg '.wda.host' '127.0.0.1')" "$(cfg '.wda.local_port' '8100')"
+}
+
+# One timeout for every request is wrong, measured rather than assumed: reading
+# the tree takes ~1.9s, while terminating the app under test was observed taking
+# ~60s before XCUITest gave its own answer. A 10s ceiling on the second aborts
+# the client while WebDriverAgent is still working, and reports a stuck driver
+# that is not stuck.
+#
+# So callers that perform a slow operation raise the ceiling for themselves by
+# exporting DT_HTTP_TIMEOUT. Reads keep the short one, where a hang really does
+# mean something is wrong.
+http_timeout() { printf '%s' "${DT_HTTP_TIMEOUT:-$(cfg '.timeouts.http_seconds' '10')}"; }
+
+# wda_fail <curl-exit> <path> — one line saying what actually went wrong.
+#
+# "Unreachable" and "did not answer in time" call for different reactions, and
+# collapsing them into one message sends the caller to restart a driver that is
+# in fact running. curl 7 is a refused connection; 28 is a timeout, which for
+# WebDriverAgent usually means a request it cannot satisfy — typing with nothing
+# focused, for instance — rather than a dead process.
+wda_fail() {
+  case "$1" in
+    28) die "WebDriverAgent did not answer within $(http_timeout)s at $2 — it is running but stuck on this request" 3 ;;
+    7)  die "WebDriverAgent unreachable at $2 (connection refused) — run $(as_cmd doctor)" 3 ;;
+    *)  die "WebDriverAgent request failed at $2 (curl $1) — run $(as_cmd doctor)" 3 ;;
+  esac
+}
+
+# wda_get <path> — prints the response body, exit 3 when the request fails.
+wda_get() {
+  local body rc=0
+  body="$(curl -sS -m "$(http_timeout)" "$(wda_base)$1" 2>/dev/null)" || rc=$?
+  [ "$rc" -eq 0 ] || wda_fail "$rc" "$(wda_base)$1"
+  printf '%s' "$body"
+}
+
+# wda_post <path> <json-body>
+wda_post() {
+  local body rc=0
+  body="$(curl -sS -m "$(http_timeout)" -X POST -H 'Content-Type: application/json' \
+      -d "$2" "$(wda_base)$1" 2>/dev/null)" || rc=$?
+  [ "$rc" -eq 0 ] || wda_fail "$rc" "$(wda_base)$1"
+  printf '%s' "$body"
+}
+
+device_udid() { cfg '.device.udid'; }
+
+# ios_kind — "device" or "simulator", resolving "auto" by asking simctl.
+#
+# Resolution is cached in a variable rather than a file: it is one simctl call
+# per script run, and a wrong answer cached on disk would outlive the reason it
+# was wrong.
+IOS_KIND=""
+ios_kind() {
+  if [ -z "$IOS_KIND" ]; then
+    case "$(target_kind)" in
+      device)    IOS_KIND=device ;;
+      simulator) IOS_KIND=simulator ;;
+      auto)
+        if xcrun simctl list devices -j 2>/dev/null | jq -e --arg u "$(device_udid)" \
+             '[.devices[][] | select(.udid == $u)] | length > 0' >/dev/null 2>&1; then
+          IOS_KIND=simulator
+        else
+          IOS_KIND=device
+        fi
+        ;;
+      *) die "device.kind must be auto, device or simulator, got: $(target_kind)" 2 ;;
+    esac
+  fi
+  printf '%s' "$IOS_KIND"
+}
+
+# The two builds cannot share a derived data directory: one targets
+# iphoneos and the other iphonesimulator, and the second would overwrite the
+# first's .xctestrun. Derived from one config key rather than needing two.
+wda_derived() {
+  local base
+  base="$(expand_path "$(cfg '.wda.derived_data' '~/tools/wda-derived')")"
+  if [ "$(ios_kind)" = simulator ]; then
+    printf '%s-simulator' "$base"
+  else
+    printf '%s' "$base"
+  fi
+}
+
+# sim_booted — true when the configured simulator is booted.
+# ASKED TWICE, BECAUSE SIMCTL SOMETIMES DOES NOT ANSWER. Under load — another
+# simctl call in flight, a simulator booting — `simctl list -j` returns nothing
+# at all, and reading that as "the device is not booted" fails a doctor
+# against a simulator that is running fine. Seen once, during an exploration
+# run. An empty answer is retried; a real answer is believed immediately.
+sim_booted() {
+  local out attempt=0
+  while [ "$attempt" -lt 2 ]; do
+    out="$(xcrun simctl list devices -j 2>/dev/null || true)"
+    if [ -n "$out" ] && printf '%s' "$out" | jq -e . >/dev/null 2>&1; then
+      printf '%s' "$out" | jq -e --arg u "$(device_udid)" \
+        '[.devices[][] | select(.udid == $u and .state == "Booted")] | length > 0' >/dev/null 2>&1
+      return $?
+    fi
+    attempt=$(( attempt + 1 ))
+    sleep 0.5
+  done
+  return 1
+}
+
+# --- the tree ----------------------------------------------------------------
+#
+# Flattening and normalisation live here, in one jq program, so that tree.sh's
+# output and every selector match are derived from exactly the same view of the
+# tree. A label copied out of tree.sh output therefore always matches.
+#
+# Labels come from application copy and can contain newlines and pipes, both of
+# which would break the line-oriented contract, so they are neutralised at the
+# point the tree is read rather than at each point it is consumed.
+JQ_CLEAN='
+  def clean:
+    if . == null then ""
+    elif type != "string" then tostring
+    else gsub("[\n\r\t]+"; " ") | gsub("\\|"; "/") | gsub("  +"; " ")
+         | ltrimstr(" ") | rtrimstr(" ")
+    end;
+  def walk($d):
+    [ { d: $d,
+        t:  (.type          | clean),
+        id: (.rawIdentifier | clean),
+        lb: (.label         | clean),
+        v:  (.value         | clean),
+        x: (.rect.x // 0), y: (.rect.y // 0),
+        w: (.rect.width // 0), h: (.rect.height // 0),
+        vis: ((.isVisible // "") == "1"),
+        en:  ((.isEnabled // "") == "1")
+      } ]
+    + ([ (.children // [])[] | walk($d + 1) ] | add // []);
+'
+
+# The XCUIElement types a user can act on. Kept as an explicit list rather than
+# a pattern, so that adding one is a decision someone made rather than a regex
+# quietly widening. Shared by controls.sh, which lists them, and tree.sh, which
+# must not hide them: a production app's welcome screen was found with three
+# unlabelled buttons and nothing else, and the tree showed none of them.
+DT_TAPPABLE_TYPES='Button|TextField|SecureTextField|SearchField|Switch|Link|MenuItem|Slider|Stepper|SegmentedControl|PageIndicator|Picker|PickerWheel|CheckBox|RadioButton|Toggle|TextView'
+
+# fetch_source — the raw tree. Internal only: nothing may print this. One screen
+# measured 107 KB against the target app, which is why tree.sh exists at all.
+# THE SESSION'S TREE, NOT THE SYSTEM'S.
+#
+# `GET /source` with no session in the path is WebDriverAgent's system-wide
+# hierarchy: springboard, the app switcher, the home grabber, every window iOS
+# has open. `GET /session/<id>/source` is the active application's.
+#
+# Measured, from an agent that got the app to the foreground and then read the
+# screen: screenshot showed a full-screen login form, snapshot showed
+# SBSwitcherWindow and AppSwitcherContentView, and `--all` returned ninety
+# unlabelled Other nodes. Every tap, measure and type after that was reasoning
+# about a tree belonging to a different process.
+#
+# The second symptom names the same cause: nodes measuring 1284x2778 sat beside
+# nodes measuring 428x926 in one tree. Those are the same screen in pixels and
+# in points — window_size already went through the session and answered in
+# points, while this went around it and answered in whatever each window used.
+fetch_source() {
+  local src
+  src="$(session_get '/source?format=json')"
+  printf '%s' "$src" | jq -e '.value' >/dev/null 2>&1 \
+    || die "WebDriverAgent returned no tree — run $(as_cmd doctor)" 3
+  printf '%s' "$src"
+}
+
+# try_fetch_source — like fetch_source, but returns 1 instead of dying.
+#
+# For advisory work that must not kill an operation which already succeeded: a
+# screenshot that was written is still a screenshot, even if the check that
+# annotates it could not run.
+try_fetch_source() {
+  local sid body rc=0
+  # The cached session only. Creating one here would make an advisory check that
+  # is allowed to fail into something that can fail loudly, and reading the
+  # system tree instead would answer a different question than the caller asked.
+  sid="$(cat "$(session_file)" 2>/dev/null || true)"
+  [ -n "$sid" ] || return 1
+  body="$(curl -sS -m "$(http_timeout)" "$(wda_base)/session/$sid/source?format=json" 2>/dev/null)" || rc=$?
+  [ "$rc" -eq 0 ] || return 1
+  printf '%s' "$body" | jq -e '.value' >/dev/null 2>&1 || return 1
+  printf '%s' "$body"
+}
+
+# --- what is inside a bundle, and what will let it onto a phone ---------------
+#
+# DeviceTools does not build. It does have to say why a build will not install,
+# because it is the only party that can see the bundle and the device at once,
+# and the errors iOS gives for this are `ApplicationVerificationFailed` and
+# `MismatchedApplicationIdentifierEntitlement`, which name neither.
+
+# bundle_facts <path> — "id|version|build|team|signed", or non-zero.
+bundle_facts() {
+  local p="$1" plist id ver bld team sig
+  plist="$p/Info.plist"
+  [ -f "$plist" ] || return 1
+  id="$(plutil -extract CFBundleIdentifier raw -o - "$plist" 2>/dev/null || true)"
+  ver="$(plutil -extract CFBundleShortVersionString raw -o - "$plist" 2>/dev/null || true)"
+  bld="$(plutil -extract CFBundleVersion raw -o - "$plist" 2>/dev/null || true)"
+  if codesign -dv "$p" >/dev/null 2>&1; then
+    sig=signed
+    team="$(codesign -dv --verbose=4 "$p" 2>&1 | sed -n 's/^TeamIdentifier=//p' | head -1)"
+    [ "$team" = "not set" ] && team=""
+  else
+    sig=unsigned
+    team=""
+  fi
+  printf '%s|%s|%s|%s|%s' "$id" "$ver" "$bld" "$team" "$sig"
+}
+
+# install_record / last_install — what DeviceTools put on this phone, and when.
+#
+# The device does not volunteer a version: reading one back needs
+# ideviceinstaller, which is a separate install and is usually absent. So this
+# records what it installed and says that is what it is — "installed by
+# DeviceTools at T" is a smaller claim than "the phone is running T", and it is
+# one that is true.
+install_record() { printf '%s/installed.tsv' "$(state_dir)"; }
+last_install() { cat "$(install_record)" 2>/dev/null || true; }
+
+# content_digest <source> — one number over the type, label and value of every
+# visible element. Changes when the screen's contents change, including in ways
+# the screen hash deliberately ignores: the screen hash answers "am I still on
+# the same screen", and a field filling up is the same screen.
+content_digest() {
+  printf '%s' "$1" | jq -r "$JQ_CLEAN"'
+    (.value | walk(0)) | map(select(.vis))
+    | map("\(.t)\u001f\(.lb)\u001f\(.v)") | join("\u001e")
+  ' 2>/dev/null | cksum | awk '{ print $1 }'
+}
+
+# match_elements <source> <kind> <value>
+# One line per exact, visible, non-degenerate match:
+#   x|y|w|h|type|id|label|text
+#
+# Matching is exact rather than substring on purpose. On the first screen this
+# was tested against, "Đăng nhập" is both a Button and the StaticText nested
+# inside it; a substring match that quietly takes the first candidate taps the
+# label instead of the button, depending on tree order. That is the worst
+# available failure mode, because it mostly works.
+match_elements() {
+  if [ "$2" = holding ]; then holding_elements "$1" "$3"; return; fi
+  printf '%s' "$1" | jq -r --arg kind "$2" --arg val "$3" "$JQ_CLEAN"'
+    (.value | walk(0))
+    | map(select(.vis and .w > 0 and .h > 0))
+    | map(select(
+        if   $kind == "id"   then .id == $val
+        elif $kind == "kind" then .t  == $val
+        elif $kind == "text" then .v  == $val
+        else                      .lb == $val end))
+    | .[]
+    | "\(.x)|\(.y)|\(.w)|\(.h)|\(.t)|\(.id)|\(.lb)|\(.v)"
+  '
+}
+
+# holding_elements <source> <text> — the control that contains that text.
+#
+# The anchor is matched WITHOUT the visibility filter, because the whole reason
+# this exists is that XCUITest calls a caption invisible when a sibling takes
+# its hit test. The container must still be visible and of a type a user can
+# act on; of those, the smallest containing one wins, so a caption inside a cell
+# inside a table resolves to the cell rather than the table.
+#
+# One result per anchor, deduplicated. Two separate controls holding the same
+# text stay two results, and the caller refuses to guess between them exactly as
+# it would for any other ambiguous selector.
+holding_elements() {
+  printf '%s' "$1" | jq -r --arg val "$2" --arg tappable "$DT_TAPPABLE_TYPES" "$JQ_CLEAN"'
+    (.value | walk(0)) as $all
+    | ($all | map(select(.w > 0 and .h > 0 and (.lb == $val or .v == $val)))) as $anchors
+    | ($all | map(select(.vis and .w > 0 and .h > 0
+                         and (.t | test("^(" + $tappable + ")$"))))) as $controls
+    | $anchors
+    | map(. as $a
+        | $controls
+        | map(select(.x <= $a.x and .y <= $a.y
+                     and (.x + .w) >= ($a.x + $a.w)
+                     and (.y + .h) >= ($a.y + $a.h)))
+        | sort_by(.w * .h)
+        | first)
+    | map(select(. != null))
+    | unique_by([.x, .y, .w, .h, .t])
+    | .[]
+    | "\(.x)|\(.y)|\(.w)|\(.h)|\(.t)|\(.id)|\(.lb)|\(.v)"
+  '
+}
+
+# keyboard_blocks <source> <x> <y> <w> <h> — "x y w h" of the keyboard when it
+# stands between the caller and that element, nothing when it does not.
+#
+# Free here: the keyboard is already in the tree that was fetched, so this costs
+# no round trip.
+#
+# MEMBERSHIP IS ANSWERED BY THE HIERARCHY, NOT BY THE TYPE. The obvious version
+# of this asked whether the element's type was Key — and on the first screen it
+# was tried against, the keyboard's own shift, Go, Emoji and Dictate are all
+# plain Buttons. Type would have refused four legitimate taps on the keyboard
+# while claiming to protect them. So the walk carries a flag down: anything
+# under the Keyboard element is the keyboard, whatever it calls itself.
+# drv_keyboard_dismiss — ask the keyboard to go away, then insist.
+#
+# WebDriverAgent's own dismiss works by pressing a Done or Return key, and an
+# app that offers neither simply keeps its keyboard: on the login screen
+# this was built against, the endpoint returned success and the keyboard stayed
+# up through a scroll as well.
+#
+# So the fallback is what a person does — tap the screen away from everything.
+# The point is COMPUTED, NOT GUESSED. Tapping a coordinate that happens to look
+# empty is exactly the wrong-tap-in-a-loop this project refuses; instead the
+# tree is asked which parts of the screen are spoken for, and the first place
+# nothing occupies is used. When every candidate is occupied, this gives up and
+# the verb reports that the keyboard stayed.
+drv_keyboard_dismiss() {
+  local src kb pt kbx kby kbw kbh
+  session_post '/wda/keyboard/dismiss' '{}' >/dev/null 2>&1
+  src="$(fetch_source)"
+  kb="$(keyboard_rect "$src")"
+  [ -n "$kb" ] || return 0
+  read -r kbx kby kbw kbh <<< "$kb"
+  pt="$(blank_point "$src" "$kby")"
+  [ -n "$pt" ] || return 0
+  # shellcheck disable=SC2086
+  drv_tap $pt >/dev/null 2>&1
+}
+
+# blank_point <source> <keyboard-top> — "x y" of a place on screen that no
+# element claims, above the keyboard, or nothing when there is no such place.
+#
+# "Claimed" is deliberately generous: anything a user can act on, anything with
+# an identifier, and anything carrying text. A custom control on iOS is often a
+# plain container with a gesture recogniser and nothing to distinguish it, so
+# the safe reading is that a labelled or identified region belongs to somebody.
+blank_point() {
+  local win_w win_h
+  read -r win_w win_h <<< "$(window_size "$1")"
+  printf '%s' "$1" | jq -r \
+    --argjson kby "$2" --argjson w "$win_w" --argjson h "$win_h" \
+    --arg tappable "$DT_TAPPABLE_TYPES" "$JQ_CLEAN"'
+    (.value | walk(0))
+    | map(select(.vis and .w > 0 and .h > 0
+                 and ((.t | test("^(" + $tappable + ")$"))
+                      or .id != "" or .lb != "" or .v != "")
+                 # A container the size of the window claims every point on the
+                 # screen and so claims none of them usefully. This login screen
+                 # carries a full-window Toolbar with both an identifier and a
+                 # label, which alone made the whole search fail. Same rule the
+                 # inspector uses to stop containers swallowing their contents.
+                 and (.w < ($w * 95 / 100) or .h < ($h * 90 / 100))))
+    as $taken
+    | ($w / 2 | floor) as $x
+    # Upward from just above the keyboard: the lower half of a form is where the
+    # padding lives, and the top is where the navigation bar is.
+    | [ range(($kby - 16); 60; -16) ]
+    | map(select(. as $y
+        | ($taken | any(.x <= $x and .y <= $y
+                        and (.x + .w) >= $x and (.y + .h) >= $y)) | not))
+    | first
+    | if . == null then empty else "\($x) \(.)" end
+  '
+}
+
+# keyboard_rect <source> — "x y w h" of the keyboard, or nothing when it is down.
+keyboard_rect() {
+  printf '%s' "$1" | jq -r "$JQ_CLEAN"'
+    (.value | walk(0))
+    | map(select(.t == "Keyboard" and .vis and .w > 0 and .h > 0))
+    | first
+    | if . == null then empty else "\(.x) \(.y) \(.w) \(.h)" end
+  '
+}
+
+keyboard_blocks() {
+  printf '%s' "$1" | jq -r \
+    --argjson tx "$2" --argjson ty "$3" --argjson tw "$4" --argjson th "$5" '
+    def walk($k):
+      ( ((.type // "") == "Keyboard") ) as $isk
+      | ( $isk or $k ) as $ink
+      | [ { isk: $isk, ink: $ink,
+            x: (.rect.x // 0), y: (.rect.y // 0),
+            w: (.rect.width // 0), h: (.rect.height // 0),
+            vis: ((.isVisible // "") == "1") } ]
+        + ([ (.children // [])[] | walk($ink) ] | add // []);
+    (.value | walk(false)) as $all
+    | ($all | map(select(.isk and .vis and .w > 0 and .h > 0)) | first) as $kb
+    | if $kb == null then empty
+      elif ($all | any(.ink and .x == $tx and .y == $ty and .w == $tw and .h == $th))
+        then empty
+      else
+        (($tx + $tw / 2) as $cx | ($ty + $th / 2) as $cy
+         | if $cx >= $kb.x and $cx <= ($kb.x + $kb.w)
+              and $cy >= $kb.y and $cy <= ($kb.y + $kb.h)
+           then "\($kb.x) \($kb.y) \($kb.w) \($kb.h)"
+           else empty end)
+      end
+  '
+}
+
+# unhittable_twin <source> <kind> <value> <x> <y> <w> <h> — the control this
+# selector really meant, when the caller is about to settle for a label instead.
+#
+# THE FAILURE THIS EXISTS FOR LOOKS EXACTLY LIKE SUCCESS.
+#
+# A login screen carries the words "Đăng nhập" twice: the title at the top and
+# the submit button at the bottom. With the keyboard up the driver reports the
+# button as not visible, so it is filtered out and the title is the only match
+# left. One match is not ambiguous, so nothing was refused: the run tapped the
+# title, the app did nothing, and the step printed OK. The baseline then
+# recorded the title as the right answer, so even the fingerprint agreed with
+# the mistake ever afterwards.
+#
+# The evidence was there the whole time — an actionable element with the same
+# words, present in the tree and unhittable. Only reported when the element
+# about to be tapped is not itself actionable: two buttons with one covered is a
+# different situation, and tapping the visible one is right.
+unhittable_twin() {
+  printf '%s' "$1" | jq -r --arg kind "$2" --arg val "$3" \
+    --argjson rx "$4" --argjson ry "$5" --argjson rw "$6" --argjson rh "$7" \
+    --arg tappable "$DT_TAPPABLE_TYPES" "$JQ_CLEAN"'
+    (.value | walk(0)) as $all
+    | ($all | map(select(.w > 0 and .h > 0 and (
+        if   $kind == "id"   then .id == $val
+        elif $kind == "kind" then .t  == $val
+        elif $kind == "text" then .v  == $val
+        else                      .lb == $val end)))) as $named
+    | ($named | map(select(.x == $rx and .y == $ry and .w == $rw and .h == $rh))
+              | first) as $self
+    | if ($self != null and ($self.t | test("^(" + $tappable + ")$"))) then empty
+      else
+        ( $named
+          | map(select((.vis | not) and (.t | test("^(" + $tappable + ")$"))))
+          | first
+          | if . == null then empty else "\(.t) at \(.x),\(.y),\(.w),\(.h)" end )
+      end
+  '
+}
+
+# named_anywhere <source> <kind> <value> — every element the selector names, with
+# the visibility filter off:
+#
+#   x|y|w|h|type|elements-sharing-that-exact-rect|visible
+#
+# Reached only after match_elements has already come back empty, so anything
+# here is either invisible or degenerate — which is precisely the distinction
+# `nothing on screen contains it` was failing to draw. See invisible_note.
+named_anywhere() {
+  printf '%s' "$1" | jq -r --arg kind "$2" --arg val "$3" "$JQ_CLEAN"'
+    (.value | walk(0)) as $all
+    | $all
+    | map(select(
+        if   $kind == "id"   then .id == $val
+        elif $kind == "kind" then .t  == $val
+        elif $kind == "text" then .v  == $val
+        elif $kind == "any"  then (.id == $val or .lb == $val or .v == $val)
+        else                      .lb == $val end))
+    | .[] as $e
+    | ($all | map(select(.x == $e.x and .y == $e.y and .w == $e.w and .h == $e.h)) | length) as $same
+    | "\($e.x)|\($e.y)|\($e.w)|\($e.h)|\($e.t)|\($same)|\(if $e.vis then 1 else 0 end)"
+  '
+}
+
+# text_anywhere <source> <text> — does that exact text exist at all, visible or
+# not? Used only to tell a `holding:` failure apart from a missing screen.
+text_anywhere() {
+  printf '%s' "$1" | jq -r --arg val "$2" "$JQ_CLEAN"'
+    (.value | walk(0))
+    | map(select(.lb == $val or .v == $val))
+    | .[] | "\(.x)|\(.y)|\(.w)|\(.h)|\(.t)"
+  '
+}
+
+# kinds_on_screen <source> — the element types present, commonest first, with
+# counts. The answer to a `kind:` that matched nothing: candidate_elements
+# searches identifiers, labels and values, so for a type it has nothing to say.
+kinds_on_screen() {
+  printf '%s' "$1" | jq -r "$JQ_CLEAN"'
+    (.value | walk(0))
+    | map(select(.vis and .w > 0 and .h > 0))
+    | group_by(.t) | map({t: .[0].t, n: length})
+    | sort_by(-.n) | .[] | "\(.t) x\(.n)"
+  ' 2>/dev/null | take_lines 8 | join_lines ', '
+}
+
+# candidate_elements <source> <value> [limit]
+# Near misses, for the message printed when an exact match fails. Being told
+# what is actually on screen is what lets a caller recover without a screenshot.
+# candidate_elements <source> <value> [n] — what is on screen that *contains*
+# the value, for the message printed when nothing matched it exactly.
+#
+# A candidate that some field matches EXACTLY is named with the selector that
+# would reach it. Reported from a real session: `tap text:8` was refused and the
+# suggestion list offered `Key "8"` — which is exactly the thing being asked
+# for, matching on its label rather than its value. Listing the answer without
+# saying how to spell it is a riddle, not a hint.
+candidate_elements() {
+  printf '%s' "$1" | jq -r --arg val "$2" "$JQ_CLEAN"'
+    (.value | walk(0))
+    | map(select(.vis and .w > 0 and .h > 0))
+    | map(select(.id != "" or .lb != "" or .v != ""))
+    | map(select(
+        ([.id, .lb, .v] | join(" ") | ascii_downcase) | contains($val | ascii_downcase)
+      ))
+    | .[]
+    | .t
+      + (if .id != "" then " #" + .id else "" end)
+      + (if .lb != "" then " \"" + .lb + "\"" else "" end)
+      + (if .v  != "" and .v != .lb then " =" + .v else "" end)
+      + (if   .id == $val then "  → try id:"    + $val
+         elif .lb == $val then "  → try label:" + $val
+         elif .v  == $val then "  → try text:"  + $val
+         else "" end)
+  ' | head -n "${3:-5}"
+}
+
+# --- sessions ----------------------------------------------------------------
+#
+# Every command that acts on the UI needs a session. Creating one per call costs
+# a round trip on every action, so the id is cached on disk and reused. The
+# cache is a hint and never truth: sessions die whenever the app or the runner
+# restarts, so a stale id is detected from the response and replaced once.
+session_file() { printf '%s/session.id' "$(state_dir)"; }
+
+wda_new_session() {
+  local resp sid
+  resp="$(wda_post '/session' '{"capabilities":{"alwaysMatch":{}}}')"
+  sid="$(printf '%s' "$resp" | jq -r '.value.sessionId // .sessionId // empty' 2>/dev/null || true)"
+  [ -n "$sid" ] || die "could not create a WebDriverAgent session — run $(as_cmd doctor)" 3
+  printf '%s' "$sid" > "$(session_file)"
+  printf '%s' "$sid"
+}
+
+# wda_drop_session — forget the cached session so the next call makes a new one.
+#
+# A session holds a reference to the application it was created against. Killing
+# that application leaves the reference dangling, and WebDriverAgent then
+# rejects a subsequent launch with "invalid argument" — an error that says
+# nothing about the real cause. Anything that ends an app's process must drop
+# the session with it.
+wda_drop_session() {
+  rm -f "$(session_file)" 2>/dev/null || true
+}
+
+wda_session() {
+  local f sid=""
+  f="$(session_file)"
+  [ -f "$f" ] && sid="$(cat "$f" 2>/dev/null || true)"
+  if [ -n "$sid" ]; then printf '%s' "$sid"; else wda_new_session; fi
+}
+
+# session_post <suffix> <json> — POST to /session/<id><suffix>, replacing the
+# session once if the cached one has expired.
+session_post() {
+  local sid resp err
+  sid="$(wda_session)"
+  resp="$(wda_post "/session/$sid$1" "$2")"
+  err="$(printf '%s' "$resp" | jq -r '.value.error // empty' 2>/dev/null || true)"
+  case "$err" in
+    "invalid session id"|"no such session"|"A session is either terminated or not started")
+      sid="$(wda_new_session)"
+      resp="$(wda_post "/session/$sid$1" "$2")"
+      ;;
+  esac
+  printf '%s' "$resp"
+}
+
+# session_get <suffix> — GET /session/<id><suffix>, replacing a stale session once.
+session_get() {
+  local sid resp err
+  sid="$(wda_session)"
+  resp="$(wda_get "/session/$sid$1")"
+  err="$(printf '%s' "$resp" | jq -r '.value.error // empty' 2>/dev/null || true)"
+  case "$err" in
+    "invalid session id"|"no such session"|"A session is either terminated or not started")
+      sid="$(wda_new_session)"
+      resp="$(wda_get "/session/$sid$1")"
+      ;;
+  esac
+  printf '%s' "$resp"
+}
+
+# session_error <response> — the WebDriverAgent error message, or empty.
+session_error() {
+  printf '%s' "$1" | jq -r '
+    if (.value | type) == "object" then (.value.error // .value.message // empty) else empty end
+  ' 2>/dev/null || true
+}
+
+
+# device_locale — the language and region the screen is currently rendered in,
+# normalised to en-US form. WDA answers for a simulator and a physical device
+# alike, which is why this asks the driver rather than ideviceinfo or simctl:
+# one source, and it is one that is already required to be running.
+#
+# Best-effort by contract. Every caller treats "" as "unknown" and carries on,
+# because provenance must never be the thing that fails a step.
+device_locale() {
+  local resp l
+  resp="$(wda_get '/wda/device/info' 2>/dev/null || true)"
+  l="$(printf '%s' "$resp" | jq -r '.value.currentLocale // empty' 2>/dev/null || true)"
+  printf '%s' "${l//_/-}"
+}
+
+# window_size [source] — "WIDTH HEIGHT" in the same coordinate space tree.sh prints.
+#
+# The argument is accepted and ignored. WebDriverAgent answers this with a
+# request, so a caller that already holds a tree cannot save anything by passing
+# it — but the Android adapter can, and does. The shared verbs call it the same
+# way on both platforms because that is the point of a shared verb.
+window_size() {
+  local resp w h
+  resp="$(session_get '/window/size')"
+  w="$(printf '%s' "$resp" | jq -r '.value.width // empty' 2>/dev/null || true)"
+  h="$(printf '%s' "$resp" | jq -r '.value.height // empty' 2>/dev/null || true)"
+  [ -n "$w" ] && [ -n "$h" ] \
+    || die "could not read the window size — run $(as_cmd doctor)" 3
+  printf '%s %s' "$w" "$h"
+}
+
+# tree_rows <source> — the tree in the one shape both platforms agree on:
+#
+#   depth|type|id|label|value|x|y|w|h
+#
+# Visible, non-degenerate elements only. This is what the resilient resolver in
+# ../lib.sh works on, and it is the reason that resolver can be written once:
+# the scoring never learns which platform produced the rows.
+tree_rows() {
+  printf '%s' "$1" | jq -r "$JQ_CLEAN"'
+    (.value | walk(0))
+    | map(select(.vis and .w > 0 and .h > 0))
+    | .[]
+    | "\(.d)|\(.t)|\(.id)|\(.lb)|\(.v)|\(.x)|\(.y)|\(.w)|\(.h)"
+  '
+}
+
+# --- gestures ----------------------------------------------------------------
+#
+# Four primitives, matching scripts/android/lib.sh name for name. Everything the
+# shared verbs in scripts/common/ do to the screen goes through one of them,
+# which is what lets those verbs exist without knowing that WebDriverAgent does.
+#
+# Each returns 0 on success, or prints one line and returns 1. They do not call
+# die: the caller decides what a failed gesture means and phrases it in terms of
+# what the caller was doing.
+
+# drv_tap <x> <y>
+drv_tap() {
+  local resp err
+  resp="$(session_post '/wda/tap' "$(printf '{"x":%s,"y":%s}' "$1" "$2")")"
+  err="$(session_error "$resp")"
+  [ -z "$err" ] && return 0
+  printf '%s' "$err"
+  return 1
+}
+
+# drv_drag <from-x> <from-y> <to-x> <to-y> <hold-ms> [travel-ms]
+#
+# WebDriverAgent takes the hold as seconds in a double; the argument is in
+# milliseconds because that is the unit gestures are actually described in.
+# `travel-ms` is accepted and ignored — WebDriverAgent does not expose the
+# travel time separately, while UiAutomator2 does.
+drv_drag() {
+  local resp err secs
+  secs="$(awk -v ms="$5" 'BEGIN { printf "%.3f", ms / 1000 }')"
+  resp="$(session_post '/wda/dragfromtoforduration' \
+    "$(jq -nc --argjson fx "$1" --argjson fy "$2" --argjson tx "$3" --argjson ty "$4" \
+       --argjson d "$secs" '{fromX: $fx, fromY: $fy, toX: $tx, toY: $ty, duration: $d}')")"
+  err="$(session_error "$resp")"
+  [ -z "$err" ] && return 0
+  printf '%s' "$err"
+  return 1
+}
+
+# drv_open_url <url> — hand a URL to the system to route.
+#
+# Opening a link can start another application, which takes as long as any other
+# launch, so this borrows the app timeout rather than the read timeout.
+drv_open_url() {
+  local resp err
+  resp="$(DT_HTTP_TIMEOUT="$(cfg '.timeouts.app_seconds' '90')" \
+    session_post '/url' "$(jq -nc --arg u "$1" '{url: $u}')")"
+  err="$(session_error "$resp")"
+  [ -z "$err" ] && return 0
+  printf '%s' "$err"
+  return 1
+}
+
+# drv_foreground_app — the bundle id now in front, or empty.
+drv_foreground_app() {
+  wda_get '/wda/activeAppInfo' 2>/dev/null | jq -r '.value.bundleId // empty' 2>/dev/null || true
+}
+
+# drv_fingerprint <source> — a number that changes when the screen changes.
+#
+# Deliberately excludes every element's value, and is sorted. Measured on an
+# idle login screen, a fingerprint that included values changed on every single
+# sample, because a carousel and a page indicator update themselves with nothing
+# touching the device. Structure — types, identifiers and labels — was identical
+# across the same samples. Including values would report every gesture as a
+# success.
+drv_fingerprint() {
+  printf '%s' "$1" | jq -r "$JQ_CLEAN"'
+    (.value | walk(0)) | map(select(.vis)) | map("\(.t)\(.id)\(.lb)") | sort | join("")' | cksum
+}
+
+# drv_fingerprint_pos <source> — as above, but including each element's y.
+#
+# For scrolling, where the structure is unchanged and only the position moves.
+drv_fingerprint_pos() {
+  printf '%s' "$1" | jq -r "$JQ_CLEAN"'
+    (.value | walk(0)) | map(select(.vis)) | map("\(.t)\(.id)\(.lb)\(.y)") | sort | join("")' | cksum
+}
+
+
+# --- the normalised screen -----------------------------------------------------
+#
+# snapshot_rows — every element on screen, in document order, in the one shape
+# both adapters agree on. This is the seam: scripts/snapshot.awk, measure.sh and
+# uid_resolve all read this and none of them can tell which driver produced it.
+#
+#   WINDOW|<w>|<h>|<orientation>
+#   <n>|<depth>|<parent-n>|<type>|<id>|<label>|<value>|<x>|<y>|<w>|<h>|<flags>
+#
+# <n> is a 1-based serial covering EVERY element, filtered or not. The display
+# filter runs downstream, and a warning like "outside parent [12]" has to be
+# able to name a container nobody asked to see.
+#
+# <flags> is a comma-separated subset of visible, enabled, actionable.
+snapshot_rows() {
+  local src w h orient
+  src="$(fetch_source)"
+
+  # The root element's rect is the screen. Asking the session for /window/size
+  # would be a second request, and a request that fails when no session is open
+  # — this has to work for a verb that only reads.
+  w="$(printf '%s' "$src" | jq -r '.value.rect.width // 0 | floor')"
+  h="$(printf '%s' "$src" | jq -r '.value.rect.height // 0 | floor')"
+  if [ "$w" -gt "$h" ] 2>/dev/null; then orient=landscape; else orient=portrait; fi
+  printf 'WINDOW|%s|%s|%s\n' "$w" "$h" "$orient"
+
+  # The parent is filled in by the awk pass below rather than threaded through
+  # the walk. jq's recursive walk cannot carry a running serial and a parent at
+  # once without rebuilding it, and the depth stack does the same job in a line.
+  printf '%s' "$src" | jq -r --arg tappable "$DT_TAPPABLE_TYPES" "$JQ_CLEAN"'
+    (.value | walk(0))
+    | to_entries
+    | map(.value + { n: (.key + 1) })
+    | .[]
+    | . as $e
+    | ([ (if $e.vis then "visible" else empty end),
+         (if $e.en  then "enabled" else empty end),
+         (if ($e.t | test("^(" + $tappable + ")$")) then "actionable" else empty end)
+       ] | join(",")) as $flags
+    | "\($e.n)|\($e.d)|0|\($e.t)|\($e.id)|\($e.lb)|\($e.v)|\($e.x|floor)|\($e.y|floor)|\($e.w|floor)|\($e.h|floor)|\($flags)"
+  ' | awk -F'|' -v OFS='|' '
+    # PARENT FROM DEPTH, DONE WITH A STACK. Keep the last serial seen at each
+    # depth: a row at depth d has whatever is at d-1 as its parent, and then
+    # becomes the entry for d itself. A subtree that ends needs no popping,
+    # because the next row at that depth overwrites the entry.
+    #
+    # The obvious alternative — "the previous row at depth-1" — picks the wrong
+    # parent the moment a subtree is empty.
+    { stack[$2] = $1
+      $3 = ($2 + 0 == 0) ? 0 : stack[$2 - 1] + 0
+      print }
+  '
+}
+
+# capture_png <path> — the screen, as a PNG, at the device's own resolution.
+#
+# Returns 2 when the file could not be written and 3 when the driver gave back
+# something that is not an image, so the caller can phrase each one in its own
+# terms. It does not call die: the caller decides what a failed capture means.
+capture_png() {
+  local out="$1" b64
+  b64="$(wda_get '/screenshot' | jq -r '.value // empty')" || return 3
+  [ -n "$b64" ] || return 3
+  printf '%s' "$b64" | base64 --decode > "$out" 2>/dev/null || return 2
+  # A PNG always starts with the same eight bytes. Checking them turns a
+  # truncated response or an error page into a clear failure now, rather than a
+  # file that fails somewhere else later.
+  [ "$(head -c 8 "$out" | od -An -tx1 | tr -d ' \n')" = "89504e470d0a1a0a" ] \
+    || { rm -f "$out"; return 3; }
+  return 0
+}
+
+# logs_since <unix-seconds> — what was logged after that moment.
+#
+# BEST-EFFORT, AND SILENT WHEN THERE IS NOTHING. Two rules hold here and both
+# matter:
+#
+#   * it never starts a collector. logs.sh starts one when you ask it to read,
+#     which is right for a verb somebody typed; doing it inside every tap would
+#     spawn a background process as a side effect of touching a button, and this
+#     device produces twenty-one thousand lines in thirty seconds.
+#   * it never fails. A log stream that will not open must not fail a tap that
+#     already landed on the phone.
+#
+# So an agent that wants the LOG section runs `logs start` once, and until then
+# actions simply do not carry one.
+#
+# The app filter is the last component of the bundle id, matched without regard
+# to case — com.example.demoapp against a process called DemoApp. That is a
+# heuristic and is named as one: iOS does not publish the process name for a
+# bundle id anywhere this can reach.
+# log_filter — from a device's whole syslog down to what the app said.
+#
+# A line looks like:
+#
+#   Aug 27 12:18:58.913302 DemoApp(CoreMotion)[78395] <Info>: message
+#   \_ timestamp ________/ \_ process _/\_ library _/
+#
+# TWO FILTERS, BECAUSE THE PROCESS NAME ALONE IS NOT ENOUGH.
+#
+# The old rule was `grep -i <app>`, matching the name anywhere on the line. That
+# is why an agent asking for the log after each action got eight lines of
+# hit-testing and accelerometer traffic: those lines DO carry the app's process
+# name, because the OS logged them on the app's behalf. Measured on a real
+# 40,775-line capture: the old rule kept 354 lines, of which 162 were attributed
+# to the app and every one of those came from a system framework —
+# CoreMotion 82, UIKitCore 64, RunningBoardServices 16 — and the app's own
+# logging, with no framework in parentheses, was zero lines.
+#
+# So the process has to be the app AND the framework has to not be one of the
+# ones that log on everybody's behalf. When that leaves nothing, nothing is the
+# answer: this app does not log, and eight lines of somebody else's telemetry is
+# a worse answer than none.
+log_filter() {
+  local app excl out
+  app="$(cfg '.app.bundle_id' '')"; app="${app##*.}"
+  excl="$(cfg '.logs.exclude_subsystems' \
+    'AXRuntime|UIAccessibility|AccessibilityUtilities|CoreMotion|UIKitCore|RunningBoardServices|CoreFoundation|CoreBrightness|CoreBluetooth|CoreTelephony|WirelessProximity|BackBoardHIDEventProcessors|MediaSafetyNet|WPDaemon|libsystem_network')"
+  out="$(cat)"
+  if [ -n "$app" ]; then
+    out="$(printf '%s\n' "$out" | grep -iE "^[A-Za-z]{3} +[0-9]+ +[0-9:.]+ +${app}[([]" || true)"
+  fi
+  if [ -n "$excl" ]; then
+    out="$(printf '%s\n' "$out" | grep -vEi "\(($excl)\)\[[0-9]+\]" || true)"
+  fi
+  printf '%s' "$out"
+}
+
+logs_since() {
+  local since="$1" f out
+  f="$(state_dir)/syslog.log"
+  [ -s "$f" ] || return 0
+  out="$(awk -F'\t' -v c="$since" '$1 >= c { sub(/^[0-9]+\t/, ""); print }' "$f" 2>/dev/null || true)"
+  [ -n "$out" ] || return 0
+  out="$(printf '%s\n' "$out" | log_filter)"
+  [ -n "$out" ] || return 0
+  printf '%s\n' "$out" | sed '/^[[:space:]]*$/d' | tail -8
+}