device-devtools-mcp 0.1.0

package/scripts/android/tree.awk

@@ -0,0 +1,166 @@
+# tree.awk — UiAutomator XML hierarchy to DeviceTools's line table.
+#
+# WHY THIS EXISTS RATHER THAN A CALL TO yq
+#
+# The obvious route is `yq -p=xml -o=json` and then jq, mirroring the iOS
+# adapter. It works: measured 0.058s on a 36 KB dump. It also adds a dependency
+# that every user must install before the tool runs at all, to do one job on one
+# input, and that job is 60 lines of awk.
+#
+# The input is not general XML and does not need a general parser. UiAutomator's
+# serialiser emits: no CDATA, no text nodes, no namespaces, no processing
+# instructions beyond the declaration, and attribute values always in double
+# quotes with `< > & " '` escaped as entities. Those properties are guaranteed by
+# the serialiser, not by luck, and they are what make a 60-line parser correct
+# instead of merely lucky.
+#
+# Output, one line per element, in document order:
+#
+#   depth|class|id|label|text|x|y|w|h|visible|enabled|password|clickable|hint
+#
+# `hint` is 1 when the `text` column is a placeholder rather than the field's
+# contents. Android reports this and iOS does not, and it is worth carrying:
+# without it, an empty field whose placeholder reads "Mật khẩu" is
+# indistinguishable from a field someone typed "Mật khẩu" into.
+#
+# The root <hierarchy> element is not a UI element and is not emitted. Its width
+# and height are the window size, printed first as:
+#
+#   WINDOW|<w>|<h>
+#
+# so that callers needing the screen size do not pay for a second request.
+
+function unesc(s) {
+  if (index(s, "&") == 0) return s
+  gsub(/&lt;/,   "<",  s)
+  gsub(/&gt;/,   ">",  s)
+  gsub(/&quot;/, "\"", s)
+  gsub(/&apos;/, "'",  s)
+  gsub(/&#10;/,  " ",  s)
+  gsub(/&#13;/,  " ",  s)
+  gsub(/&#9;/,   " ",  s)
+  # Last, and never earlier: decoding &amp; first would turn the literal text
+  # "&lt;" into "<". In awk's replacement string "&" means the matched text, so
+  # a literal ampersand has to be escaped.
+  gsub(/&amp;/,  "\\&", s)
+  return s
+}
+
+# The same normalisation the iOS adapter applies in jq. Labels come from
+# application copy and can hold newlines and pipes, both of which would break
+# the line-oriented contract, so they are neutralised where the tree is read.
+function clean(s) {
+  gsub(/[\n\r\t]+/, " ", s)
+  gsub(/\|/, "/", s)
+  gsub(/  +/, " ", s)
+  sub(/^ +/, "", s)
+  sub(/ +$/, "", s)
+  return s
+}
+
+# attr(rec, name) — the value of one attribute, or "".
+#
+# The leading space in the needle is what keeps `text` from matching
+# `tooltip-text` and `id` from matching `window-id`.
+#
+# BOTH QUOTE CHARACTERS ARE LOAD-BEARING. UiAutomator does not escape a double
+# quote inside a value; it switches the delimiter instead. Typing
+#   Đặng Thu Hà & "ghi chú"
+# into a field serialises as
+#   text='Đặng Thu Hà &amp; "ghi chú"'
+# with `&` escaped and `"` not. A parser that only knows double quotes reads
+# that attribute as absent and reports an empty field — which is how a passing
+# test can be built on a value that was never checked.
+function attr(rec, name,   i, dq, sq, q, s, j) {
+  dq = index(rec, " " name "=\"")
+  sq = index(rec, " " name "='")
+  if (dq == 0 && sq == 0) return ""
+  # Whichever appears first is this attribute; the other, if present, belongs to
+  # a different attribute whose name ends with the same characters.
+  if (sq == 0 || (dq != 0 && dq < sq)) { i = dq; q = "\"" } else { i = sq; q = "'" }
+  s = substr(rec, i + length(name) + 3)
+  j = index(s, q)
+  if (j == 0) return ""
+  return unesc(substr(s, 1, j - 1))
+}
+
+BEGIN {
+  RS = "<"
+  # <hierarchy> is a synthetic wrapper, not a widget, so it is not emitted and
+  # not counted: the first real element comes out at depth 0, which is where the
+  # iOS adapter puts the root element too.
+  depth = -2
+  win_w = 0; win_h = 0
+}
+
+# Everything before the first "<" is the empty leading record.
+NR == 1 { next }
+
+{
+  rec = $0
+  c = substr(rec, 1, 1)
+
+  if (c == "?" || c == "!") next            # declaration, comment, doctype
+  if (c == "/") { depth--; next }           # closing tag
+
+  # Self-closing has to be decided on a skeleton with attribute values removed:
+  # a value may legitimately end in "/" (a path, a date), and testing the raw
+  # record would then call an opening tag self-closing and corrupt every depth
+  # below it.
+  skel = rec
+  gsub(/"[^"]*"/, "", skel)
+  gsub(/'[^']*'/, "", skel)
+  selfclose = (skel ~ /\/[ \t\r\n]*>[ \t\r\n]*$/)
+
+  depth++
+
+  cls = attr(rec, "class")
+
+  if (cls == "hierarchy") {
+    win_w = attr(rec, "width") + 0
+    win_h = attr(rec, "height") + 0
+    print "WINDOW|" win_w "|" win_h
+    if (selfclose) depth--
+    next
+  }
+
+  # bounds="[x1,y1][x2,y2]"
+  b = attr(rec, "bounds")
+  x = 0; y = 0; w = 0; h = 0
+  if (b != "") {
+    n = split(b, p, /[^0-9-]+/)
+    # split on the separators leaves an empty first field from the leading "["
+    if (n >= 5) {
+      x1 = p[2] + 0; y1 = p[3] + 0; x2 = p[4] + 0; y2 = p[5] + 0
+      x = x1; y = y1; w = x2 - x1; h = y2 - y1
+    }
+  }
+
+  # The last dotted segment is enough to identify a widget and costs a fraction
+  # of the tokens: android.widget.TextView is TextView on every screen.
+  short = cls
+  sub(/^.*\./, "", short)
+
+  # resource-id arrives as "com.example.app:id/login_button". The package prefix
+  # is the same for every element of the app under test, so it is pure noise in
+  # the common case. It is stripped here; lib.sh matches a selector against both
+  # the stripped and the full form, so either spelling works and neither is
+  # silently wrong.
+  rid = attr(rec, "resource-id")
+  sub(/^[^ ]*:id\//, "", rid)
+
+  printf "%d|%s|%s|%s|%s|%d|%d|%d|%d|%s|%s|%s|%s|%s\n",
+    depth,
+    clean(short),
+    clean(rid),
+    clean(attr(rec, "content-desc")),
+    clean(attr(rec, "text")),
+    x, y, w, h,
+    (attr(rec, "displayed")     == "true" ? 1 : 0),
+    (attr(rec, "enabled")       == "true" ? 1 : 0),
+    (attr(rec, "password")      == "true" ? 1 : 0),
+    (attr(rec, "clickable")     == "true" ? 1 : 0),
+    (attr(rec, "showing-hint")  == "true" ? 1 : 0)
+
+  if (selfclose) depth--
+}

package/scripts/android/tree.sh

@@ -0,0 +1,127 @@
+#!/usr/bin/env bash
+# tree.sh — the accessibility tree, reduced to something an agent can afford to read.
+#
+#   tree.sh [--all] [--depth N] [--grep S]
+#
+# One line per element, identical in shape to the iOS adapter's:
+#
+#   depth | type | id | label | value | x,y,w,h
+#
+# On Android `id` is the resource-id with its package prefix removed, `label` is
+# the content description and `value` is the element's text.
+#
+# The raw XML hierarchy for one screen measured 46 KB (~11.6k tokens) on the
+# device this was built against. Raw XML must never reach the agent, so this
+# script is the only supported way to read the tree.
+#
+# By default an element is shown when it is visible AND it either carries an
+# identifier, a label or a value, or is marked clickable. An invisible element
+# with a label is noise; an unlabelled control is not, because it can still be
+# reached by coordinate or by structure.
+#
+#   --all        every element, no filter and no cap
+#   --full       do not truncate strings at 48 characters
+#   --depth N    only elements at depth <= N
+#   --grep S     case-insensitive substring of id, label, value or type.
+#                Searches the whole tree, including elements the default filter
+#                hides, so it can find something that is present but off-screen.
+#
+# Output is capped at tree.max_lines from the config and always ends with
+#   … N more elements (--all)
+# when truncated, so a partial tree can never be mistaken for a complete one.
+#
+# exit 0  at least one element printed
+# exit 1  usage error
+# exit 3  UiAutomator2 unreachable — run doctor.sh
+# exit 4  nothing matched
+
+source "$(dirname "${BASH_SOURCE[0]}")/lib.sh"
+
+ALL=0
+FULL=0
+DEPTH=-1
+GREP=""
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --all) ALL=1; shift ;;
+    # Repair needs exact strings. A label cut at 48 characters cannot be turned
+    # into a selector that matches, so a caller capturing a failure dump asks for
+    # this while everything an agent reads interactively keeps the cap.
+    --full) FULL=1; shift ;;
+    --depth)
+      [ $# -ge 2 ] || die "--depth needs a number" 1
+      case "$2" in (*[!0-9]*|"") die "--depth needs a non-negative integer, got: $2" 1 ;; esac
+      DEPTH="$2"; shift 2 ;;
+    --grep)
+      [ $# -ge 2 ] || die "--grep needs a string" 1
+      GREP="$2"; shift 2 ;;
+    -h|--help) awk 'NR > 1 { if (!/^#/) exit; sub(/^# ?/, ""); print }' "${BASH_SOURCE[0]}"; exit 0 ;;
+    *) die "unknown argument: $1 (usage: tree.sh [--all] [--full] [--depth N] [--grep S])" 1 ;;
+  esac
+done
+
+load_config
+MAXLINES="$(cfg '.tree.max_lines' '60')"
+
+src="$(fetch_source)"
+
+# One awk pass: filter, format, truncate.
+#
+# TRUNCATION COUNTS CHARACTERS, NOT BYTES, and that is not pedantry. macOS ships
+# awk 20200816, whose length() and substr() are byte-oriented: cutting "Lê"
+# at six bytes yields "Nguy\341\273", an incomplete UTF-8 sequence that renders
+# as a replacement character and can never be matched by a selector. Since every
+# label in the app this was built against is Vietnamese, a byte cut would
+# corrupt most of the output. So character boundaries are found by skipping
+# UTF-8 continuation bytes, which awk compares correctly even though it cannot
+# express them as a regex range.
+rows="$(printf '%s' "$src" | awk -F'|' -v all="$ALL" -v depth="$DEPTH" -v want="$GREP" -v full="$FULL" '
+  BEGIN { for (i = 128; i <= 191; i++) CONT = CONT sprintf("%c", i) }
+
+  function cutn(s, n,   i, chars, b, len) {
+    if (full == 1) return s
+    len = length(s); chars = 0
+    for (i = 1; i <= len; i++) {
+      b = substr(s, i, 1)
+      if (index(CONT, b) > 0) continue      # continuation byte: same character
+      chars++
+      if (chars == n + 1) return substr(s, 1, i - 1) "…"
+    }
+    return s
+  }
+
+  $1 == "WINDOW" || $1 == "" { next }
+  depth >= 0 && $1 + 0 > depth { next }
+  {
+    d = $1; t = $2; id = $3; lb = $4; v = $5
+    vis = ($10 == 1)
+    if (want == "") {
+      # $13 is clickable. An unlabelled control is still a control, and hiding
+      # it tells the reader the screen has nothing to tap — which is worse than
+      # the noise the filter exists to remove.
+      if (all != 1 && !(vis && (id != "" || lb != "" || v != "" || $13 == 1))) next
+    } else {
+      hay = tolower(id " " lb " " v " " t)
+      if (index(hay, tolower(want)) == 0) next
+    }
+    printf "%s | %s | %s | %s | %s | %s,%s,%s,%s\n",
+      d, t, cutn(id, 48), cutn(lb, 48), cutn(v, 48), $6, $7, $8, $9
+  }')"
+
+if [ -z "$rows" ]; then
+  total="$(printf '%s' "$src" | grep -vc '^WINDOW|' || true)"
+  if [ -n "$GREP" ]; then
+    die "no elements matched --grep '$GREP' ($total elements in tree)" 4
+  fi
+  die "no elements matched (tree has $total elements, try --all)" 4
+fi
+
+n="$(printf '%s\n' "$rows" | wc -l | tr -d ' ')"
+
+if [ "$ALL" -eq 1 ] || [ "$n" -le "$MAXLINES" ]; then
+  printf '%s\n' "$rows"
+else
+  printf '%s\n' "$rows" | take_lines "$MAXLINES"
+  printf '… %s more elements (--all)\n' "$(( n - MAXLINES ))"
+fi

package/scripts/android/type.sh

@@ -0,0 +1,191 @@
+#!/usr/bin/env bash
+# type.sh — type into whatever currently has keyboard focus, then prove it.
+#
+#   type.sh <text>
+#
+# Verification is the point of this script. Sending keystrokes is one HTTP call;
+# knowing they landed is what stops an agent from building a chain of reasoning
+# on a field that never received the text.
+#
+# WHY NOT `adb shell input text`
+#
+# It cannot type Vietnamese. Four encodings were tried against a real device and
+# each returned "Exception occurred while executing 'text'", while the same call
+# with ASCII returned 0. Every field this tool exists to fill is in Vietnamese,
+# so the whole Android adapter is built on the UiAutomator2 server instead.
+#
+# Verification is tiered, because a masked field cannot echo back what you typed:
+#
+#   verified              the field now reads exactly what was typed
+#   verified, appended    the field ends with what was typed
+#   verified by change    the field changed but reads something else — a password
+#                         field, or an input mask reformatting as you go
+#   nothing changed       exit 4; the keystrokes went nowhere
+#
+# Android reports `password` on the element itself, so unlike iOS this does not
+# have to guess why a field failed to echo: the verdict names the reason.
+#
+# What was typed is reported as a length, not as text, because this runs against
+# a production app and stdout ends up in CI logs. The field's own contents are
+# echoed only when they differ from what was typed, which is the case where a
+# human debugging a failure genuinely needs to see them.
+#
+# --snapshot prints the screen this left behind and renumbers the uids, so the
+# read that would have been the next call is folded into this one. In a measured
+# session — log in, open Settings — twelve calls did the work and six of them
+# were snapshots taken only to find out what the previous action produced.
+#
+# exit 0  typed, and something changed to prove it
+# exit 1  usage error
+# exit 3  UiAutomator2 unreachable — run doctor.sh
+# exit 4  nothing focused, or typing changed nothing
+
+source "$(dirname "${BASH_SOURCE[0]}")/lib.sh"
+
+TEXT=""
+HAVE_TEXT=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --snapshot) act_snapshot_on; shift ;;
+    -h|--help) awk 'NR > 1 { if (!/^#/) exit; sub(/^# ?/, ""); print }' "${BASH_SOURCE[0]}"; exit 0 ;;
+    # See the iOS adapter: `--` is how text that begins with a dash is told
+    # apart from a mistyped flag, and a mistyped flag must not be keyed into a
+    # password field.
+    --) shift
+        [ $# -ge 1 ] || die "-- must be followed by the text to type" 1
+        [ "$HAVE_TEXT" -eq 0 ] || die "type.sh takes one text argument; quote text containing spaces" 1
+        TEXT="$1"; HAVE_TEXT=1; shift ;;
+    -*) die "unknown argument: $1 (usage: type.sh <text> [--snapshot]; use -- before text starting with a dash)" 1 ;;
+    *)
+      [ "$HAVE_TEXT" -eq 0 ] || die "type.sh takes one text argument; quote text containing spaces" 1
+      TEXT="$1"; HAVE_TEXT=1; shift ;;
+  esac
+done
+[ "$HAVE_TEXT" -eq 1 ] || die "missing text (usage: type.sh <text> [--snapshot])" 1
+
+load_config
+
+# key -> value, one line per text input: key, rect, type, value, password.
+#
+# THE KEY IS THE RESOURCE ID WHEN THERE IS ONE, AND THE RECT ONLY OTHERWISE.
+# Keying on the rect alone, as the iOS adapter must, has a measured failure
+# mode: typing into a password field moved it from y=808 to y=751 because the
+# keyboard resized the layout. Under a rect key that is not "this field
+# changed", it is "a field I have never seen appeared" — and a field that merely
+# moved would then be reported as proof that typing worked. Android publishes a
+# resource id, which survives the move, so it is used where present.
+#
+# A field showing its placeholder is recorded as EMPTY, not as the placeholder
+# text. Android sets `showing-hint` for exactly this, and without honouring it
+# a field whose hint reads "Mật khẩu" would appear to already contain that
+# string, so typing it would register as "nothing changed".
+snapshot_inputs() {
+  printf '%s' "$1" | awk -F'|' '
+    $1 == "WINDOW" || $1 == "" { next }
+    $10 != 1 || $8 <= 0 || $9 <= 0 { next }
+    ($2 !~ /Edit/ && $12 != 1) { next }
+    { val  = ($14 == 1 ? "" : $5)
+      rect = $6 "," $7 "," $8 "," $9
+      key  = ($3 != "" ? "#" $3 : rect)
+      printf "%s\t%s\t%s\t%s\t%s\n", key, rect, $2, val, $12 }'
+}
+
+# Fetches are assigned to their own variable rather than nested inside another
+# substitution. A failure in `f "$(g)"` is discarded — the exit status seen is
+# f's, not g's — so nesting a call that can fail hides the failure.
+src="$(fetch_source)"
+
+# FOCUS IS THE PRECONDITION. A TEXT INPUT IN THE TREE IS NOT.
+#
+# UiAutomator2 types into a named element, so focus has to be resolved rather
+# than assumed. This is also the cheap pre-check: with nothing focused the
+# server answers immediately instead of hanging until the HTTP timeout.
+#
+# It used to be preceded by a guard that refused unless the tree held something
+# recognisable as a text input. See the iOS adapter for why that is wrong: an
+# OTP field is routinely invisible to accessibility while holding focus, so the
+# guard refused a screen that would have accepted every keystroke.
+resp="$(session_get '/element/active')"
+EID="$(printf '%s' "$resp" | jq -r '.value.ELEMENT // empty' 2>/dev/null)"
+[ -n "$EID" ] || die "nothing has keyboard focus — tap a field to focus it before typing" 4
+
+before="$(snapshot_inputs "$src")"
+before_digest="$(content_digest "$src")"
+
+act_before
+payload="$(jq -nc --arg t "$TEXT" '{text: $t}')"
+resp="$(session_post "/element/$EID/value" "$payload")"
+err="$(session_error "$resp")"
+[ -z "$err" ] || die "typing failed — $err" 3
+
+src="$(fetch_source)"
+after="$(snapshot_inputs "$src")"
+after_digest="$(content_digest "$src")"
+
+# Which input changed, if any, strongest evidence first.
+#
+# Rank matters because not all evidence is equal. A field that kept its identity
+# and changed its value is proof. A field that appeared where none was tracked
+# is only proof if it now holds what was typed; otherwise it may simply be a
+# field that moved, and reporting it as success would confirm a keystroke that
+# never landed.
+#
+# The blank-line guard is load bearing: `printf '%s\n' "$empty"` emits one empty
+# line, which awk counts as a record. Without it, an empty "after" manufactures
+# a phantom changed input and reports success.
+changed="$(awk -F'\t' -v OFS='\t' -v typed="$TEXT" '
+  $1 == "" { next }
+  NR == FNR { was[$1] = $4; seen[$1] = 1; next }
+  {
+    if (seen[$1]) {
+      if (was[$1] == $4) next
+      rank = 0                                    # same field, new value
+    } else if (typed != "" && index($4, typed) > 0) {
+      rank = 1                                    # new field, holds what we typed
+    } else {
+      rank = 2                                    # new field, unexplained
+    }
+    print rank, $2, $3, $4, $5
+  }
+' <(printf '%s\n' "$before") <(printf '%s\n' "$after") | sort -n -k1,1)"
+
+# VERIFICATION DROPS A TIER, IT DOES NOT REFUSE. See the iOS adapter.
+if [ -z "$changed" ]; then
+  if [ "$before_digest" != "$after_digest" ]; then
+    act_report TYPE "${#TEXT} char(s) — no text input in the tree, and the screen changed. Typical of an OTP or PIN field: the value cannot be read back from here, so this is evidence the keystrokes landed, not proof of what they were"
+    journal_append type "$TEXT" "" "" "" "" 0 0 0 0 "$DT_ACT_HASH"
+    exit 0
+  fi
+  # The length, not the text — see the note on the same line in the iOS adapter.
+  die "typed ${#TEXT} char(s) and nothing on screen changed — focus was held but the keystrokes went nowhere; tap the field again" 4
+fi
+
+n="$(printf '%s\n' "$changed" | wc -l | tr -d ' ')"
+line="$(first_line "$changed")"
+rect="$(printf '%s' "$line" | cut -f2)"
+# NOT `type`: it is a shell builtin, and on the iOS side an unset one made the
+# error read `type: unbound variable`, which looks like a missing command.
+field_type="$(printf '%s' "$line" | cut -f3)"
+now="$(printf '%s' "$line" | cut -f4)"
+pw="$(printf '%s' "$line" | cut -f5)"
+
+if [ "$now" = "$TEXT" ]; then
+  verdict="verified"
+else
+  case "$now" in
+    *"$TEXT") verdict="verified, appended" ;;
+    *)
+      if [ "$pw" = 1 ]; then
+        verdict="verified by change only — password field, contents are not readable"
+      else
+        verdict="verified by change only — field reads '$now', which is expected for a reformatting input"
+      fi ;;
+  esac
+fi
+
+if [ "$n" -gt 1 ]; then
+  verdict="$verdict ($n inputs changed, reporting the first)"
+fi
+
+act_report TYPE "${#TEXT} char(s) — $field_type at $rect, $verdict"
+journal_append type "$TEXT" "${field_type-}" "" "" "" 0 0 0 0 "$DT_ACT_HASH"

package/scripts/common/find.sh

@@ -0,0 +1,95 @@
+#!/usr/bin/env bash
+# find.sh — resolve a selector and report what it matched.
+#
+#   find.sh <selector> [--index N]
+#
+# One line per match, in tree.sh's column order minus the depth:
+#
+#   type | id | label | text | x,y,w,h
+#
+# Unlike tap.sh this does not insist on a single match — reading is not acting,
+# and "how many of these are there" is a question worth being able to ask. It
+# still matches exactly, so what it reports is what tap.sh would act on.
+#
+# This is the lookup primitive assertions are built from. Without it the runner
+# would have to re-implement matching, which would put knowledge of the
+# platform's tree above the line that is supposed to hide it.
+#
+# exit 0  at least one match
+# exit 1  usage error
+# exit 3  the device driver is unreachable — run doctor.sh
+# exit 4  no match
+
+# SHARED VERB — one copy, reached from scripts/ios/ and scripts/android/ by
+# symlink. The symlink's own directory decides which lib.sh the line below
+# resolves to, which is the whole mechanism.
+#
+# It qualifies as shared because it touches the screen only through the driver
+# primitives (drv_tap, drv_drag, drv_fingerprint*) and the lookup helpers every
+# adapter implements. Nothing here may learn that WebDriverAgent or UiAutomator2
+# exists; the moment a verb needs to, it stops being shared and moves back into
+# the adapter that needs it.
+source "$(dirname "${BASH_SOURCE[0]}")/lib.sh"
+
+SELECTOR=""
+INDEX=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --index)
+      [ $# -ge 2 ] || die "--index needs a number" 1
+      case "$2" in (*[!0-9]*|"") die "--index needs a non-negative integer, got: $2" 1 ;; esac
+      INDEX="$2"; shift 2 ;;
+    -h|--help) awk 'NR > 1 { if (!/^#/) exit; sub(/^# ?/, ""); print }' "${BASH_SOURCE[0]}"; exit 0 ;;
+    -*) die "unknown argument: $1 (usage: find.sh <selector> [--index N])" 1 ;;
+    *)
+      [ -z "$SELECTOR" ] || die "only one selector is supported, got '$SELECTOR' and '$1'" 1
+      SELECTOR="$1"; shift ;;
+  esac
+done
+[ -n "$SELECTOR" ] || die "missing selector (usage: find.sh <selector> [--index N])" 1
+
+load_config
+parse_selector "$SELECTOR"
+
+[ "$SEL_KIND" != xy ] \
+  || die "xy selectors cannot be looked up — a point always exists; use id:, label: or text:" 1
+
+src="$(fetch_source)"
+# What the screen says right now. Nothing is consulted except the screen.
+matches="$(match_or_holding "$src" "$SEL_KIND" "$SEL_VALUE" || true)"
+resolve_state
+
+if [ -z "$matches" ]; then
+  note="$(invisible_note "$src" "$SEL_KIND" "$SEL_VALUE" || true)"
+  [ -n "$note" ] && die "$SEL_DESC matches nothing that can be acted on — $note" 4
+
+  cands="$(candidate_elements "$src" "$SEL_VALUE" 5 | join_lines '; ' || true)"
+  if [ -z "$cands" ] && [ "$SEL_KIND" = text ]; then
+    note="$(holding_absence "$src" "$SEL_VALUE")"
+    [ -n "$note" ] && die "no control matched '$SEL_VALUE' — $note" 4
+  fi
+  # candidate_elements searches identifiers, labels and values, so for a type it
+  # has nothing to offer. The types that ARE here is the answer to that question.
+  if [ "$SEL_KIND" = kind ]; then
+    die "no visible $SEL_VALUE on this screen. What is here: $(kinds_on_screen "$src")" 4
+  fi
+  [ -z "$cands" ] \
+    && die "nothing matches $SEL_DESC and nothing on screen contains it" 4
+  die "nothing matches $SEL_DESC — a selector matches whole, and these merely contain it: $cands" 4
+fi
+
+if [ -n "$INDEX" ]; then
+  n="$(printf '%s\n' "$matches" | wc -l | tr -d ' ')"
+  [ "$INDEX" -lt "$n" ] \
+    || die "--index $INDEX is out of range: $SEL_DESC matches $n element(s), so the last index is $((n - 1))" 4
+  matches="$(printf '%s\n' "$matches" | sed -n "$((INDEX + 1))p")"
+fi
+
+printf '%s\n' "$matches" \
+  | awk -F'|' '{ printf "%s | %s | %s | %s | %s,%s,%s,%s\n", $5, $6, $7, $8, $1, $2, $3, $4 }'
+
+# The note, if there was one, on its own last line. The element lines keep the
+# shape every caller parses — five columns split on " | " — because a note
+# appended to one of them would land in a column and be read as data.
+[ "$RESOLVE_HOW" = holding ] && printf 'resolved by the control holding that text\n'
+exit 0

package/scripts/common/key.sh

@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+# key.sh — put the on-screen keyboard away.
+#
+#   key.sh hide
+#
+# This exists because `tap` refuses when the keyboard stands between it and the
+# control, and told people to dismiss it without giving them any way to. An
+# error message that names an action the tool cannot perform is a dead end.
+#
+# It is deliberately not automatic. A keyboard that disappears by itself between
+# steps changes the screen the next step reasons about, and a test that reads
+# `tap { label: Đăng nhập }` should not also mean "and close the keyboard if it
+# is awkward". The step is written down or it does not happen.
+#
+# Verified rather than assumed: the driver answers the dismiss request before
+# the animation has finished, so this waits for the keyboard to actually leave,
+# and fails if it does not — some fields keep it up on purpose.
+#
+# --snapshot prints the screen this left behind and renumbers the uids, so the
+# read that would have been the next call is folded into this one. In a measured
+# session — log in, open Settings — twelve calls did the work and six of them
+# were snapshots taken only to find out what the previous action produced.
+#
+# exit 0  the keyboard is gone, or was never up
+# exit 1  usage error
+# exit 3  the device driver is unreachable — run doctor.sh
+# exit 4  it was asked to go and stayed
+
+# SHARED VERB — one copy, reached from scripts/ios/ and scripts/android/ by
+# symlink. The two drivers put a keyboard away differently, and that difference
+# is the whole of what `drv_keyboard_dismiss` hides.
+source "$(dirname "${BASH_SOURCE[0]}")/lib.sh"
+
+CMD=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    hide) [ -z "$CMD" ] || die "key.sh takes one verb (usage: key.sh hide [--snapshot])" 1
+          CMD=hide; shift ;;
+    --snapshot) act_snapshot_on; shift ;;
+    -h|--help) awk 'NR > 1 { if (!/^#/) exit; sub(/^# ?/, ""); print }' "${BASH_SOURCE[0]}"; exit 0 ;;
+    *) die "unknown verb '$1' (usage: key.sh hide [--snapshot])" 1 ;;
+  esac
+done
+[ -n "$CMD" ] || die "missing verb (usage: key.sh hide [--snapshot])" 1
+
+load_config
+
+up() { [ -n "$(keyboard_rect "$(fetch_source)")" ]; }
+
+if ! up; then
+  printf 'OK keyboard — already down\n'
+  act_snapshot_now
+  exit 0
+fi
+
+drv_keyboard_dismiss || true
+
+n=0
+while [ "$n" -lt 10 ]; do
+  up || { printf 'OK keyboard — dismissed\n'; act_snapshot_now; exit 0; }
+  n=$((n + 1))
+  sleep 0.3
+done
+
+die "asked the keyboard to go and it is still up — some fields hold it open; tap elsewhere, or act on a control the keyboard does not cover" 4

package/scripts/common/lib.sh

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+# Not a library — a signpost.
+#
+# The verbs in this directory are meant to be reached through the symlinks in
+# scripts/ios/ and scripts/android/, so that `dirname "${BASH_SOURCE[0]}"`
+# resolves to an adapter and picks up that adapter's lib.sh. Running one from
+# here directly finds this file instead.
+#
+# Without it the failure is `scripts/common/lib.sh: No such file or directory`,
+# which says nothing about what the caller did wrong.
+
+printf 'scripts/common/ holds shared verb implementations and cannot be run from here — use scripts/%s (it selects the platform from your config)\n' \
+  "$(basename "${BASH_SOURCE[1]:-<verb>.sh}")" >&2
+exit 2