device-devtools-mcp 0.1.0

package/scripts/common/measure.sh

@@ -0,0 +1,170 @@
+#!/usr/bin/env bash
+# measure.sh — one element, and everything that can be said about where it is.
+#
+#   measure.sh <uid>
+#
+# snapshot warns about what it can prove is wrong, and groups those warnings so
+# a list of six identical rows does not report the same fault six times. This is
+# the other half of that trade: when you want to know which sibling something
+# overlaps, or how far it sits from the thing above it, you ask here.
+#
+#   [4] Button "Đăng nhập"   (24,356) 327x50
+#       parent   ScrollView (0,88) 375x724 — contained
+#       above    [3] SecureTextField, gap 24pt
+#       below    [5] StaticText, gap 34pt
+#       text     "Đăng nhập" — not truncated
+#       overlaps none
+#       hit area 327x50 — meets the 44pt minimum
+#
+# The uid comes from the last snapshot and is checked before anything is
+# described. Describing an element that has moved is describing a screen that no
+# longer exists.
+#
+# exit 0  described
+# exit 1  usage error
+# exit 3  the driver is unreachable — run doctor.sh
+# exit 4  no such uid, or it is stale
+
+source "$(dirname "${BASH_SOURCE[0]}")/lib.sh"
+
+case "${1-}" in
+  -h|--help) awk 'NR > 1 { if (!/^#/) exit; sub(/^# ?/, ""); print }' "${BASH_SOURCE[0]}"; exit 0 ;;
+  "") die "measure.sh needs a uid (usage: measure.sh <uid>)" 1 ;;
+  *[!0-9]*) die "measure.sh takes a uid, which is a number — got '$1'" 1 ;;
+esac
+[ $# -eq 1 ] || die "too many arguments (usage: measure.sh <uid>)" 1
+WANT="$1"
+
+load_config
+
+case "$(platform)" in
+  android) MINHIT=48 ;;
+  *)       MINHIT=44 ;;
+esac
+
+STORE="$(uid_store)"
+[ -f "$STORE" ] || die "no uid is in play — run snapshot.sh first" 4
+
+# uid_resolve is the staleness check, and it is the same one tap uses. Its
+# answer is discarded here; what matters is that it did not die.
+uid_resolve "$WANT" >/dev/null
+
+rows="$(snapshot_rows)"
+[ -n "$rows" ] || die "the driver returned an empty tree — run $(as_cmd doctor)" 3
+
+printf '%s\n' "$rows" | awk -F'|' -v U="$WANT" -v MINHIT="$MINHIT" -v STORE="$STORE" '
+  # The store is the authority on what a uid means. It is read first so that
+  # every neighbour this prints can be named by the number the agent already has
+  # in front of it, rather than by a description it would have to go and match.
+  BEGIN {
+    while ((getline line < STORE) > 0) {
+      k = split(line, f, "|")
+      if (k < 10) continue
+      su[++ns] = f[1]; stype[ns] = f[3]; sid[ns] = f[4]; slabel[ns] = f[5]
+      sval[ns] = f[6]; sx[ns] = f[7] + 0; sy[ns] = f[8] + 0
+      sw[ns] = f[9] + 0; sh[ns] = f[10] + 0
+      if (f[1] + 0 == U + 0) {
+        TT = f[3]; TI = f[4]; TL = f[5]; TV = f[6]
+        TX = f[7] + 0; TY = f[8] + 0; TW = f[9] + 0; TH = f[10] + 0
+      }
+    }
+    close(STORE)
+  }
+
+  $1 == "WINDOW" { WW = $2 + 0; WH = $3 + 0; next }
+  $0 == "" { next }
+  {
+    n++
+    parent[n] = $3 + 0; type[n] = $4; id[n] = $5; label[n] = $6; value[n] = $7
+    x[n] = $8 + 0; y[n] = $9 + 0; w[n] = $10 + 0; h[n] = $11 + 0
+    byserial[$1 + 0] = n
+    if ($4 == TT && $5 == TI && $6 == TL && $7 == TV && near($8, TX) && near($9, TY) &&
+        near($10, TW) && near($11, TH)) me = n
+  }
+
+  # The same two points of slack uid_resolve allows, for the same reason: the
+  # drivers report floats and this pipeline floors them.
+  function near(a, b,   d) { d = (a + 0) - (b + 0); return (d < 0 ? -d : d) <= 2 }
+  function best(i)         { return label[i] != "" ? label[i] : (value[i] != "" ? value[i] : id[i]) }
+  function span(a1, a2, b1, b2,   lo, hi) {
+    lo = (a1 > b1) ? a1 : b1; hi = (a2 < b2) ? a2 : b2; return hi - lo
+  }
+
+  # Which uid, if any, the last snapshot gave this element. Elements the display
+  # filter hid have none, and are named by type instead.
+  function uidat(i,   k) {
+    for (k = 1; k <= ns; k++)
+      if (stype[k] == type[i] && sid[k] == id[i] && slabel[k] == label[i] &&
+          sval[k] == value[i] && near(sx[k], x[i]) && near(sy[k], y[i]) &&
+          near(sw[k], w[i]) && near(sh[k], h[i])) return su[k]
+    return ""
+  }
+  function name(i,   u) {
+    u = uidat(i)
+    return (u != "" ? sprintf("[%s] %s", u, type[i]) : sprintf("%s", type[i]))
+  }
+
+  END {
+    if (!me) {
+      print "the element moved between the check and the read — run snapshot.sh again" > "/dev/stderr"
+      exit 4
+    }
+
+    lbl = best(me)
+    printf "[%s] %s%s   (%d,%d) %dx%d\n", U, type[me],
+      (lbl != "" ? sprintf(" \"%s\"", lbl) : ""), x[me], y[me], w[me], h[me]
+
+    p = byserial[parent[me]]
+    if (p) {
+      inside = (x[me] >= x[p] - 2 && y[me] >= y[p] - 2 &&
+                x[me] + w[me] <= x[p] + w[p] + 2 && y[me] + h[me] <= y[p] + h[p] + 2)
+      printf "    parent   %s (%d,%d) %dx%d — %s\n", type[p], x[p], y[p], w[p], h[p],
+        (inside ? "contained" : "THIS ELEMENT ESCAPES IT")
+    } else {
+      print  "    parent   none — this is the root"
+    }
+
+    # Nearest sibling above and below, by edge-to-edge gap.
+    bestUp = -1; bestDn = -1
+    for (i = 1; i <= n; i++) {
+      if (i == me || parent[i] != parent[me]) continue
+      if (y[i] + h[i] <= y[me]) {
+        g = y[me] - (y[i] + h[i]); if (bestUp < 0 || g < bestUp) { bestUp = g; upi = i }
+      }
+      if (y[i] >= y[me] + h[me]) {
+        g = y[i] - (y[me] + h[me]); if (bestDn < 0 || g < bestDn) { bestDn = g; dni = i }
+      }
+    }
+    if (bestUp >= 0) printf "    above    %s, gap %dpt\n", name(upi), bestUp
+    else             print  "    above    nothing at this level"
+    if (bestDn >= 0) printf "    below    %s, gap %dpt\n", name(dni), bestDn
+    else             print  "    below    nothing at this level"
+
+    if (lbl != "")
+      printf "    text     \"%s\" — %s\n", lbl,
+        ((lbl ~ /…$/ || lbl ~ /\.\.\.$/) ? "TRUNCATED BY THE OS" : "not truncated")
+
+    ov = ""
+    for (i = 1; i <= n; i++) {
+      if (i == me || parent[i] != parent[me]) continue
+      ox = span(x[me], x[me] + w[me], x[i], x[i] + w[i])
+      oy = span(y[me], y[me] + h[me], y[i], y[i] + h[i])
+      if (ox > 2 && oy > 2)
+        ov = ov sprintf("%s%s by %dpt", (ov == "" ? "" : ", "), name(i), (ox < oy ? ox : oy))
+    }
+    printf "    overlaps %s\n", (ov != "" ? ov : "none")
+
+    if (WW > 0 && WH > 0) {
+      off = 0
+      if (x[me] + w[me] > WW) off = x[me] + w[me] - WW
+      if (y[me] + h[me] > WH && y[me] + h[me] - WH > off) off = y[me] + h[me] - WH
+      if (x[me] < 0 && -x[me] > off) off = -x[me]
+      if (y[me] < 0 && -y[me] > off) off = -y[me]
+      printf "    screen   %dx%d — %s\n", WW, WH,
+        (off > 2 ? sprintf("THIS ELEMENT HANGS %dpt OFF IT", off) : "fully on it")
+    }
+
+    printf "    hit area %dx%d — %s the %dpt minimum\n", w[me], h[me],
+      ((w[me] < MINHIT || h[me] < MINHIT) ? "BELOW" : "meets"), MINHIT
+  }
+'

package/scripts/common/open.sh

@@ -0,0 +1,131 @@
+#!/usr/bin/env bash
+# open.sh — hand a URL to the device and say where it landed.
+#
+#   open.sh <url> [--expect-app <id>] [--timeout N]
+#
+# This is how deep links are tested: `open.sh myapp://transfer/123` asks the
+# system to route the link exactly as it would if the user had tapped it in a
+# message, which is the thing under test. An http(s) URL works too and lands in
+# the browser.
+#
+# WHY IT VERIFIES, AND WHAT IT CAN HONESTLY VERIFY
+#
+# Handing over a URL always "succeeds": the system accepts it and the caller is
+# told nothing about whether anything opened. A link with a typo'd scheme is
+# accepted and silently does nothing, so a bare open would report success for
+# the exact failure a deep-link test exists to catch.
+#
+# So this waits for the screen to change, and reports which app ended up in
+# front. `--expect-app` turns that report into a check: the step fails unless
+# the named app is the one that answered.
+#
+#   open.sh myapp://pay/9 --expect-app com.example.myapp
+#
+# It cannot verify that the app routed the link to the *right screen*. Assert
+# that yourself with `wait` on something only that screen has.
+#
+# --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 URL was accepted and the screen changed
+# exit 1  usage error
+# exit 3  the device driver is unreachable — run doctor.sh
+# exit 4  nothing changed, or a different app answered than --expect-app named
+
+# 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_open_url, drv_foreground_app, drv_fingerprint) and the lookup
+# helpers every adapter implements. Nothing here may learn that WebDriverAgent
+# or UiAutomator2 exists.
+source "$(dirname "${BASH_SOURCE[0]}")/lib.sh"
+
+URL=""
+EXPECT=""
+TIMEOUT=""
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --expect-app)
+      [ $# -ge 2 ] || die "--expect-app needs a bundle id or package name" 1
+      EXPECT="$2"; shift 2 ;;
+    --timeout)
+      [ $# -ge 2 ] || die "--timeout needs a number of seconds" 1
+      case "$2" in (*[!0-9]*|"") die "--timeout needs a positive integer, got: $2" 1 ;; esac
+      TIMEOUT="$2"; shift 2 ;;
+    --snapshot) act_snapshot_on; shift ;;
+    -h|--help) awk 'NR > 1 { if (!/^#/) exit; sub(/^# ?/, ""); print }' "${BASH_SOURCE[0]}"; exit 0 ;;
+    -*) die "unknown argument: $1 (usage: open.sh <url> [--expect-app <id>] [--timeout N])" 1 ;;
+    *)
+      [ -z "$URL" ] || die "only one url is supported, got '$URL' and '$1'" 1
+      URL="$1"; shift ;;
+  esac
+done
+
+[ -n "$URL" ] || die "missing url (usage: open.sh <url> [--expect-app <id>])" 1
+
+# A URL with no scheme is the commonest way to write one that silently does
+# nothing, so it is refused here rather than handed over to be ignored.
+case "$URL" in
+  *://*) ;;
+  *:*) ;;
+  *) die "'$URL' has no scheme — a deep link needs one, e.g. myapp://path or https://example.com" 1 ;;
+esac
+
+load_config
+[ -n "$TIMEOUT" ] || TIMEOUT="$(cfg '.timeouts.wait_seconds' '15')"
+POLL_MS="$(cfg '.timeouts.poll_ms' '400')"
+
+src="$(fetch_source)"
+before="$(drv_fingerprint "$src")"
+before_app="$(drv_foreground_app || true)"
+
+# EXIT 4, NOT 3, AND THE DIFFERENCE NOW MATTERS.
+#
+# A refusal here means the system had no handler for the scheme — a finding, and
+# usually the finding the test was written to make. It is not a connectivity
+# problem. Connectivity problems never reach this line: the adapters raise those
+# as exit 3 from inside the request itself.
+#
+# Getting this wrong was worse than untidy once callers began retrying exit 3
+# automatically. A typo'd scheme would have been reported as a dropped
+# connection, sent the runner through a full driver restart, and then failed
+# anyway — burning a recovery cycle on a link that was never going to open.
+err="$(drv_open_url "$URL" || true)"
+[ -z "$err" ] || die "the system would not open $URL — $err" 4
+
+deadline=$(( $(date +%s) + TIMEOUT ))
+changed=0
+while [ "$(date +%s)" -lt "$deadline" ]; do
+  now_src="$(try_fetch_source || true)"
+  if [ -n "$now_src" ]; then
+    [ "$(drv_fingerprint "$now_src")" != "$before" ] && { changed=1; break; }
+  fi
+  sleep "$(awk -v ms="$POLL_MS" 'BEGIN { printf "%.2f", ms / 1000 }')"
+done
+
+after_app="$(drv_foreground_app || true)"
+
+if [ -n "$EXPECT" ]; then
+  [ "$after_app" = "$EXPECT" ] \
+    || die "opened $URL but $EXPECT is not in front — ${after_app:-nothing identifiable} is. The link may have no handler, or another app claims that scheme" 4
+  printf 'OK opened %s — %s came to the front\n' "$URL" "$after_app"
+  act_snapshot_now
+  exit 0
+fi
+
+if [ "$changed" -eq 0 ]; then
+  die "opened $URL but nothing changed within ${TIMEOUT}s — the scheme probably has no handler installed${after_app:+ (still in $after_app)}" 4
+fi
+
+
+if [ -n "$after_app" ] && [ "$after_app" != "$before_app" ]; then
+  printf 'OK opened %s — %s came to the front\n' "$URL" "$after_app"
+else
+  printf 'OK opened %s — the screen changed%s\n' "$URL" "${after_app:+, still in $after_app}"
+fi
+act_snapshot_now

package/scripts/common/screenshot.sh

@@ -0,0 +1,102 @@
+#!/usr/bin/env bash
+# screenshot.sh — the screen as an image, for the things a tree cannot say.
+#
+#   screenshot.sh [name] [--scale N] [--full]
+#
+# Prints the path and nothing else, so the output can be used as an argument.
+#
+# READ snapshot.sh FIRST. It costs roughly a third as much, it can be measured,
+# and it answers most questions. This verb is for the ones it cannot: a wrong
+# icon, a blurry asset, a colour, a contrast, a gradient. Neither XCUITest nor
+# UiAutomator reports any of those, so the only way to know is to look.
+#
+#   --scale N   longest edge, in pixels. Default 768, which is roughly 360
+#               tokens and still shows the layout. --scale 0 leaves it alone.
+#   --full      the same as --scale 0. A phone screen at full size costs about
+#               1,500 tokens after the model downscales it anyway.
+#
+# CAPTURE-PROTECTED FIELDS RENDER BLANK. Apps that mark secure inputs render
+# them as empty regions in any captured image; the pixels are genuinely absent.
+# A blank region here is not evidence the field failed to draw — read it with
+# snapshot.sh. This script says so whenever a text input is on screen.
+#
+# exit 0  file written
+# exit 1  usage error
+# exit 2  could not write the file
+# exit 3  the driver is unreachable — run doctor.sh
+
+source "$(dirname "${BASH_SOURCE[0]}")/lib.sh"
+
+NAME=""
+SCALE=768
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --scale)
+      [ $# -ge 2 ] || die "--scale needs a number" 1
+      case "$2" in *[!0-9]*|"") die "--scale needs a non-negative integer, got: $2" 1 ;; esac
+      SCALE="$2"; shift 2 ;;
+    --full) SCALE=0; shift ;;
+    -h|--help) awk 'NR > 1 { if (!/^#/) exit; sub(/^# ?/, ""); print }' "${BASH_SOURCE[0]}"; exit 0 ;;
+    -*) die "unknown argument: $1 (usage: screenshot.sh [name] [--scale N] [--full])" 1 ;;
+    *)
+      [ -z "$NAME" ] || die "too many arguments (usage: screenshot.sh [name] [--scale N])" 1
+      NAME="$1"; shift ;;
+  esac
+done
+
+load_config
+dir="$(run_dir)"
+
+if [ -n "$NAME" ]; then
+  # A name is used to build a path, so it must not be able to escape the run
+  # directory or collide with shell parsing.
+  case "$NAME" in
+    */*|..*) die "name must not contain '/' or start with '..': $NAME" 1 ;;
+  esac
+  NAME="${NAME%.png}"
+  out="$dir/$NAME.png"
+else
+  n=1
+  while [ -e "$(printf '%s/screen-%03d.png' "$dir" "$n")" ]; do n=$((n + 1)); done
+  out="$(printf '%s/screen-%03d.png' "$dir" "$n")"
+fi
+
+capture_png "$out" || rc=$?
+case "${rc:-0}" in
+  0) ;;
+  2) die "could not write the screenshot into $out" 2 ;;
+  *) die "the driver returned no usable image — run $(as_cmd doctor)" 3 ;;
+esac
+
+# sips ships with macOS, so downscaling costs no dependency. -Z fits the longest
+# edge and preserves the aspect ratio, which matters more than it sounds: a
+# squashed screenshot is a layout bug that is not in the application.
+#
+# A resize that fails is a warning, not a failure. The image is already on disk
+# and is still the truth about the screen; refusing to hand it over because it
+# is larger than asked for would lose the thing the caller wanted.
+if [ "$SCALE" -gt 0 ]; then
+  sips -Z "$SCALE" "$out" >/dev/null 2>&1 \
+    || printf 'warning: could not resize %s to %spx, so it is at full size\n' "$out" "$SCALE" >&2
+fi
+
+# Which elements are at risk cannot be decided from the element type. On the app
+# this was built against, the password field reports as a plain TextField with
+# no secure marker of any kind, yet does not appear in the captured image. So
+# any text input is treated as suspect: a false warning costs one line, a missed
+# one costs a wrong conclusion about the screen.
+if rows="$(snapshot_rows 2>/dev/null)"; then
+  inputs="$(printf '%s\n' "$rows" | awk -F'|' '
+    $1 == "WINDOW" { next }
+    $4 ~ /TextField|SecureTextField|EditText|TextView|SearchField/ && $10 + 0 > 0 && $11 + 0 > 0 {
+      printf "  %s label:%s value:%s at %s,%s %sx%s\n", $4, $6, $7, $8, $9, $10, $11 }')"
+  if [ -n "$inputs" ]; then
+    printf 'warning: %s text input(s) on screen; capture-protected inputs render blank here even though they are on the device. Read them with snapshot.sh — a blank region is not evidence the field failed to render\n' \
+      "$(printf '%s\n' "$inputs" | wc -l | tr -d ' ')" >&2
+    printf '%s\n' "$inputs" >&2
+  fi
+else
+  printf 'warning: the tree could not be read, so capture-protected inputs were not checked for — treat blank regions in this image as unknown, not absent\n' >&2
+fi
+
+printf '%s\n' "$out"

package/scripts/common/scroll.sh

@@ -0,0 +1,177 @@
+#!/usr/bin/env bash
+# scroll.sh — bring content into view.
+#
+#   scroll.sh <up|down|left|right> [--times N]
+#   scroll.sh --until <selector> [--direction down] [--max N] [--index N]
+#
+# DIRECTION MEANS WHERE THE CONTENT IS, NOT WHERE THE FINGER GOES
+#
+# `scroll.sh down` reveals what is further down the page. The finger travels
+# upwards to do that. This is the opposite of `swipe.sh --direction up`, which
+# describes the gesture, and the two are separated on purpose: mixing the
+# physical and the intentional reading into one word is how everyone ends up
+# scrolling the wrong way for their first hour with a tool.
+#
+#   scroll  = where you want to go       (intent)
+#   swipe   = where your thumb moves     (gesture)
+#
+# --until polls with the same exact matching tap.sh uses, so "scrolled to it"
+# and "can tap it" cannot disagree. It stops as soon as the selector matches, or
+# when the screen stops changing — a list that has hit its end is reported as
+# such rather than scrolled at forever.
+#
+# --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  scrolled, and for --until the selector is now on screen
+# exit 1  usage error
+# exit 3  the device driver is unreachable — run doctor.sh
+# exit 4  --until never found it
+
+# 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"
+
+DIRECTION=""
+TIMES=1
+UNTIL=""
+MAX=""
+INDEX=""
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    up|down|left|right)
+      [ -z "$DIRECTION" ] || die "direction given twice: '$DIRECTION' and '$1'" 1
+      DIRECTION="$1"; shift ;;
+    --direction)
+      [ $# -ge 2 ] || die "--direction needs up, down, left or right" 1
+      case "$2" in up|down|left|right) ;; *) die "--direction must be up, down, left or right, got: $2" 1 ;; esac
+      DIRECTION="$2"; shift 2 ;;
+    --until)
+      [ $# -ge 2 ] || die "--until needs a selector" 1
+      UNTIL="$2"; shift 2 ;;
+    --times)
+      [ $# -ge 2 ] || die "--times needs a number" 1
+      case "$2" in (*[!0-9]*|"") die "--times needs a positive integer, got: $2" 1 ;; esac
+      [ "$2" -gt 0 ] || die "--times must be greater than zero" 1
+      TIMES="$2"; shift 2 ;;
+    --max)
+      [ $# -ge 2 ] || die "--max needs a number" 1
+      case "$2" in (*[!0-9]*|"") die "--max needs a positive integer, got: $2" 1 ;; esac
+      [ "$2" -gt 0 ] || die "--max must be greater than zero" 1
+      MAX="$2"; shift 2 ;;
+    --index)
+      [ $# -ge 2 ] || die "--index needs a number" 1
+      INDEX="$2"; shift 2 ;;
+    --snapshot) act_snapshot_on; shift ;;
+    -h|--help) awk 'NR > 1 { if (!/^#/) exit; sub(/^# ?/, ""); print }' "${BASH_SOURCE[0]}"; exit 0 ;;
+    *) die "unknown argument: $1 (usage: scroll.sh <up|down|left|right> [--times N] | scroll.sh --until <selector>)" 1 ;;
+  esac
+done
+
+[ -n "$DIRECTION" ] || [ -n "$UNTIL" ] \
+  || die "missing direction (usage: scroll.sh <up|down|left|right> [--times N] | scroll.sh --until <selector>)" 1
+[ -n "$DIRECTION" ] || DIRECTION=down
+
+load_config
+[ -n "$MAX" ] || MAX="$(cfg '.scroll.max_swipes' '15')"
+
+read -r WIN_W WIN_H <<< "$(window_size)"
+
+# A swipe over the middle 60% of the screen. The margins matter: starting at the
+# very edge triggers the system's back gesture on iOS, and ending at the very
+# top or bottom lands in the status bar or the home indicator.
+CX=$(( WIN_W / 2 ))
+CY=$(( WIN_H / 2 ))
+NEAR_Y=$(( WIN_H * 70 / 100 ))
+FAR_Y=$(( WIN_H * 30 / 100 ))
+NEAR_X=$(( WIN_W * 80 / 100 ))
+FAR_X=$(( WIN_W * 20 / 100 ))
+
+case "$DIRECTION" in
+  down)  FX=$CX; FY=$NEAR_Y; TX=$CX; TY=$FAR_Y ;;
+  up)    FX=$CX; FY=$FAR_Y;  TX=$CX; TY=$NEAR_Y ;;
+  right) FX=$NEAR_X; FY=$CY; TX=$FAR_X; TY=$CY ;;
+  left)  FX=$FAR_X;  FY=$CY; TX=$NEAR_X; TY=$CY ;;
+esac
+
+one_swipe() {
+  local err
+  err="$(drv_drag "$FX" "$FY" "$TX" "$TY" 200 || true)"
+  [ -z "$err" ] || die "scroll failed — $err" 3
+}
+
+# --- plain scroll -------------------------------------------------------------
+
+if [ -z "$UNTIL" ]; then
+  act_before
+  i=0
+  while [ "$i" -lt "$TIMES" ]; do
+    one_swipe
+    i=$((i + 1))
+  done
+  act_report SCROLL "$DIRECTION — $TIMES time(s)"
+  journal_append scroll "$DIRECTION $TIMES" "" "" "" "" 0 0 0 0 "$DT_ACT_HASH"
+  exit 0
+fi
+
+# --- scroll until visible -----------------------------------------------------
+
+parse_selector "$UNTIL"
+[ "$SEL_KIND" != xy ] \
+  || die "--until needs id:, label: or text: — a point is always 'visible'" 1
+
+found_now() {
+  local src matches
+  src="$(fetch_source)"
+  matches="$(match_elements "$src" "$SEL_KIND" "$SEL_VALUE" || true)"
+  [ -n "$matches" ] || return 1
+  printf '%s\n' "$matches" | awk -F'|' 'NR == 1 { printf "%s at %s,%s,%s,%s", $5, $1, $2, $3, $4 }'
+}
+
+# Recorded even though nothing has been swiped yet: this branch performs no
+# action, and act_report needs a before-state or it says the screen could not be
+# read — which would be a stranger answer than "unchanged".
+act_before
+if hit="$(found_now)"; then
+  act_report SCROLL "$DIRECTION — $UNTIL already visible ($hit), 0 swipes"
+  exit 0
+fi
+
+prev=""
+n=0
+while [ "$n" -lt "$MAX" ]; do
+  one_swipe
+  n=$((n + 1))
+
+  if hit="$(found_now)"; then
+    act_report SCROLL "$DIRECTION — found $UNTIL after $n swipe(s) ($hit)"
+    exit 0
+  fi
+
+  # A fingerprint of the screen. When two consecutive swipes leave it unchanged
+  # the list has hit its end, and continuing to swipe would burn the whole --max
+  # budget to report the same failure later.
+  #
+  # Values are excluded: on an idle screen a value-sensitive fingerprint changed
+  # on every sample, because carousels and page indicators animate themselves.
+  # Positions are kept, because a scroll that moves nothing is exactly the
+  # condition being detected.
+  src_now="$(fetch_source)"
+  now="$(drv_fingerprint_pos "$src_now")"
+  if [ "$now" = "$prev" ]; then
+    die "scrolled $DIRECTION $n time(s) and reached the end without finding $UNTIL" 4
+  fi
+  prev="$now"
+done
+
+die "scrolled $DIRECTION $MAX time(s) without finding $UNTIL — raise --max if the list is longer" 4

package/scripts/common/snapshot.sh

@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+# snapshot.sh — what is on the screen, with the geometry, numbered.
+#
+#   snapshot.sh [--all] [--grep S]
+#
+# This is the default way to read a screen and the cheapest one. A dense screen
+# comes back as 25–50 lines; the same screen as an image costs roughly three
+# times as many tokens and cannot be measured.
+#
+#   [7]  Button #btn_login "Đăng nhập"  (24,612)  327x50  enabled
+#
+#   ⚠ hit area below the 44pt minimum — [3] [7] [19]
+#
+# #btn_login is the accessibility identifier, printed when the app supplies one.
+# It is the only selector that survives rewritten copy and a second language, so
+# it is worth preferring over the label; a warning names the controls that have
+# none, which is a fault in the app rather than on the screen.
+#
+# The number in brackets is a uid, and it is only valid until the next snapshot.
+# `tap 7` re-reads the screen and requires the element still to be exactly what
+# was numbered — same type, same text, same rectangle. If it is not, the tap is
+# refused rather than aimed at wherever that element used to be.
+#
+# Warnings are grouped rather than printed beside each element: a list of six
+# identical rows otherwise reports the same fault six times, and an agent that
+# reads fifty warnings on every screen stops reading warnings. Which sibling an
+# element overlaps is a question for measure.sh, which exists for it.
+#
+#   --all      every element, no filter
+#   --grep S   case-insensitive substring of type, id, label or value. Searches
+#              the whole tree, including what the filter hides, so it can find
+#              something that is present but off screen.
+#
+# exit 0  the screen was read
+# exit 1  usage error
+# exit 3  the driver is unreachable — run doctor.sh
+# exit 4  nothing matched
+
+source "$(dirname "${BASH_SOURCE[0]}")/lib.sh"
+
+ALL=0
+GREP=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --all) ALL=1; shift ;;
+    --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: snapshot.sh [--all] [--grep S])" 1 ;;
+  esac
+done
+
+load_config
+
+rows="$(snapshot_rows)"
+[ -n "$rows" ] || die "the driver returned an empty tree — run $(as_cmd doctor)" 3
+
+# render_rows and write_uid_store live in lib.sh, because an action asked for
+# `--snapshot` produces exactly this and must number it exactly this way. Two
+# copies of the numbering rule is how `tap 7` comes to mean two different things
+# depending on which verb printed the 7.
+out="$(render_rows "$rows" "$ALL" "$GREP")" \
+  || die "nothing on this screen matched${GREP:+ --grep '$GREP'}" 4
+
+write_uid_store "$rows" "$ALL" "$GREP" \
+  || die "could not write the uid store at $(uid_store)" 2
+
+printf '%s\n' "$out"