device-devtools-mcp 0.1.0

package/scripts/android/lib.sh

@@ -0,0 +1,699 @@
+#!/usr/bin/env bash
+# DeviceTools — Android adapter internals: everything that knows about adb and the
+# UiAutomator2 server.
+#
+# 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.
+#
+# WHY A SERVER ON THE DEVICE RATHER THAN PLAIN adb
+#
+# `adb shell uiautomator dump` needs nothing installed, and for reading the
+# screen it works. It was rejected on two measurements:
+#
+#   reading the tree    dump 4.3s        server 0.11s
+#   typing "Lê"     dump — impossible
+#
+# `adb shell input text` rejects every non-ASCII string. Four encodings were
+# tried; each returned "Exception occurred while executing 'text'" while the
+# same call with ASCII returned 0. For an app whose login screen is in
+# Vietnamese that is not a limitation, it is a disqualification.
+#
+# So Android gets the same shape as iOS: an HTTP driver installed on the device,
+# separate from the app under test. It is a separate application, so the rule
+# that no instrumentation code goes inside the app under test still holds.
+
+source "$(dirname "${BASH_SOURCE[0]}")/../lib.sh"
+
+ua2_base() {
+  printf 'http://%s:%s' "$(cfg '.ua2.host' '127.0.0.1')" "$(cfg '.ua2.local_port' '6790')"
+}
+
+http_timeout() { printf '%s' "${DT_HTTP_TIMEOUT:-$(cfg '.timeouts.http_seconds' '10')}"; }
+
+device_serial() { cfg '.device.serial'; }
+
+# adb_dev — adb bound to the configured device, and detached from stdin.
+#
+# Never bare `adb`: with two devices attached, bare adb fails, and with one
+# attached it succeeds against whichever one that is. A test suite that runs on
+# the wrong phone is worse than one that refuses to run.
+#
+# THE `< /dev/null` IS NOT DECORATION. `adb shell` forwards its standard input
+# to the device, so an adb call anywhere inside a pipeline eats the data flowing
+# through that pipeline. It was found here as log lines vanishing: a
+# `$(adb shell date +%z)` used to build an awk argument silently consumed every
+# record awk was about to format, and the command reported success with no
+# output. No adb invocation in this tool wants stdin, so it is closed for all of
+# them rather than remembered at each call site.
+adb_dev() { adb -s "$(device_serial)" "$@" < /dev/null; }
+
+# pkg_installed <package> — is exactly this package present on the device?
+#
+# ASK ABOUT ONE PACKAGE. NEVER LIST THEM ALL AND SEARCH THE LIST.
+#
+# `pm list packages` with no argument returns every package — 243 of them on a
+# CI emulator — and that output came back TRUNCATED, differently on two queries
+# seconds apart. One run could not find the UiAutomator2 server; the next found
+# the server but not its test harness; a plain `adb shell pm list packages` run
+# by hand two seconds earlier had listed all three packages involved, and `adb
+# install` had reported Success for both APKs. Nothing was wrong with the
+# device or with the matching. The list was simply not arriving whole.
+#
+# Passing the name filters it on the device, so the reply is one or two lines
+# and there is nothing to truncate. The filter is a substring match, so the
+# exact comparison still has to happen here — `…server` must not answer for
+# `…server.test`.
+pkg_installed() {
+  [ -n "${1:-}" ] || return 1
+  adb_dev shell pm list packages "$1" 2>/dev/null | tr -d '\r' | grep -qx "package:$1"
+}
+
+# android_kind — "device" or "emulator", resolving "auto" by asking the device.
+ANDROID_KIND=""
+android_kind() {
+  [ -n "$ANDROID_KIND" ] && { printf '%s' "$ANDROID_KIND"; return 0; }
+  local k
+  k="$(target_kind)"
+  case "$k" in
+    device|emulator) ANDROID_KIND="$k" ;;
+    auto)
+      # ro.kernel.qemu is set on emulators and absent on hardware; the serial
+      # prefix agrees, and checking both means a renamed serial cannot mislead.
+      if [ "$(adb_dev shell getprop ro.kernel.qemu 2>/dev/null | tr -d '\r')" = "1" ] \
+         || case "$(device_serial)" in emulator-*) true ;; *) false ;; esac; then
+        ANDROID_KIND=emulator
+      else
+        ANDROID_KIND=device
+      fi ;;
+    *) die "device.kind must be auto, device or emulator — got '$k'" 2 ;;
+  esac
+  printf '%s' "$ANDROID_KIND"
+}
+
+# ua2_fail <curl-exit> <url> — one line saying what actually went wrong.
+#
+# Unreachable and timed-out call for different reactions, and collapsing them
+# sends the caller to restart a server that is in fact running.
+ua2_fail() {
+  case "$1" in
+    28) die "UiAutomator2 did not answer within $(http_timeout)s at $2 — it is running but stuck on this request" 3 ;;
+    7)  die "UiAutomator2 unreachable at $2 (connection refused) — run $(as_cmd doctor)" 3 ;;
+    *)  die "UiAutomator2 request failed at $2 (curl $1) — run $(as_cmd doctor)" 3 ;;
+  esac
+}
+
+ua2_get() {
+  local body rc=0
+  body="$(curl -sS -m "$(http_timeout)" "$(ua2_base)$1" 2>/dev/null)" || rc=$?
+  [ "$rc" -eq 0 ] || ua2_fail "$rc" "$(ua2_base)$1"
+  printf '%s' "$body"
+}
+
+ua2_post() {
+  local body rc=0
+  body="$(curl -sS -m "$(http_timeout)" -X POST -H 'Content-Type: application/json' \
+      -d "${2:-\{\}}" "$(ua2_base)$1" 2>/dev/null)" || rc=$?
+  [ "$rc" -eq 0 ] || ua2_fail "$rc" "$(ua2_base)$1"
+  printf '%s' "$body"
+}
+
+# ua2_error <response> — the error as one short line, or empty on success.
+#
+# UiAutomator2 answers a failure with a full Java stack trace. One "no such
+# element" measured over 2,000 tokens of frames from io.appium.uiautomator2,
+# androidx.test and java.lang, none of which say anything about the app. Passing
+# that through would put a stack trace in the caller's context on every miss, so
+# only the error name and message survive, and the message is capped.
+ua2_error() {
+  printf '%s' "$1" | jq -r '
+    if (.value | type) == "object" and (.value.error // "") != "" then
+      (.value.error // "error")
+      + (if (.value.message // "") != ""
+         then ": " + ((.value.message | gsub("[\n\r\t]+"; " "))[:160])
+         else "" end)
+    else empty end' 2>/dev/null || true
+}
+
+# --- 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 when the instrumentation
+# restarts, so a stale id is detected from the response and replaced once.
+
+session_file() { printf '%s/session.id' "$(state_dir)"; }
+
+ua2_new_session() {
+  local resp sid err
+  resp="$(ua2_post '/session' '{"capabilities":{"alwaysMatch":{},"firstMatch":[{}]}}')"
+  err="$(ua2_error "$resp")"
+  [ -z "$err" ] || die "UiAutomator2 refused a new session — $err" 3
+  sid="$(printf '%s' "$resp" | jq -r '.value.sessionId // .sessionId // empty' 2>/dev/null)"
+  [ -n "$sid" ] || die "UiAutomator2 returned no session id — run $(as_cmd doctor)" 3
+  printf '%s' "$sid" > "$(session_file)"
+  printf '%s' "$sid"
+}
+
+ua2_drop_session() { rm -f "$(session_file)" 2>/dev/null || true; }
+
+ua2_session() {
+  local f sid
+  f="$(session_file)"
+  if [ -f "$f" ]; then
+    sid="$(cat "$f" 2>/dev/null || true)"
+    [ -n "$sid" ] && { printf '%s' "$sid"; return 0; }
+  fi
+  ua2_new_session
+}
+
+# session_get / session_post — a request under the current session, retried once
+# against a fresh session when the cached one turns out to be dead.
+session_get() {
+  local sid resp err
+  sid="$(ua2_session)"
+  resp="$(ua2_get "/session/$sid$1")"
+  err="$(ua2_error "$resp")"
+  case "$err" in
+    *"invalid session"*|*"session not"*|*"no such session"*|*"terminated"*)
+      ua2_drop_session
+      sid="$(ua2_new_session)"
+      resp="$(ua2_get "/session/$sid$1")" ;;
+  esac
+  printf '%s' "$resp"
+}
+
+session_post() {
+  local sid resp err
+  sid="$(ua2_session)"
+  resp="$(ua2_post "/session/$sid$1" "${2:-}")"
+  err="$(ua2_error "$resp")"
+  case "$err" in
+    *"invalid session"*|*"session not"*|*"no such session"*|*"terminated"*)
+      ua2_drop_session
+      sid="$(ua2_new_session)"
+      resp="$(ua2_post "/session/$sid$1" "${2:-}")" ;;
+  esac
+  printf '%s' "$resp"
+}
+
+# session_error — kept as a name shared with the iOS adapter so the verb scripts
+# read the same on both platforms.
+session_error() { ua2_error "$1"; }
+
+# --- reading the screen ------------------------------------------------------
+#
+# TREE_AWK converts UiAutomator's XML into the line table every verb consumes.
+# See tree.awk for why this is not a call to yq.
+TREE_AWK="$(dirname "${BASH_SOURCE[0]}")/tree.awk"
+
+# fetch_source — the parsed line table, including the leading WINDOW line.
+#
+# Internal only: nothing may print this. It is already far smaller than the XML
+# it came from, but a full screen is still hundreds of lines.
+# AN EMPTY TREE IS A MISSING ANSWER, NOT AN ANSWER. ASK AGAIN.
+#
+# UiAutomator dumps the hierarchy of whatever is on screen at that instant, and
+# during a window transition that is briefly nothing at all — a valid XML
+# document describing no nodes. Treating it as "the screen has no controls"
+# turns a race into an assertion failure against a screen that is fine a
+# hundred milliseconds later.
+#
+# Measured on a GitHub Actions emulator: `assert visible
+# id:open_search_view_edit_text` failed here on the search screen opening, on a
+# suite that passes every time on a developer's machine. A slower device does
+# not have different windows, it has longer transitions.
+#
+# Three attempts, a short pause between them. It stays a hard failure if the
+# tree is genuinely empty, so a driver that has actually stopped answering is
+# still reported — this buys a transition time to finish, not silence.
+FETCH_SOURCE_TRIES=3
+
+fetch_source() {
+  local resp xml table i
+  i=1
+  while [ "$i" -le "$FETCH_SOURCE_TRIES" ]; do
+    resp="$(session_get '/source?format=xml')"
+    xml="$(printf '%s' "$resp" | jq -r '.value // empty' 2>/dev/null)"
+    if [ -n "$xml" ]; then
+      table="$(printf '%s' "$xml" | awk -f "$TREE_AWK")"
+      [ -n "$table" ] && { printf '%s' "$table"; return 0; }
+    fi
+    [ "$i" -lt "$FETCH_SOURCE_TRIES" ] && sleep 0.4
+    i=$((i + 1))
+  done
+  [ -n "$xml" ] || die "UiAutomator2 returned no tree — run $(as_cmd doctor)" 3
+  die "the screen hierarchy parsed to nothing $FETCH_SOURCE_TRIES times — run $(as_cmd doctor)" 3
+}
+
+# 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 resp xml table rc=0
+  sid="$(cat "$(session_file)" 2>/dev/null || true)"
+  [ -n "$sid" ] || return 1
+  resp="$(curl -sS -m "$(http_timeout)" "$(ua2_base)/session/$sid/source?format=xml" 2>/dev/null)" || rc=$?
+  [ "$rc" -eq 0 ] || return 1
+  xml="$(printf '%s' "$resp" | jq -r '.value // empty' 2>/dev/null)" || return 1
+  [ -n "$xml" ] || return 1
+  table="$(printf '%s' "$xml" | awk -f "$TREE_AWK")" || return 1
+  [ -n "$table" ] || return 1
+  printf '%s' "$table"
+}
+
+# window_size [source] — "<w> <h>", taken from the hierarchy root.
+#
+# iOS pays a request for this. Android does not: UiAutomator puts the window
+# size on the root node of the tree, so a caller that already holds a source can
+# pass it and pay nothing. The zero-argument form exists because that is the
+# shape the iOS adapter exposes, and a verb that works on both platforms must
+# not have to know which one it is talking to.
+window_size() {
+  local src="${1:-}"
+  [ -n "$src" ] || src="$(fetch_source)"
+  printf '%s' "$src" | awk -F'|' '$1 == "WINDOW" { print $2, $3; exit }'
+}
+
+# device_locale — the language and region the screen is currently rendered in,
+# normalised to en-US form.
+#
+# Two properties, in this order: persist.sys.locale is what the user last chose
+# in Settings, ro.product.locale is what the image shipped with. An emulator
+# nobody has touched has only the second — measured, not assumed.
+#
+# 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 l
+  l="$(adb_dev shell getprop persist.sys.locale 2>/dev/null | tr -d '\r' || true)"
+  [ -n "$l" ] || l="$(adb_dev shell getprop ro.product.locale 2>/dev/null | tr -d '\r' || true)"
+  printf '%s' "${l//_/-}"
+}
+
+# --- gestures ----------------------------------------------------------------
+#
+# Three primitives. Everything a verb does to the screen goes through one of
+# them, which is what keeps tap.sh, swipe.sh, scroll.sh and back.sh free of any
+# knowledge that UiAutomator2 exists.
+
+# drv_tap <x> <y>
+drv_tap() {
+  local resp err
+  resp="$(session_post '/actions' "$(printf '{"actions":[{"type":"pointer","id":"finger1","parameters":{"pointerType":"touch"},"actions":[{"type":"pointerMove","duration":0,"x":%s,"y":%s},{"type":"pointerDown","button":0},{"type":"pause","duration":80},{"type":"pointerUp","button":0}]}]}' "$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]
+#
+# The hold is the press before the drag begins; a short hold reads as a flick
+# and scrolls with momentum, a long one reads as a deliberate drag and does not.
+# The travel time is separate and is what actually decides how far a flick
+# carries, so both are exposed rather than conflated.
+drv_drag() {
+  local resp err travel="${6:-300}"
+  resp="$(session_post '/actions' "$(printf '{"actions":[{"type":"pointer","id":"finger1","parameters":{"pointerType":"touch"},"actions":[{"type":"pointerMove","duration":0,"x":%s,"y":%s},{"type":"pointerDown","button":0},{"type":"pause","duration":%s},{"type":"pointerMove","duration":%s,"x":%s,"y":%s},{"type":"pointerUp","button":0}]}]}' \
+      "$1" "$2" "$5" "$travel" "$3" "$4")")"
+  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.
+#
+# The URL is single-quoted for the shell that runs on the device, not just for
+# the one running here. A link with a query string reaches `am` as several words
+# otherwise, and `&` would background half of it — the sort of thing that works
+# for every URL in the examples and breaks on the first real deep link.
+drv_open_url() {
+  local out
+  out="$(adb_dev shell "am start -a android.intent.action.VIEW -d '$1'" 2>&1 | tr -d '\r' || true)"
+  case "$out" in
+    *Error*|*error*|*Exception*)
+      printf '%s' "$(printf '%s' "$out" | grep -m1 -i 'error\|exception')"
+      return 1 ;;
+  esac
+  return 0
+}
+
+# drv_foreground_app — the package now in front, or empty.
+drv_foreground_app() {
+  local line
+  line="$(adb_dev shell dumpsys window 2>/dev/null | tr -d '\r' | awk '/mCurrentFocus/ { print; exit }')"
+  printf '%s' "$line" | sed -n 's/.*[ {]\([a-zA-Z0-9_.]*\)\/[a-zA-Z0-9_.]*}.*/\1/p'
+}
+
+# drv_fingerprint <source> — a number that changes when the screen changes.
+#
+# Deliberately excludes every element's text, and is sorted. Measured on an idle
+# screen, a fingerprint that included text changed between consecutive samples
+# with nothing touching the device, because clocks and carousels update
+# themselves. Structure — types, identifiers and labels — was identical across
+# the same samples. Including text would report every gesture as a success.
+drv_fingerprint() {
+  printf '%s' "$1" | awk -F'|' '
+    $1 == "WINDOW" || $1 == "" { next }
+    $10 != 1 { next }
+    { print $2 $3 $4 }' | sort | 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" | awk -F'|' '
+    $1 == "WINDOW" || $1 == "" { next }
+    $10 != 1 { next }
+    { print $2 $3 $4 $7 }' | sort | cksum
+}
+
+# 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" | awk -F'|' '
+    $1 == "WINDOW" || $1 == "" { next }
+    $10 != 1 || $8 <= 0 || $9 <= 0 { next }
+    { printf "%s|%s|%s|%s|%s|%s|%s|%s|%s\n", $1, $2, $3, $4, $5, $6, $7, $8, $9 }'
+}
+
+# --- selectors ---------------------------------------------------------------
+#
+# strip_id_prefix — resource ids arrive fully qualified as
+# "com.example.app:id/login_button" and the table stores only the last part,
+# because the package is identical for every element of the app under test. A
+# selector written either way must work, so the selector is reduced the same
+# way before comparison rather than the table being expanded.
+strip_id_prefix() { printf '%s' "${1##*:id/}"; }
+
+# match_elements <source> <kind> <value>
+# One line per exact, visible, non-degenerate match:
+#   x|y|w|h|type|id|label|text
+#
+# The columns and their order are identical to the iOS adapter's, so every verb
+# above this line is written once.
+#
+# Matching is exact rather than substring on purpose. A screen measured here had
+# five elements whose id was "title"; a substring match that quietly takes the
+# first candidate taps whichever one document order happens to put first, which
+# is the worst available failure mode because it mostly works.
+# holding_elements <source> <text> — the control that contains that text.
+#
+# Android publishes `clickable`, so the container test is exact here rather than
+# inferred from the type. The anchor ignores visibility for the same reason as
+# on iOS: a caption drawn inside a control is still a caption.
+holding_elements() {
+  printf '%s' "$1" | awk -F'|' -v val="$2" '
+    $1 == "WINDOW" || $1 == "" { next }
+    {
+      n++
+      X[n] = $6; Y[n] = $7; W[n] = $8; H[n] = $9
+      T[n] = $2; ID[n] = $3; LB[n] = $4; V[n] = $5
+      VIS[n] = $10; CLK[n] = $13
+      if (($4 == val || $5 == val) && $8 > 0 && $9 > 0) A[++an] = n
+    }
+    END {
+      for (i = 1; i <= an; i++) {
+        a = A[i]; best = 0; bestArea = 0
+        for (j = 1; j <= n; j++) {
+          if (VIS[j] != 1 || CLK[j] != 1 || W[j] <= 0 || H[j] <= 0) continue
+          if (X[j] <= X[a] && Y[j] <= Y[a] \
+              && X[j] + W[j] >= X[a] + W[a] && Y[j] + H[j] >= Y[a] + H[a]) {
+            area = W[j] * H[j]
+            if (best == 0 || area < bestArea) { best = j; bestArea = area }
+          }
+        }
+        if (best) {
+          key = X[best] "|" Y[best] "|" W[best] "|" H[best]
+          if (!(key in seen)) {
+            seen[key] = 1
+            printf "%s|%s|%s|%s|%s|%s|%s|%s\n",
+              X[best], Y[best], W[best], H[best], T[best], ID[best], LB[best], V[best]
+          }
+        }
+      }
+    }'
+}
+
+# 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.
+#
+# The source argument is unused, and no membership test is needed: uiautomator
+# dumps the application's window, the input method is a window of its own, so
+# nothing this adapter can resolve is ever a key. It costs one adb round trip,
+# measured at 70ms against the emulator this was built on, which is why the
+# caller asks only when it is about to touch the screen.
+#
+# The touchable region is the right rectangle, not the frame — the IME window's
+# frame spans the whole display while only its lower part accepts touches. When
+# the keyboard is down the window is not among the visible ones and this prints
+# nothing. A region split into several rectangles reports its first, so a split
+# keyboard is under-reported rather than over-reported, which is the safe
+# direction for a check that refuses to act.
+keyboard_blocks() {
+  local kb cx cy
+  kb="$(keyboard_region)"
+  [ -n "$kb" ] || return 0
+  cx=$(( $2 + $4 / 2 ))
+  cy=$(( $3 + $5 / 2 ))
+  printf '%s\n' "$kb" | awk -v cx="$cx" -v cy="$cy" '
+    cx >= $1 && cx <= $3 && cy >= $2 && cy <= $4 { print $1, $2, $3 - $1, $4 - $2 }'
+}
+
+# drv_keyboard_dismiss — ask the keyboard to go away. BACK rather than ESCAPE:
+# while the input method is up, BACK is consumed by it and closes it without
+# navigating, which is what a person does and what every keyboard supports.
+drv_keyboard_dismiss() {
+  adb_dev shell input keyevent 4 >/dev/null 2>&1
+}
+
+# keyboard_region — "left top right bottom" of the input method's touchable
+# region, or nothing when the keyboard is down.
+keyboard_region() {
+  adb_dev shell dumpsys window InputMethod 2>/dev/null \
+    | sed -n 's/.*InputMethod, frame=\[[^]]*\], touchableRegion=SkRegion((\([0-9]*\),\([0-9]*\),\([0-9]*\),\([0-9]*\))).*/\1 \2 \3 \4/p' \
+    | head -1
+}
+
+# keyboard_rect <source> — "x y w h", or nothing when it is down. The source is
+# unused; see keyboard_blocks.
+keyboard_rect() {
+  keyboard_region | awk '{ print $1, $2, $3 - $1, $4 - $2 }'
+}
+
+# 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.
+# See the iOS adapter for the failure this exists for; here `clickable` answers
+# exactly what type has to be inferred from there.
+unhittable_twin() {
+  local val="$3"
+  [ "$2" = id ] && val="$(strip_id_prefix "$3")"
+  printf '%s' "$1" | awk -F'|' -v kind="$2" -v val="$val" \
+    -v rx="$4" -v ry="$5" -v rw="$6" -v rh="$7" '
+    $1 == "WINDOW" || $1 == "" { next }
+    $8 <= 0 || $9 <= 0 { next }
+    {
+      if      (kind == "id")   { named = ($3 == val) }
+      else if (kind == "kind") { named = ($2 == val) }
+      else if (kind == "text") { named = ($5 == val) }
+      else                     { named = ($4 == val) }
+      if (!named) next
+      if ($6 == rx && $7 == ry && $8 == rw && $9 == rh) { if ($13 == 1) self_ok = 1; next }
+      if ($10 != 1 && $13 == 1 && !found) {
+        found = 1; desc = sprintf("%s at %s,%s,%s,%s", $2, $6, $7, $8, $9)
+      }
+    }
+    END { if (!self_ok && found) print desc }'
+}
+
+# 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() {
+  local val="$3"
+  [ "$2" = id ] && val="$(strip_id_prefix "$3")"
+  printf '%s' "$1" | awk -F'|' -v kind="$2" -v val="$val" '
+    $1 == "WINDOW" || $1 == "" { next }
+    { rows[NR] = $0; key = $6 "," $7 "," $8 "," $9; same[key]++ }
+    END {
+      for (i = 1; i <= NR; i++) {
+        n = split(rows[i], f, "|")
+        if (n < 10) continue
+        if      (kind == "id")   named = (f[3] == val)
+        else if (kind == "kind") named = (f[2] == val)
+        else if (kind == "text") named = (f[5] == val)
+        else if (kind == "any")  named = (f[3] == val || f[4] == val || f[5] == val)
+        else                     named = (f[4] == val)
+        if (!named) continue
+        key = f[6] "," f[7] "," f[8] "," f[9]
+        printf "%s|%s|%s|%s|%s|%s|%s\n", f[6], f[7], f[8], f[9], f[2], same[key], (f[10] == 1 ? 1 : 0)
+      }
+    }'
+}
+
+# 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" | awk -F'|' -v val="$2" '
+    $1 == "WINDOW" || $1 == "" { next }
+    ($4 == val || $5 == val) { printf "%s|%s|%s|%s|%s\n", $6, $7, $8, $9, $2 }'
+}
+
+match_elements() {
+  local val="$3"
+  if [ "$2" = holding ]; then holding_elements "$1" "$3"; return; fi
+  [ "$2" = id ] && val="$(strip_id_prefix "$3")"
+  printf '%s' "$1" | awk -F'|' -v kind="$2" -v val="$val" '
+    $1 == "WINDOW" || $1 == "" { next }
+    $10 != 1 || $8 <= 0 || $9 <= 0 { next }
+    {
+      if      (kind == "id")   { ok = ($3 == val) }
+      else if (kind == "kind") { ok = ($2 == val) }
+      else if (kind == "text") { ok = ($5 == val) }
+      else                     { ok = ($4 == val) }
+      if (ok) printf "%s|%s|%s|%s|%s|%s|%s|%s\n", $6, $7, $8, $9, $2, $3, $4, $5
+    }'
+}
+
+# kinds_on_screen <source> — the element types present, commonest first, with
+# counts. See the iOS adapter: candidate_elements searches identifiers, labels
+# and values, so for a `kind:` that matched nothing it has nothing to say.
+kinds_on_screen() {
+  printf '%s' "$1" | awk -F'|' '
+    $1 == "WINDOW" || $1 == "" { next }
+    $10 != 1 || $8 <= 0 || $9 <= 0 { next }
+    { n[$2]++ }
+    END { for (k in n) printf "%s x%s\n", k, n[k] }' \
+  | sort -t'x' -k2 -rn | 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" | awk -F'|' -v val="$2" '
+    function lower(s) { return tolower(s) }
+    $1 == "WINDOW" || $1 == "" { next }
+    $10 != 1 || $8 <= 0 || $9 <= 0 { next }
+    ($3 == "" && $4 == "" && $5 == "") { next }
+    {
+      hay = lower($3 " " $4 " " $5)
+      if (index(hay, lower(val)) == 0) next
+      out = $2
+      if ($3 != "") out = out " #" $3
+      if ($4 != "") out = out " \"" $4 "\""
+      if ($5 != "" && $5 != $4) out = out " =" $5
+      if      ($3 == val) out = out "  → try id:" val
+      else if ($4 == val) out = out "  → try label:" val
+      else if ($5 == val) out = out "  → try text:" val
+      print out
+    }' | head -n "${3:-5}"
+}
+
+# --- the normalised screen -----------------------------------------------------
+#
+# snapshot_rows — see the iOS adapter for the format, which is the point: the
+# two produce the same twelve fields and scripts/snapshot.awk cannot tell which
+# driver was on the other end.
+#
+# This is a re-shaping rather than a second fetch. tree.awk already emits
+# fourteen columns — depth|class|id|label|text|x|y|w|h|visible|enabled|password|
+# clickable|hint — so the work here is renumbering, deriving the parent and
+# folding three booleans into the flags field.
+#
+# NOT YET RUN AGAINST A DEVICE. There was no Android phone attached when this
+# was written, and docs/RELEASE.md says so. The iOS side is proven; this is not,
+# and a reader should treat it as a claim rather than a fact until it is.
+snapshot_rows() {
+  local src w h orient
+  src="$(fetch_source)"
+
+  read -r w h <<< "$(window_size "$src")"
+  w="${w:-0}"; h="${h:-0}"
+  if [ "$w" -gt "$h" ] 2>/dev/null; then orient=landscape; else orient=portrait; fi
+  printf 'WINDOW|%s|%s|%s\n' "$w" "$h" "$orient"
+
+  printf '%s\n' "$src" | awk -F'|' -v OFS='|' '
+    $1 == "WINDOW" || $1 == "" { next }
+    {
+      n++
+      depth = $1 + 0
+      stack[depth] = n
+      parent = (depth == 0) ? 0 : stack[depth - 1] + 0
+
+      # Android publishes `clickable` on the element, so "actionable" here is a
+      # fact rather than the type-based inference the iOS adapter has to make.
+      flags = ""
+      if ($10 == 1) flags = flags (flags == "" ? "" : ",") "visible"
+      if ($11 == 1) flags = flags (flags == "" ? "" : ",") "enabled"
+      if ($13 == 1) flags = flags (flags == "" ? "" : ",") "actionable"
+
+      print n, depth, parent, $2, $3, $4, $5, $6, $7, $8, $9, flags
+    }'
+}
+
+# content_digest <source> — see the iOS adapter. Rows here, not JSON:
+# depth|class|id|label|text|x|y|w|h|visible|enabled|password|clickable|hint
+content_digest() {
+  printf '%s' "$1" | awk -F'|' '
+    $1 == "WINDOW" || $1 == "" { next }
+    $10 != 1 { next }
+    { print $2 "\037" $4 "\037" $5 }' | cksum | awk '{ print $1 }'
+}
+
+# capture_png <path> — see the iOS adapter.
+#
+# `exec-out` rather than `shell`: adb's shell channel translates line endings,
+# which corrupts a PNG in a way that is invisible until something tries to
+# decode it.
+capture_png() {
+  local out="$1"
+  adb_dev exec-out screencap -p > "$out" 2>/dev/null || return 3
+  [ -s "$out" ] || { rm -f "$out"; return 3; }
+  [ "$(head -c 8 "$out" | od -An -tx1 | tr -d ' \n')" = "89504e470d0a1a0a" ] \
+    || { rm -f "$out"; return 3; }
+  return 0
+}
+
+# logs_since <unix-seconds> — see the iOS adapter for the two rules this obeys:
+# it never starts a collector, and it never fails.
+#
+# The app filter is the package name, which Android does publish and which
+# logcat lines carry, so this one is a match rather than the heuristic the iOS
+# side has to make do with.
+logs_since() {
+  local since="$1" f pkg out
+  f="$(state_dir)/logcat.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
+  pkg="$(cfg '.app.package' '')"
+  if [ -n "$pkg" ]; then
+    out="$(printf '%s\n' "$out" | grep -i -F -- "$pkg" || true)"
+  fi
+  [ -n "$out" ] || return 0
+  printf '%s\n' "$out" | sed '/^[[:space:]]*$/d' | tail -8
+}