device-devtools-mcp 0.1.0

package/scripts/common/swipe.sh

@@ -0,0 +1,171 @@
+#!/usr/bin/env bash
+# swipe.sh — drag from one point to another.
+#
+#   swipe.sh <up|down|left|right> [--duration MS]
+#   swipe.sh <from> <to> [--duration MS]
+#   swipe.sh --direction <up|down|left|right> [--duration MS]
+#
+# Both endpoints are selectors. An element selector resolves to that element's
+# centre, exactly as tap.sh does, and is subject to the same rule: it must match
+# EXACTLY ONE visible element or nothing happens.
+#
+#   swipe.sh label:Inbox xy:200,100
+#   swipe.sh xy:214,700 xy:214,200 --duration 300
+#
+# --direction describes where the FINGER travels. That is the opposite reading
+# from scroll.sh, where the direction is where the content you want lives:
+#
+#   swipe --direction up   ==   scroll down
+#
+# Both exist because one is a gesture and the other is an intent, and collapsing
+# them into a single word is how everyone spends their first hour scrolling the
+# wrong way.
+#
+# --duration is the press-and-hold time before the drag begins, in milliseconds.
+# It is not the travel time. Short values read as a flick and scroll with
+# momentum; longer ones read as a deliberate drag and do not. The default of
+# 200ms is a flick, which is what "swipe" usually means.
+#
+# --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  swiped
+# exit 1  usage error
+# exit 3  the device driver is unreachable — run doctor.sh
+# exit 4  an endpoint selector did not resolve to exactly one element
+
+# 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"
+
+FROM=""
+TO=""
+SWIPE_DIR=""
+DURATION_MS=200
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --duration)
+      [ $# -ge 2 ] || die "--duration needs a number of milliseconds" 1
+      case "$2" in (*[!0-9]*|"") die "--duration needs a non-negative integer, got: $2" 1 ;; esac
+      DURATION_MS="$2"; shift 2 ;;
+    --snapshot) act_snapshot_on; shift ;;
+    -h|--help) awk 'NR > 1 { if (!/^#/) exit; sub(/^# ?/, ""); print }' "${BASH_SOURCE[0]}"; exit 0 ;;
+    --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
+      SWIPE_DIR="$2"; shift 2 ;;
+    -*) die "unknown argument: $1 (usage: swipe.sh <up|down|left|right> | swipe.sh <from> <to> [--duration MS])" 1 ;;
+    *)
+      if   [ -z "$FROM" ]; then FROM="$1"
+      elif [ -z "$TO" ];   then TO="$1"
+      else die "swipe.sh takes exactly two selectors, got a third: $1" 1
+      fi
+      shift ;;
+  esac
+done
+
+# A LONE DIRECTION WORD IS A DIRECTION, NOT AN ENDPOINT.
+#
+# `scroll.sh right` has always meant the direction; `swipe.sh right` used to
+# mean "start at the element matching 'right'" and then failed for want of a
+# second endpoint. Two shapes for the same idea, and the MCP layer sends the
+# positional form, so every swipe an agent asked for died on the difference.
+#
+# Decided after parsing rather than during it, so `swipe.sh up down` is still
+# two endpoints rather than a direction plus a stray.
+if [ -z "$SWIPE_DIR" ] && [ -n "$FROM" ] && [ -z "$TO" ]; then
+  case "$FROM" in
+    up|down|left|right) SWIPE_DIR="$FROM"; FROM="" ;;
+  esac
+fi
+
+if [ -n "$SWIPE_DIR" ]; then
+  [ -z "$FROM" ] && [ -z "$TO" ] \
+    || die "--direction and explicit endpoints cannot be combined — use one or the other" 1
+else
+  [ -n "$FROM" ] && [ -n "$TO" ] \
+    || die "missing endpoint (usage: swipe.sh <from> <to> [--duration MS] | swipe.sh --direction <dir>)" 1
+fi
+
+load_config
+
+SRC=""
+
+# resolve_point <selector> <role> — sets PT_X, PT_Y and PT_DESC.
+resolve_point() {
+  local sel="$1" role="$2" matches n all cands
+  parse_selector "$sel"
+
+  if [ "$SEL_KIND" = xy ]; then
+    parse_xy "$SEL_VALUE"
+    PT_X="$XY_X"; PT_Y="$XY_Y"; PT_DESC="point"
+    return 0
+  fi
+
+  # One tree read serves both endpoints: two reads cost ~3.8s and, worse, could
+  # resolve against two different screens.
+  [ -n "$SRC" ] || SRC="$(fetch_source)"
+
+  matches="$(match_elements "$SRC" "$SEL_KIND" "$SEL_VALUE" || true)"
+  if [ -z "$matches" ]; then
+    cands="$(candidate_elements "$SRC" "$SEL_VALUE" 5 | join_lines '; ' || true)"
+    [ -z "$cands" ] \
+      && die "$role endpoint: nothing matches $SEL_DESC — run $(as_cmd tree)" 4
+    die "$role endpoint: nothing matches $SEL_DESC — did you mean: $cands" 4
+  fi
+
+  n="$(printf '%s\n' "$matches" | wc -l | tr -d ' ')"
+  if [ "$n" -gt 1 ]; then
+    all="$(printf '%s\n' "$matches" \
+      | awk -F'|' 'NR <= 5 { printf "[%d] %s at %s,%s,%s,%s\n", NR - 1, $5, $1, $2, $3, $4 }' | join_lines '; ')"
+    die "$role endpoint: $SEL_DESC matches $n elements, refusing to guess: $all" 4
+  fi
+
+  PT_X="$(printf '%s' "$matches" | awk -F'|' '{ print $1 + $3 / 2 }')"
+  PT_Y="$(printf '%s' "$matches" | awk -F'|' '{ print $2 + $4 / 2 }')"
+  PT_DESC="$(printf '%s' "$matches" | awk -F'|' '{ print $5 }')"
+}
+
+if [ -n "$SWIPE_DIR" ]; then
+  read -r WIN_W WIN_H <<< "$(window_size)"
+  # Kept off the very edges: starting at x=0 triggers the system back gesture,
+  # and the extremes of y are the status bar and 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 "$SWIPE_DIR" in
+    up)    FX=$CX; FY=$NEAR_Y; TX=$CX; TY=$FAR_Y ;;
+    down)  FX=$CX; FY=$FAR_Y;  TX=$CX; TY=$NEAR_Y ;;
+    left)  FX=$NEAR_X; FY=$CY; TX=$FAR_X; TY=$CY ;;
+    right) FX=$FAR_X;  FY=$CY; TX=$NEAR_X; TY=$CY ;;
+  esac
+  FROM="--direction $SWIPE_DIR"; TO=""
+  FD="point"; TD="point"
+else
+  resolve_point "$FROM" from
+  FX="$PT_X"; FY="$PT_Y"; FD="$PT_DESC"
+  resolve_point "$TO" to
+  TX="$PT_X"; TY="$PT_Y"; TD="$PT_DESC"
+fi
+
+act_before
+err="$(drv_drag "$FX" "$FY" "$TX" "$TY" "$DURATION_MS" || true)"
+[ -z "$err" ] || die "swipe from $FX,$FY to $TX,$TY failed — $err" 3
+
+if [ -n "$SWIPE_DIR" ]; then
+  act_report SWIPE "$SWIPE_DIR — $FX,$FY → $TX,$TY over ${DURATION_MS}ms"
+  journal_append swipe "$SWIPE_DIR" "" "" "" "" "$FX" "$FY" 0 0 "$DT_ACT_HASH"
+else
+  printf 'OK swiped %s → %s — %s %s,%s → %s %s,%s over %sms\n' \
+    "$FROM" "$TO" "$FD" "$FX" "$FY" "$TD" "$TX" "$TY" "$DURATION_MS"
+fi

package/scripts/common/tap.sh

@@ -0,0 +1,226 @@
+#!/usr/bin/env bash
+# tap.sh — tap exactly one thing, or refuse.
+#
+#   tap.sh <selector> [--index N] [--count N]
+#
+# selector is one of:
+#   id:<identifier>   accessibilityIdentifier, exact match
+#   label:<text>      accessibility label, exact match
+#   text:<text>       the element's value, exact match. This is how fields that
+#                     carry neither an identifier nor a label are addressed at
+#                     all — a password field with only a placeholder, say.
+#   kind:<Type>       the element's class, the word snapshot prints first on the
+#                     line: kind:SecureTextField. For a control with no
+#                     identifier, no label and no value — usually with --index.
+#
+# EVERY SELECTOR MATCHES WHOLE. `text:OTP` does not find a label that contains
+# OTP; `snapshot --grep OTP` does. Reading may guess, acting may not — a
+# substring match is how a tap lands on the caption instead of the button.
+#   xy:<x>,<y>        raw point, in the same coordinate space tree.sh prints
+#
+#   --index N         act on the Nth match, zero-based, in tree order
+#   --count N         tap the same point N times, N up to 20
+#
+# WHY --count EXISTS, AND WHY IT RESOLVES ONCE.
+#
+# A six-digit code is six taps on one key. Six separate calls is six round trips
+# and six identical tool calls, which some agent harnesses treat as a loop to
+# break out of — one refused to make the sixth call at all. So the repetition
+# happens here.
+#
+# The element is resolved once and the same point is tapped N times. Re-reading
+# the tree between taps would be slower and would also be wrong: a keypad key
+# does not move, and a uid that went stale mid-sequence should stop the sequence
+# rather than silently retarget it.
+#
+# For id:, label: and text: the selector must resolve to EXACTLY ONE visible
+# element, unless --index says which one. Zero matches, or several without an
+# index, and this exits non-zero naming what it saw, without tapping anything.
+#
+# That strictness is the entire point. A wrong tap is worse than a stop: the
+# stop is visible and recoverable, while the wrong tap leaves the caller
+# reasoning confidently about a screen it is no longer on, and every step after
+# it compounds the error. Guessing "probably the first one" is how that happens.
+#
+# --index is the way through, and it is deliberately explicit. Other tools
+# resolve ambiguity implicitly and are usually right; when tree order changes,
+# the implicit choice silently starts acting on something else while the test
+# keeps passing. Written into the test, the intent survives.
+#
+# On success one line on stdout:
+#   OK tapped <selector> — <resolved by ...> <Type> at x,y,w,h → tapped cx,cy
+#
+# --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  tapped
+# exit 1  usage error
+# exit 3  the device driver is unreachable — run doctor.sh
+# exit 4  the selector did not resolve to exactly one element
+
+# 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=""
+COUNT=1
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --count)
+      [ $# -ge 2 ] || die "--count needs a number" 1
+      case "$2" in (*[!0-9]*|""|0) die "--count needs a positive integer, got: $2" 1 ;; esac
+      # Bounded, because the documented limit has to be enforced somewhere and
+      # an unbounded count is a way to hammer a real device by typo.
+      [ "$2" -le 20 ] || die "--count is capped at 20, got: $2" 1
+      COUNT="$2"; shift 2 ;;
+    --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 ;;
+    --snapshot) act_snapshot_on; shift ;;
+    -h|--help) awk 'NR > 1 { if (!/^#/) exit; sub(/^# ?/, ""); print }' "${BASH_SOURCE[0]}"; exit 0 ;;
+    -*) die "unknown argument: $1 (usage: tap.sh <selector> [--index N] [--count 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: tap.sh <selector> [--index N] [--count N])" 1
+
+load_config
+parse_selector "$SELECTOR"
+
+if [ "$SEL_KIND" = xy ]; then
+  parse_xy "$SEL_VALUE"
+  CX="$XY_X"
+  CY="$XY_Y"
+  # A uid arrives here as a point, because that is what uid_resolve produces
+  # after proving the element is still where it was numbered. Reporting it as
+  # "resolved by xy" would describe the mechanism instead of what was asked for,
+  # and the two are not the same claim: a raw point was never checked against
+  # anything, and a uid was.
+  case "$SEL_DESC" in
+    uid\ *) RESOLVED="resolved by $SEL_DESC"; DETAIL="verified still at $CX,$CY" ;;
+    *)      RESOLVED="resolved by xy";        DETAIL="point" ;;
+  esac
+else
+  src="$(fetch_source)"
+  # What the screen says right now, and only that. There is no fingerprint to
+  # fall back on any more: a screen that has moved on is read again, which costs
+  # one cheap call, instead of being matched against a recording from some
+  # earlier day.
+  matches="$(match_or_holding "$src" "$SEL_KIND" "$SEL_VALUE" || true)"
+  resolve_state
+
+  if [ -z "$matches" ]; then
+    # AN EXACT HIT THAT IS MERELY COVERED BEATS A LIST OF NEAR MISSES.
+    #
+    # This branch used to end at "nothing on screen contains it" while
+    # `snapshot --grep` was listing the very thing, because snapshot searches
+    # the whole tree and this searches what a user could touch. Both are right;
+    # only one of them was saying so.
+    note="$(invisible_note "$src" "$SEL_KIND" "$SEL_VALUE" || true)"
+    [ -n "$note" ] && die "$SEL_DESC matches nothing that can be tapped — $note" 4
+
+    # A selector matches a value WHOLE; --grep searches inside one. Said here
+    # because the list below otherwise reads as a contradiction: this line says
+    # nothing matched and then prints things that plainly contain the words.
+    cands="$(candidate_elements "$src" "$SEL_VALUE" 5 | join_lines '; ' || true)"
+    if [ -n "$cands" ]; then
+      die "nothing matches $SEL_DESC — a selector matches whole, and these merely contain it: $cands" 4
+    fi
+    if [ "$SEL_KIND" = text ]; then
+      note="$(holding_absence "$src" "$SEL_VALUE")"
+      [ -n "$note" ] && die "no control matched '$SEL_VALUE' — $note" 4
+    fi
+    if [ "$SEL_KIND" = kind ]; then
+      die "no visible $SEL_VALUE on this screen. What is here: $(kinds_on_screen "$src")" 4
+    fi
+    die "nothing matches $SEL_DESC and nothing on screen contains it — run $(as_cmd snapshot)" 4
+  fi
+
+  n="$(printf '%s\n' "$matches" | wc -l | tr -d ' ')"
+  if [ -n "$INDEX" ]; then
+    [ "$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")"
+  elif [ "$n" -gt 1 ]; then
+    # The numbers are the values --index takes, printed because a list without
+    # them is an invitation to guess, and guessing is the thing this refusal
+    # exists to prevent.
+    all="$(printf '%s\n' "$matches" \
+      | awk -F'|' 'NR <= 5 { printf "[%d] %s at %s,%s,%s,%s\n", NR - 1, $5, $1, $2, $3, $4 }' | join_lines '; ')"
+    die "$SEL_DESC matches $n elements, refusing to guess: $all — use --index N, or id:/xy:" 4
+  fi
+
+  IFS='|' read -r X Y W H TYPE EID ELB EVAL <<< "$matches"
+  CX=$(( X + W / 2 ))
+  CY=$(( Y + H / 2 ))
+  # Not `"...$([ -n "$INDEX" ] && printf ...)"`. A command substitution whose
+  # last command is false makes the whole assignment fail, and under `set -e`
+  # that ends the script with status 1 and no message at all.
+  if [ -n "$INDEX" ]; then
+    RESOLVED="resolved by $SEL_KIND index $INDEX of $n"
+  elif [ "$RESOLVE_HOW" = holding ]; then
+    RESOLVED="resolved by the control holding that text"
+  else
+    RESOLVED="resolved by $SEL_KIND"
+  fi
+  DETAIL="$TYPE at $X,$Y,$W,$H"
+fi
+
+# A TAP THE KEYBOARD SWALLOWS IS NOT A TAP, AND MUST NOT BE REPORTED AS ONE.
+#
+# Found on a real login screen: the submit button sits at the bottom, the
+# keyboard is up because the step before typed a password, and the driver still
+# reports the button visible and at its usual place. The tap goes to the
+# keyboard. `tap` printed OK, the app did nothing, and the suite stayed green
+# over an action that never happened — the worst failure available, because
+# nothing about it looks like a failure.
+#
+# Refusing costs one screen's worth of nothing on iOS, where the keyboard is
+# already in the tree, and one adb call on Android. Both are cheaper than a
+# green run that means nothing.
+#
+# Tapping the keyboard itself stays allowed: a key, or the keyboard as a whole,
+# is the thing being aimed at rather than the thing in the way.
+if [ "$SEL_KIND" != xy ]; then
+  # Settling for the label when the control itself is merely unreachable is the
+  # one failure that leaves no trace: one match is not ambiguous, so nothing is
+  # refused, and the run goes green over an action nobody performed.
+  twin="$(unhittable_twin "$src" "$SEL_KIND" "$SEL_VALUE" "$X" "$Y" "$W" "$H" 2>/dev/null || true)"
+  [ -z "$twin" ] || die "$SEL_KIND '$SEL_VALUE' also names $twin, which is on screen but not hittable — the only match left is $DETAIL, and tapping that acts on the label instead of the control; dismiss whatever covers it, or scroll it into view" 4
+
+  kb="$(keyboard_blocks "$src" "$X" "$Y" "$W" "$H" 2>/dev/null || true)"
+  [ -z "$kb" ] || die "the keyboard covers $DETAIL — a tap at $CX,$CY would land on the keyboard at ${kb// /,} and the app would see nothing; dismiss the keyboard first, or scroll the control clear of it" 4
+fi
+
+act_before
+i=1
+while [ "$i" -le "$COUNT" ]; do
+  err="$(drv_tap "$CX" "$CY" || true)"
+  [ -z "$err" ] || die "tap $i of $COUNT at $CX,$CY failed — $err" 3
+  i=$((i + 1))
+done
+
+if [ "$COUNT" -eq 1 ]; then
+  act_report TAP "$SELECTOR — $RESOLVED, $DETAIL → tapped $CX,$CY"
+else
+  act_report TAP "$SELECTOR — $RESOLVED, $DETAIL → tapped $CX,$CY ${COUNT} times"
+fi
+# X..EVAL are set only on the resolving path; a raw point has no element behind
+# it, and the journal records that honestly rather than inventing one.
+journal_append tap "$SEL_KIND:$SEL_VALUE" "${TYPE-}" "${EID-}" "${ELB-}" "${EVAL-}" \
+               "${X-0}" "${Y-0}" "${W-0}" "${H-0}" "$DT_ACT_HASH"

package/scripts/common/wait.sh

@@ -0,0 +1,212 @@
+#!/usr/bin/env bash
+# wait.sh — block until the screen satisfies a condition.
+#
+#   wait.sh <selector> [--gone] [--timeout N]
+#
+# selector is id:<identifier>, label:<text>, text:<value>, kind:<Type>, or a
+# plain string. EVERY ONE OF THEM MATCHES WHOLE — `text:OTP` does not find a
+# label that merely contains OTP. `snapshot --grep` is the one that searches
+# inside, because reading may guess and acting may not.
+#
+#   screen:<name>   wait until the SCREEN line reads exactly that name, or
+#   screen:#<hash>  exactly that hash. This is how a flow says where it expects
+#                   to be starting from, which is the assertion that stops it
+#                   tapping into a screen it was not written for.
+#
+#   (default)     wait until the selector matches at least one element
+#   --gone        wait until it matches none
+#   --timeout N   seconds; defaults to timeouts.wait_seconds from the config
+#
+# This exists so that nothing in this repo ever synchronises with `sleep`. A
+# fixed sleep is a guess about a device you cannot see: too short and the agent
+# acts on the previous screen, too long and every step pays for the worst case.
+# Polling a real condition is both faster and correct.
+#
+# One tree fetch costs about 1.9s against the device this was built on, which
+# dominates timeouts.poll_ms entirely — the real interval is roughly
+# 1.9s + poll_ms. Lowering poll_ms below a second buys nothing. Expect elapsed
+# times reported here to be quantised to about two seconds.
+#
+# On success one line on stdout:
+#   OK <selector> — <present|gone> after <N>s (<detail>)
+#
+# --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 condition held
+# exit 1  usage error
+# exit 3  the device driver is unreachable — run doctor.sh
+# exit 4  the condition did not hold before the timeout
+
+# 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=""
+GONE=0
+TIMEOUT=""
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --gone) GONE=1; shift ;;
+    --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
+      [ "$2" -gt 0 ] || die "--timeout must be greater than zero" 1
+      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: wait.sh <selector> [--gone] [--timeout 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: wait.sh <selector> [--gone] [--timeout N])" 1
+
+load_config
+
+# screen:<name> — WAIT FOR A PLACE, NOT FOR A CONTROL.
+#
+# Handled before parse_selector, and deliberately not added to the selector
+# grammar: a screen is not an element, so `tap screen:Home` has no meaning and
+# every verb that took a selector would need a guard against it. One verb can
+# ask this question, so one verb knows the spelling.
+#
+# The name is the one snapshot prints on its SCREEN line, matched exactly —
+# a substring would make `screen:Home` pass on `HomeOnboarding`, and an assertion
+# that passes on the wrong screen is worse than none. `screen:#6360` matches the
+# hash instead, which is what to use when the app publishes no useful title.
+#
+# This is what makes a flow able to check where it is starting from. Logging in
+# has three different paths depending on whether the device is activated, and a
+# flow that taps into the wrong one produces a session's worth of confident
+# nonsense.
+case "$SELECTOR" in
+  screen:*)
+    WANT="${SELECTOR#screen:}"
+    [ -n "$WANT" ] || die "screen: needs a name or a #hash — got '$SELECTOR'" 1
+    [ "$GONE" -eq 0 ] || die "--gone makes no sense for a screen: you are always on one" 1
+    [ -n "$TIMEOUT" ] || TIMEOUT="$(cfg '.timeouts.wait_seconds' '15')"
+    POLL_MS="$(cfg '.timeouts.poll_ms' '400')"
+    poll_s="$(awk -v ms="$POLL_MS" 'BEGIN { printf "%.3f", ms / 1000 }')"
+    SECONDS=0
+    while :; do
+      split_state "$(screen_state || true)"
+      case "$WANT" in
+        \#*) [ "#$ST_HASH" = "$WANT" ] && { printf 'OK %s — arrived after %ss ("%s")\n' "$SELECTOR" "$SECONDS" "$ST_NAME"; act_snapshot_now; exit 0; } ;;
+        *)   [ "$ST_NAME" = "$WANT" ]  && { printf 'OK %s — arrived after %ss (#%s)\n' "$SELECTOR" "$SECONDS" "$ST_HASH"; act_snapshot_now; exit 0; } ;;
+      esac
+      [ "$SECONDS" -lt "$TIMEOUT" ] || break
+      sleep "$poll_s"
+    done
+    if [ -z "$ST_HASH" ]; then
+      die "timeout after ${TIMEOUT}s: the screen could not be read at all — run $(as_cmd doctor)" 3
+    fi
+    die "timeout after ${TIMEOUT}s: this is \"$ST_NAME\" #$ST_HASH, not $SELECTOR" 4
+    ;;
+esac
+
+parse_selector "$SELECTOR"
+
+# Waiting on a coordinate cannot mean anything: a point is always "there".
+# Failing here is better than looping for the full timeout and reporting a
+# condition that was never checkable.
+[ "$SEL_KIND" != xy ] \
+  || die "xy selectors cannot be waited on — use id: or label:, or wait for an element near that point" 1
+
+[ -n "$TIMEOUT" ] || TIMEOUT="$(cfg '.timeouts.wait_seconds' '15')"
+POLL_MS="$(cfg '.timeouts.poll_ms' '400')"
+poll_s="$(awk -v ms="$POLL_MS" 'BEGIN { printf "%.3f", ms / 1000 }')"
+
+SECONDS=0
+last_count=0
+while :; do
+  src="$(fetch_source)"
+  # The containing-control rule belongs in the loop, not after the timeout: a
+  # caption the driver calls invisible is on screen from the first poll, and
+  # making the step sit out the whole timeout before finding it would turn a
+  # correct answer into a slow one. The fingerprint stays after the timeout,
+  # where it cannot bind to something that merely resembles the target while the
+  # screen is still building.
+  matches="$(match_or_holding "$src" "$SEL_KIND" "$SEL_VALUE" || true)"
+
+  # THERE USED TO BE AN EARLY EXIT HERE, AND IT NEVER RAN.
+  #
+  # It was guarded by `[ -n "$(baseline_file)" ]` — a function belonging to the
+  # test layer that was deleted, so every poll ran `baseline_file` as a command,
+  # got "command not found" on stderr, and read the condition as false. Eight
+  # lines of that per wait, on a phone, for months, while the block they were
+  # guarding did nothing at all.
+  #
+  # Not resurrected. What it did was give up early once the screen had stopped
+  # changing, on the theory that whatever was going to appear had appeared —
+  # which is false for anything arriving over the network, and this app waits on
+  # a network. The timeout is the honest deadline, and the caller sets it.
+  if [ -z "$matches" ]; then last_count=0; else last_count="$(printf '%s\n' "$matches" | wc -l | tr -d ' ')"; fi
+
+  if [ "$GONE" -eq 1 ]; then
+    if [ "$last_count" -eq 0 ]; then
+      printf 'OK %s — gone after %ss\n' "$SELECTOR" "$SECONDS"
+      act_snapshot_now
+      exit 0
+    fi
+  elif [ "$last_count" -gt 0 ]; then
+    detail="$(printf '%s\n' "$matches" | awk -F'|' 'NR == 1 { printf "%s at %s,%s,%s,%s", $5, $1, $2, $3, $4 }')"
+    if [ "$last_count" -gt 1 ]; then detail="$last_count matches, first: $detail"; fi
+    resolve_state
+    if [ "$RESOLVE_HOW" = holding ]; then
+      detail="$detail, the control holding that text"
+    fi
+    printf 'OK %s — present after %ss (%s)\n' "$SELECTOR" "$SECONDS" "$detail"
+    act_snapshot_now
+    exit 0
+  fi
+
+  [ "$SECONDS" -lt "$TIMEOUT" ] || break
+  sleep "$poll_s"
+done
+
+# Say what was actually on screen. An agent that only learns "it timed out"
+# has to spend a screenshot to find out why; one that learns the nearest
+# candidates can usually recover on the spot.
+if [ "$GONE" -eq 1 ]; then
+  die "timeout after ${TIMEOUT}s: $SELECTOR still present ($last_count match(es))" 4
+fi
+
+note="$(invisible_note "$src" "$SEL_KIND" "$SEL_VALUE" || true)"
+[ -n "$note" ] && die "timeout after ${TIMEOUT}s: $SELECTOR never became actionable — $note" 4
+
+if [ "$SEL_KIND" = text ]; then
+  note="$(holding_absence "$src" "$SEL_VALUE")"
+  [ -n "$note" ] && die "timeout after ${TIMEOUT}s: no control matched '$SEL_VALUE' — $note" 4
+fi
+# "NEAR MATCHES" AFTER "NEVER APPEARED" READS LIKE A CONTRADICTION, AND IT WAS
+# ONE — REPORTED AS SUCH.
+#
+# `wait text:OTP` timed out and then listed a StaticText whose value contains
+# OTP. Both lines are true and the pair is unreadable, because the rule joining
+# them was never stated: A SELECTOR MATCHES A VALUE WHOLE. --grep searches
+# inside one, which is why reading finds things acting cannot.
+#
+# That difference is deliberate and stays. Substring matching is what makes a
+# tap land on the label instead of the button — the failure this tool is
+# arranged around. So the rule is said out loud instead.
+cands="$(candidate_elements "$src" "$SEL_VALUE" 3 | join_lines '; ' || true)"
+if [ -n "$cands" ]; then
+  die "timeout after ${TIMEOUT}s: nothing has the whole value '$SEL_VALUE' — a selector matches a value whole, while --grep searches inside one. '$SEL_VALUE' is inside: $cands. Name one of those in full, or use id:/kind:" 4
+fi
+if [ "$SEL_KIND" = kind ]; then
+  die "no visible $SEL_VALUE on this screen. What is here: $(kinds_on_screen "$src")" 4
+fi
+die "timeout after ${TIMEOUT}s: $SELECTOR never appeared — no element contains '$SEL_VALUE'" 4