device-devtools-mcp 0.1.0

package/scripts/lib.sh

@@ -0,0 +1,1032 @@
+#!/usr/bin/env bash
+# DeviceTools — shared, platform-neutral helpers.
+#
+# Sourced, never executed. Nothing in this file may know that WebDriverAgent,
+# adb or any other driver exists: that is what makes a second platform a matter
+# of adding a directory rather than editing everything.
+#
+# Exit codes, uniform across every script and every platform:
+#   0  success
+#   1  usage error (bad arguments)
+#   2  environment or configuration problem
+#   3  device or driver connectivity lost — caller must run doctor
+#   4  the request was well-formed but the screen did not satisfy it
+#      (zero matches, several matches, a condition that never held)
+
+set -euo pipefail
+
+# --- where the tool is, and where the work is ---------------------------------
+#
+# These are two different directories and conflating them is what stops this
+# being installable. DT_HOME is the checkout: scripts, adapters, AGENTS.md —
+# read-only, one copy per machine, upgraded by pulling. DT_ROOT is the
+# project: config.json, environments/, .state/, .runs/ — the customer's,
+# versioned in the customer's repository.
+#
+# Every relative path in a config resolves against DT_ROOT. Nothing
+# user-authored ever resolves into DT_HOME.
+DT_HOME="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+export DT_HOME
+
+# The project is found by walking up from the working directory looking for a
+# .devicetools marker — the same rule git uses, for the same reason: you should be
+# able to run this from a subdirectory.
+#
+# The marker is an explicit file, not "the directory containing config.json".
+# config.json is gitignored, so a fresh clone of a test repository has none, and
+# guessing on a filename that common would sooner or later adopt an unrelated
+# directory as the project and read a config that was never meant for us. A
+# wrong project root is the same class of failure as a wrong tap.
+#
+# With no marker anywhere above, the checkout is the project. That is this
+# repository's own layout, and it keeps every existing invocation working.
+dt_find_project() {
+  local d="$PWD"
+  while [ -n "$d" ] && [ "$d" != / ]; do
+    [ -f "$d/.devicetools" ] && { printf '%s' "$d"; return 0; }
+    d="$(dirname "$d")"
+  done
+  [ -f /.devicetools ] && { printf '%s' /; return 0; }
+  printf '%s' "$DT_HOME"
+}
+
+# --project <dir> — SAY WHICH PROJECT, BECAUSE MCP HAS NO WORKING DIRECTORY.
+#
+# dt_find_project walks up from $PWD, which is the rule git uses and the right
+# one for a shell. An MCP server has no such thing: the host sets its working
+# directory when it spawns the process and it never changes, so every walk-up
+# lands in the DeviceTools checkout no matter which repository the person
+# holding the conversation is standing in. Reported after `flow save` wrote into
+# the checkout, told the caller to run `init` in their repository, and then had
+# nothing that could make the result take effect — an agent following its own
+# advice into a dead end.
+#
+# So the project can be named per call, on ANY verb. Stripped out of the
+# argument list here rather than parsed by each verb: sourcing this file happens
+# at the top level of every script, so `set --` below reaches the caller's own
+# positional parameters and nothing downstream has to know the flag exists.
+#
+# The project's config.json wins when it has one, and is exported, so that a
+# child this verb spawns — run.sh calling tap.sh, flow.sh calling run.sh —
+# resolves to the same place rather than half of each.
+#
+# `--` ends option processing, so `type -- --project` types the words.
+_dt_argv=()
+_dt_endopts=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --) _dt_endopts=1; _dt_argv+=("$1"); shift ;;
+    --project)
+      if [ "$_dt_endopts" -eq 1 ] || [ $# -lt 2 ]; then _dt_argv+=("$1"); shift; continue; fi
+      DEVICETOOLS_PROJECT="$2"; export DEVICETOOLS_PROJECT
+      DT_PROJECT_EXPLICIT=1
+      shift 2 ;;
+    *) _dt_argv+=("$1"); shift ;;
+  esac
+done
+set -- ${_dt_argv[@]+"${_dt_argv[@]}"}
+unset _dt_argv _dt_endopts
+
+if [ -n "${DEVICETOOLS_PROJECT:-}" ]; then
+  DT_ROOT="$(cd "$DEVICETOOLS_PROJECT" 2>/dev/null && pwd)" \
+    || { printf 'no such directory: DEVICETOOLS_PROJECT=%s\n' "$DEVICETOOLS_PROJECT" >&2; exit 2; }
+else
+  DT_ROOT="$(dt_find_project)"
+fi
+export DT_ROOT
+
+# Named explicitly, and it has a config: that config is the config, ahead of an
+# inherited DEVICETOOLS_CONFIG. A flag on this call is more specific than an
+# environment variable set when the server started.
+if [ -n "${DT_PROJECT_EXPLICIT:-}" ] && [ -f "$DT_ROOT/config.json" ]; then
+  DEVICETOOLS_CONFIG="$DT_ROOT/config.json"
+  export DEVICETOOLS_CONFIG
+fi
+
+# devicetools_version — the release, and the commit when the checkout is a git one.
+# A report or a bug report that cannot name the build it came from is a bug
+# report about an unknown program.
+devicetools_version() {
+  local v c
+  v="$(cat "$DT_HOME/VERSION" 2>/dev/null || printf 'unknown')"
+  c="$(git -C "$DT_HOME" rev-parse --short HEAD 2>/dev/null || true)"
+  [ -n "$c" ] && printf '%s+%s' "$v" "$c" || printf '%s' "$v"
+}
+
+# die <message> [exit_code]
+# Exactly one line on stderr. Never a stack trace, never a wall of text.
+#
+# WHY THIS IS MORE THAN `exit`
+#
+# A plain `exit` inside $( ) leaves only the subshell. `set -e` does not reliably
+# carry that failure out to the caller — measured, not assumed:
+#
+#   inner() { b="$(false)" || die "failed"; }
+#   outer() { r="$(inner)"; }
+#   x="$(outer)"        # prints "failed", then carries on with x='' and exit 0
+#
+# That turns "the device is unreachable" into "OK, verified", which is the exact
+# class of lie this project exists to prevent. So a die from any depth records
+# its exit code and signals the top-level shell, which then exits with it.
+# The signal is sent unconditionally rather than only from subshells. macOS
+# ships bash 3.2, which has no BASHPID, so a script cannot cheaply tell whether
+# it is currently inside a subshell — and guarding on `$$` is worse than useless
+# there, because `$$` stays the parent's pid inside one. Signalling from the top
+# level too is harmless: the trap exits with the same code the plain exit would.
+DT_TOP=$$
+
+# --- one EXIT trap, and a list -------------------------------------------------
+#
+# A SECOND `trap … EXIT` REPLACES THE FIRST. IT DOES NOT ADD TO IT.
+#
+# This file used to set one here for the return-code file and another, three
+# hundred lines below, for the resolver's state file. Only the second ever ran,
+# so every invocation of every script left a file behind — 401 of them in
+# TMPDIR on this machine when it was noticed, from one day's work. Nothing
+# broke, which is why it lasted: a leak that only fills a directory produces no
+# symptom until something else does.
+#
+# So there is one trap, and things register with it. Anything holding a path
+# that must not outlive the process — a temp file, or an expanded
+# step list, which carries substituted secrets and would otherwise survive a run
+# that died before its own cleanup — calls dt_cleanup_add.
+DT_CLEANUP=""
+dt_cleanup_add() { DT_CLEANUP="$DT_CLEANUP$1"$'\n'; }
+
+# Some things that need releasing are not files. The studio leaves a listener
+# holding a port, and a script that installed its own `trap … EXIT` to take it
+# down would REPLACE the one above rather than run alongside it — which is the
+# bug that leaked a temp file per run until it was found. So hooks register here
+# and the single trap runs them.
+DT_CLEANUP_HOOKS=""
+dt_cleanup_add_hook() { DT_CLEANUP_HOOKS="$DT_CLEANUP_HOOKS$1"$'\n'; }
+
+# EVERY STEP HERE ENDS IN `|| true`, AND `rm` TAKES -r.
+#
+# Both halves of that are load-bearing, and both were found the same way. This
+# file runs under `set -e`, and `[ -n "$p" ] && rm -f "$p"` is an AND-list whose
+# last command `set -e` does not exempt. So a single failing removal aborted the
+# whole function before `return 0` — which meant two things at once, and the
+# quieter one is the worse one:
+#
+#   * the shell exited with the status of the failed rm, so a script that had
+#     succeeded reported failure. A passing self-test exited 1.
+#   * every path registered AFTER the failing one was never removed. That is
+#     precisely the leak this list was introduced to stop.
+#
+# What failed was `rm -f` on a directory, which returns non-zero on macOS. The
+# registered paths are all created by this tool — a temp file, a temp
+# directory — so -r is what "remove it" means here.
+dt_cleanup() {
+  local p h
+  while IFS= read -r h; do
+    [ -z "$h" ] && continue
+    "$h" 2>/dev/null || true
+  done <<< "$DT_CLEANUP_HOOKS"
+  while IFS= read -r p; do
+    [ -z "$p" ] && continue
+    rm -rf "$p" 2>/dev/null || true
+  done <<< "$DT_CLEANUP"
+  return 0
+}
+trap dt_cleanup EXIT
+# Ctrl-C does not run an EXIT trap in every shell that matters here, and the
+# studio's listener must go either way.
+trap 'dt_cleanup; exit 130' INT
+trap 'dt_cleanup; exit 143' TERM
+
+DT_RCFILE="${TMPDIR:-/tmp}/devicetools.rc.$$"
+dt_cleanup_add "$DT_RCFILE"
+trap 'exit "$(cat "$DT_RCFILE" 2>/dev/null || echo 1)"' USR1
+
+die() {
+  local rc="${2:-1}"
+  printf '%s\n' "$1" >&2
+  printf '%s' "$rc" > "$DT_RCFILE" 2>/dev/null || true
+  kill -USR1 "$DT_TOP" 2>/dev/null || true
+  exit "$rc"
+}
+
+need_cmd() {
+  command -v "$1" >/dev/null 2>&1 || die "missing required command: $1 — see README.md setup" 2
+}
+
+# Absolute path with leading ~ expanded. Relative paths resolve against DT_ROOT.
+expand_path() {
+  local p="$1"
+  case "$p" in
+    "~") p="$HOME" ;;
+    "~/"*) p="$HOME/${p#\~/}" ;;
+    /*) ;;
+    *) p="$DT_ROOT/$p" ;;
+  esac
+  printf '%s' "$p"
+}
+
+# --- colour -------------------------------------------------------------------
+#
+# THE TERMINAL'S PALETTE IS THE USER'S, NOT OURS.
+#
+# The HTML report names hex values because it is read off this machine — in a
+# ticket, in a mail, on paper — and has to look the same wherever it lands. A
+# terminal is the opposite: the person reading it already chose a colour scheme,
+# their background may be white or black, and a hex tuned for one is unreadable
+# on the other. So the CLI paints with ANSI's *semantic slots* — red, green,
+# yellow, dim — and lets the terminal decide what those look like. Same design
+# language, opposite mechanism, for the same reason: the reader's context wins.
+#
+# WHAT MUST NOT CHANGE, AND HOW THAT IS GUARANTEED
+#
+# stdout is a contract. It is parsed by CI, by agents, and by this project's own
+# scripts, and a colour code that a parser has to strip is exactly the cost this
+# project refuses everywhere else. So:
+#
+#   - the text never changes; only SGR codes are wrapped around tokens that were
+#     already there. Every status is still a word, which is the rule the visual
+#     language is built on: word first, then glyph, then colour.
+#   - colour is off unless stdout is a terminal. Piped, redirected, or run by
+#     another script, the bytes are identical to what they were before this
+#     existed. That is the pipe-safe proof the design document asked for before
+#     any of this was allowed to be written.
+#   - NO_COLOR is honoured, and DEVICETOOLS_COLOR=never|auto|always overrides.
+#
+# The decision is made HERE, once, while lib.sh is being sourced — which is the
+# only moment file descriptor 1 is still the script's own stdout. Asking `[ -t 1 ]`
+# later from inside a command substitution tests the substitution's pipe and
+# answers "not a terminal" every time, which is how this kind of check silently
+# never fires.
+C_ON=""
+case "${DEVICETOOLS_COLOR:-auto}" in
+  always) C_ON=1 ;;
+  never)  C_ON="" ;;
+  *)
+    if [ -z "${NO_COLOR+x}" ] && [ -t 1 ]; then
+      case "${TERM:-}" in ""|dumb) ;; *) C_ON=1 ;; esac
+    fi ;;
+esac
+
+if [ -n "$C_ON" ]; then
+  C_OFF=$'\033[0m'; C_DIM=$'\033[2m'
+  C_PASS=$'\033[32m'; C_FAIL=$'\033[31m'; C_NOTE=$'\033[33m'; C_SKIP=$'\033[2m'
+else
+  C_OFF=""; C_DIM=""; C_PASS=""; C_FAIL=""; C_NOTE=""; C_SKIP=""
+fi
+
+# paint <line> — the same line, with the record type dimmed and the status word
+# tinted. Returns the input untouched when colour is off.
+#
+# The record type is dimmed rather than coloured because it is scaffolding: RUN,
+# STEP and RESULT are how the stream is parsed, not what it says. Pushing them
+# back is what lets the eye land on the status and the selector, which is what a
+# person is actually scanning for.
+paint() {
+  [ -n "$C_ON" ] || { printf '%s' "$1"; return 0; }
+  local line="$1" tag rest col w
+  case "$line" in
+    [A-Z]*) ;;
+    *) printf '%s' "$line"; return 0 ;;
+  esac
+  tag="${line%%[[:space:]]*}"
+  rest="${line#"$tag"}"
+
+  # ONLY THE FIRST TOKEN AFTER THE RECORD TYPE CAN BE A STATUS.
+  #
+  # Searching the whole line for "OK" paints it inside a test name — `Dialog OK
+  # button works` — and inside a selector, `tap text:OK`. Both are words the
+  # product is quoting, not words it is asserting, and tinting them would make
+  # the line claim something it does not.
+  local lead first
+  lead="${rest%%[! ]*}"
+  first="${rest#"$lead"}"
+  first="${first%%[[:space:]]*}"
+  case "$first" in
+    PASS|OK)    col="$C_PASS" ;;
+    FAIL)       col="$C_FAIL" ;;
+    SKIP)       col="$C_SKIP" ;;
+    RETRY|WARN) col="$C_NOTE" ;;
+    *)          col="" ;;
+  esac
+  [ -n "$col" ] && rest="${lead}${col}${first}${C_OFF}${rest#"$lead$first"}"
+
+  # Drift is the state this product invented, and it is the one word in a green
+  # line that must not read as ordinary. It is marked wherever it appears.
+  case "$rest" in
+    *drifted*) rest="${rest/drifted/${C_NOTE}drifted${C_OFF}}" ;;
+  esac
+
+  printf '%s%s%s%s' "$C_DIM" "$tag" "$C_OFF" "$rest"
+}
+
+# WHERE THE CONFIG IS, AND WHY THERE IS A FOURTH PLACE NOW.
+#
+# Run from a git checkout, the config sits beside it and that is the end of it.
+# Run through `npx`, the package is in a cache directory that npm may delete
+# between invocations — writing a config there means filling in a UDID, a team
+# and a bundle id, and losing them at the next release. So a per-user location
+# is the last resort, and it is the one npx actually uses.
+#
+# In order, most specific first:
+#   1. DEVICETOOLS_CONFIG          named outright
+#   2. $DEVICETOOLS_PROJECT/config.json   the project named for this session
+#   3. $DT_ROOT/config.json        the project found by walking up, or the checkout
+#   4. ~/.config/devicetools/config.json  the per-user one (XDG_CONFIG_HOME wins)
+#
+# 3 is skipped when it does not exist, so that a checkout with no config still
+# reaches 4 rather than reporting the file it happens to be standing next to.
+dt_user_config() { printf '%s/devicetools/config.json' "${XDG_CONFIG_HOME:-$HOME/.config}"; }
+
+if   [ -n "${DEVICETOOLS_CONFIG:-}" ];        then DT_CONFIG="$DEVICETOOLS_CONFIG"
+elif [ -f "$DT_ROOT/config.json" ];           then DT_CONFIG="$DT_ROOT/config.json"
+elif [ -f "$(dt_user_config)" ];              then DT_CONFIG="$(dt_user_config)"
+else                                               DT_CONFIG="$DT_ROOT/config.json"
+fi
+
+load_config() {
+  need_cmd jq
+  [ -f "$DT_CONFIG" ] || die "no config — looked in $DT_ROOT/config.json and $(dt_user_config). Make one with $(as_cmd init '<your app repository>'), or copy $DT_HOME/config.example.json to $(dt_user_config) and fill it in" 2
+  jq -e . "$DT_CONFIG" >/dev/null 2>&1 || die "config is not valid JSON: $DT_CONFIG" 2
+}
+
+# cfg <jq-path> [default]
+# Prints the value, or the default when absent/null/empty. Fails when a value is
+# required and missing, rather than silently substituting an empty string.
+cfg() {
+  local path="$1" default="${2-}" v
+  v="$(jq -r "$path // empty" "$DT_CONFIG" 2>/dev/null || true)"
+  if [ -z "$v" ]; then
+    if [ $# -ge 2 ]; then
+      printf '%s' "$default"
+      return 0
+    fi
+    die "config key missing: $path (in $DT_CONFIG)" 2
+  fi
+  printf '%s' "$v"
+}
+
+# as_cmd <verb> [args] — how to spell a verb back to whoever is reading.
+#
+# bin/devicetools exports DT_CLI before exec'ing a verb and the MCP server
+# exports DT_MCP, so the same remedy reads `devicetools doctor --recover` on the
+# CLI, `doctor --recover` to a model that only knows tool names, and
+# `scripts/doctor.sh --recover` to whoever ran the script. A model told to run
+# `scripts/snapshot.sh` has been handed a path it cannot call.
+as_cmd() {
+  local verb="$1"; shift
+  if   [ -n "${DT_MCP:-}" ]; then printf '%s' "$verb"
+  elif [ -n "${DT_CLI:-}" ]; then printf 'devicetools %s' "$verb"
+  else printf 'scripts/%s.sh' "$verb"; fi
+  [ $# -gt 0 ] && printf ' %s' "$*"
+  return 0
+}
+
+# as_flag <name> <value> — how to spell a flag back to whoever is reading.
+#
+# The sibling of as_cmd, and needed for the same reason: `--project /x` is not
+# something a model can send. Over MCP a flag is a key in the arguments object.
+as_flag() {
+  if [ -n "${DT_MCP:-}" ]; then printf '%s=%s' "$1" "${2-}"
+  else printf -- '--%s %s' "$1" "${2-}"; fi
+}
+
+platform() { cfg '.platform' 'ios'; }
+
+# target_kind — "auto", "device" or "simulator", as configured.
+#
+# The split is not iOS-specific: Android has real devices and emulators too, and
+# an adapter that resolves "auto" for its own platform keeps the distinction in
+# one vocabulary instead of two.
+target_kind() { cfg '.device.kind' 'auto'; }
+
+adapter_dir() {
+  local p d
+  p="$(platform)"
+  d="$DT_HOME/scripts/$p"
+  [ -d "$d" ] || die "no adapter for platform '$p' — expected $d" 2
+  printf '%s' "$d"
+}
+
+# flows_dir — where saved flows live.
+#
+# IN THE PROJECT, NOT IN THE TOOL'S CONFIG. A flow is knowledge about an
+# application — that logging in means these six steps, on these screens — so it
+# belongs beside the application, in its repository, reviewed like the code it
+# describes. Putting it in config.json would make it per-machine and invisible
+# to everyone else on the team, which is the opposite of the point.
+#
+# Not created here: reading a directory that does not exist is a fine answer,
+# and only `flow save` has any business making one.
+flows_dir() { expand_path "$(cfg '.paths.flows_dir' 'flows')"; }
+
+state_dir() {
+  local d
+  d="$(expand_path "$(cfg '.paths.state_dir' '.state')")"
+  mkdir -p "$d"
+  printf '%s' "$d"
+}
+
+# --- uids ----------------------------------------------------------------------
+#
+# `snapshot` numbers what it shows and writes the numbering here; `tap 7` reads
+# it back. The store is on disk rather than in the environment because every
+# verb is a separate process started by whoever is driving — an exported
+# variable would have to be threaded through every call site.
+#
+# There is exactly one store. A uid means "the seventh thing on the screen I was
+# last shown", and keeping two of those around is how a tap lands on the wrong
+# button.
+uid_store() { printf '%s' "${DEVICETOOLS_UID_STORE:-$(state_dir)/uids.tsv}"; }
+
+# --- the session journal -------------------------------------------------------
+#
+# Every action that lands is appended here. NOT a test case: there are no
+# assertions in it, nothing runs it in CI, and nothing scores anything. It is
+# the path back to where you were, which is what installing a new build takes
+# away — the app returns to its first screen and a long flow is four screens
+# deep.
+#
+# Failing to write it must never fail an action. The tap already happened on the
+# phone; reporting failure afterwards would be a lie with a consequence, because
+# the agent would do it again.
+journal_path() { printf '%s' "${DEVICETOOLS_JOURNAL:-$(state_dir)/session.jsonl}"; }
+
+# journal_append <verb> <args> <type> <id> <label> <value> <x> <y> <w> <h> <screen>
+journal_append() {
+  local f
+  f="$(journal_path)"
+  mkdir -p "$(dirname "$f")" 2>/dev/null || return 0
+  jq -nc --arg verb "${1-}" --arg args "${2-}" --arg type "${3-}" --arg id "${4-}" \
+         --arg label "${5-}" --arg value "${6-}" \
+         --arg x "${7:-0}" --arg y "${8:-0}" --arg w "${9:-0}" --arg h "${10:-0}" \
+         --arg screen "${11-}" \
+    '{verb:$verb, args:$args, type:$type, id:$id, label:$label, value:$value,
+      x:($x|tonumber? // 0), y:($y|tonumber? // 0),
+      w:($w|tonumber? // 0), h:($h|tonumber? // 0), screen:$screen}' \
+    >> "$f" 2>/dev/null || true
+  return 0
+}
+
+# --- what happened -------------------------------------------------------------
+#
+# A person who taps a button sees the screen move, sees the app stall, sees the
+# dialog appear. An agent that only gets "OK tapped" has to spend another call
+# to learn any of it, and between the two calls it knows nothing.
+#
+# So an action reports three things: what it did, whether the screen moved, and
+# what the app said while it was moving. NOT the new tree — attaching a snapshot
+# to every action would triple the cost of the loop to answer a question that
+# "changed" or "unchanged" already answers, and the agent calls snapshot when it
+# wants the detail.
+
+# screen_state — "<hash>\t<name>" for whatever is on screen now, or empty.
+#
+# One fetch for both, because two would be two chances for the screen to move
+# between them and a report that mixed one screen's hash with another's name.
+# TWO DIGESTS, BECAUSE "THE SAME SCREEN" AND "NOTHING HAPPENED" ARE NOT THE
+# SAME CLAIM.
+#
+# The screen hash is over the type and label of every shown element: it answers
+# "am I still on the same screen", and a field filling up is the same screen.
+# The content digest also covers values, so it moves when the screen's contents
+# do.
+#
+# Without the second one, tapping a keypad key on an OTP sheet reported SCREEN
+# unchanged while the field went from "8 8" to "8 8 8" — and the agent that read
+# it went and spent a snapshot proving the tap had in fact landed, which is the
+# round trip this line exists to save. A false "nothing happened" is worse than
+# no line at all.
+#
+# One read, both digests: the rows are fetched once and measured twice.
+screen_state() { state_from_rows "$(snapshot_rows 2>/dev/null || true)"; }
+
+# state_from_rows <rows> — the same answer, from rows already in hand.
+#
+# Split out so that an action asked for a snapshot pays for ONE fetch and gets
+# both answers from it. Fetching twice would also be two chances for the screen
+# to move in between, and a report that paired one screen's digest with another
+# screen's tree would be worse than no report.
+state_from_rows() {
+  local rows="$1" head content
+  [ -n "$rows" ] || return 0
+
+  head="$(printf '%s\n' "$rows" \
+    | awk -v ALL=0 -v GREP="" -v MINHIT=44 -f "$DT_HOME/scripts/snapshot.awk" 2>/dev/null \
+    | awk -F'"' '
+        NR == 1 {
+          name = (NF >= 2 ? $2 : "")
+          hash = ""
+          n = split($0, w, " ")
+          for (i = 1; i <= n; i++) if (w[i] ~ /^#/) hash = substr(w[i], 2)
+          printf "%s\t%s", hash, name
+          exit
+        }')"
+  [ -n "$head" ] || return 0
+
+  # n|depth|parent|type|id|label|value|x|y|w|h|flags
+  content="$(printf '%s\n' "$rows" \
+    | awk -F'|' '$1 != "WINDOW" && $1 != "" { print $4 "\037" $6 "\037" $7 }' \
+    | cksum | awk '{ print $1 }')"
+
+  printf '%s\t%s' "$head" "$content"
+}
+
+# --- rendering a screen, from rows -------------------------------------------
+#
+# snapshot.sh used to own all of this. It now shares it with act_report, because
+# an action that can hand back the new screen is the difference between two
+# calls and one, and the read–act–read cycle was half the round trips in a
+# measured session: twelve calls to log in and open Settings, six of them
+# snapshots taken only to find out what the last action produced.
+
+# min_hit — the minimum comfortable hit area, in points, for this platform.
+# Apple says 44, Google says 48, and reporting one platform's number on the
+# other is a warning nobody should act on.
+min_hit() {
+  case "$(platform)" in
+    android) printf '48' ;;
+    *)       printf '44' ;;
+  esac
+}
+
+# render_rows <rows> [all] [grep] — the screen as an agent reads it.
+render_rows() {
+  printf '%s\n' "$1" \
+    | awk -v ALL="${2:-0}" -v GREP="${3-}" -v MINHIT="$(min_hit)" \
+          -f "$DT_HOME/scripts/snapshot.awk"
+}
+
+# write_uid_store <rows> [all] [grep] — renumber, so the uids just printed work.
+#
+# Written to a temporary file and moved into place. A half-written store read by
+# the next verb would resolve a uid to whatever happened to be on that line,
+# which is the one failure this whole mechanism exists to prevent.
+write_uid_store() {
+  local store tmp
+  store="$(uid_store)"
+  tmp="$store.new"
+  mkdir -p "$(dirname "$store")" 2>/dev/null || true
+  printf '%s\n' "$1" \
+    | awk -v ALL="${2:-0}" -v GREP="${3-}" -v MINHIT="$(min_hit)" -v MODE=store \
+          -f "$DT_HOME/scripts/snapshot.awk" > "$tmp" \
+    || { rm -f "$tmp"; return 1; }
+  mv "$tmp" "$store" || { rm -f "$tmp"; return 1; }
+  return 0
+}
+
+DT_ACT_HASH=""
+DT_ACT_NAME=""
+DT_ACT_CONTENT=""
+DT_ACT_AT=""
+
+# Whether an action hands back the screen it produced. Off by default: attaching
+# a tree to every action would triple the cost of a loop that mostly does not
+# need it, and "changed" or "unchanged" already answers the common question.
+# The caller asks with --snapshot, and asks when it is about to look anyway.
+DT_ACT_SNAPSHOT=0
+act_snapshot_on() { DT_ACT_SNAPSHOT=1; }
+
+# act_before — remember the screen, and the moment, before acting.
+# split_state <state> — sets ST_HASH, ST_NAME, ST_CONTENT from one screen_state
+# line. One splitter, because two copies of "the second tab is the name" is how
+# a third field silently ends up inside the second.
+split_state() {
+  local s="$1" rest
+  ST_HASH="${s%%	*}"
+  rest="${s#*	}"
+  if [ "$rest" = "$s" ]; then ST_NAME=""; ST_CONTENT=""; return 0; fi
+  ST_NAME="${rest%%	*}"
+  ST_CONTENT="${rest#*	}"
+  [ "$ST_CONTENT" = "$rest" ] && ST_CONTENT=""
+  return 0
+}
+
+act_before() {
+  local s
+  s="$(screen_state || true)"
+  split_state "$s"
+  DT_ACT_HASH="$ST_HASH"
+  DT_ACT_NAME="$ST_NAME"
+  DT_ACT_CONTENT="$ST_CONTENT"
+  DT_ACT_AT="$(date +%s)"
+  return 0
+}
+
+# act_report <VERB> <what> — the three lines.
+act_report() {
+  local verb="$1" what="$2" rows s hash2 name2 content2 lines n tree
+  printf '%-6s %s\n' "$verb" "$what"
+
+  # ONE FETCH. The digests below and the tree at the bottom are two readings of
+  # the same rows, not two reads of the same phone.
+  rows="$(snapshot_rows 2>/dev/null || true)"
+  s="$(state_from_rows "$rows" || true)"
+  split_state "$s"
+  hash2="$ST_HASH"; name2="$ST_NAME"; content2="$ST_CONTENT"
+
+  if [ -z "$DT_ACT_HASH" ] || [ -z "$hash2" ]; then
+    printf 'SCREEN unknown — the tree could not be read on both sides of this\n'
+  elif [ "$hash2" != "$DT_ACT_HASH" ]; then
+    printf 'SCREEN changed — %s#%s → %s#%s\n' \
+      "${DT_ACT_NAME:+\"$DT_ACT_NAME\" }" "$DT_ACT_HASH" "${name2:+\"$name2\" }" "$hash2"
+  elif [ -n "$DT_ACT_CONTENT" ] && [ -n "$content2" ] && [ "$content2" != "$DT_ACT_CONTENT" ]; then
+    # Same controls, different contents: a field filling up, a counter moving, a
+    # code being entered. Not a new screen, and emphatically not "nothing
+    # happened".
+    printf 'SCREEN same — %s#%s, contents changed\n' "${name2:+\"$name2\" }" "$hash2"
+  else
+    printf 'SCREEN unchanged — %s#%s\n' "${name2:+\"$name2\" }" "$hash2"
+  fi
+
+  # No collector, no LOG section. See logs_since in each adapter: an action must
+  # not start a background process, and `logs start` is how an agent asks for
+  # this.
+  lines="$(logs_since "${DT_ACT_AT:-0}" 2>/dev/null || true)"
+  if [ -n "$lines" ]; then
+    n="$(printf '%s\n' "$lines" | wc -l | tr -d ' ')"
+    printf 'LOG    %s line%s\n' "$n" "$( [ "$n" = 1 ] || printf s )"
+    printf '%s\n' "$lines" | sed 's/^/       /'
+  fi
+
+  # THE NEW SCREEN, WHEN IT WAS ASKED FOR — AND THE UIDS RENUMBERED TO MATCH.
+  #
+  # Printing the tree without rewriting the store would be worse than not
+  # printing it: the numbers would be the previous screen's, and every one of
+  # them would resolve to something that is no longer there. So the store is
+  # rewritten from these rows, and `tap 7` means the seventh line below.
+  #
+  # Neither failure here may fail the action. The tap already happened on the
+  # phone; reporting failure afterwards is a lie the agent would act on by
+  # doing it again.
+  if [ "$DT_ACT_SNAPSHOT" -eq 1 ]; then emit_tree "$rows"; fi
+  return 0
+}
+
+# emit_tree <rows> — print the screen and renumber the store, or say why not.
+emit_tree() {
+  local rows="${1-}" tree
+  if [ -z "$rows" ]; then
+    printf 'TREE   unavailable — the screen could not be read after the action\n'
+    return 0
+  fi
+  if ! tree="$(render_rows "$rows" 2>/dev/null)" || [ -z "$tree" ]; then
+    printf 'TREE   unavailable — nothing on the screen survived the filter\n'
+    return 0
+  fi
+  write_uid_store "$rows" \
+    || printf 'TREE   the uid store could not be written — run %s before acting on these numbers\n' "$(as_cmd snapshot)"
+  printf '\n%s\n' "$tree"
+  return 0
+}
+
+# act_snapshot_now — the same, for a verb that does not report through
+# act_report: app launch, key hide, open. Costs one fetch and only when asked.
+act_snapshot_now() {
+  [ "$DT_ACT_SNAPSHOT" -eq 1 ] || return 0
+  emit_tree "$(snapshot_rows 2>/dev/null || true)"
+  return 0
+}
+
+# run_dir — where screenshots and trees for the current run are written.
+# A caller may export DEVICETOOLS_RUN_ID; without it everything lands in one "adhoc"
+# directory so a single script still works on its own.
+run_dir() {
+  local base d
+  base="$(expand_path "$(cfg '.paths.runs_dir' '.runs')")"
+  d="$base/${DEVICETOOLS_RUN_ID:-adhoc}"
+  mkdir -p "$d"
+  printf '%s' "$d"
+}
+
+# port_open <port> — true when something is listening on 127.0.0.1:<port>
+port_open() {
+  nc -z 127.0.0.1 "$1" >/dev/null 2>&1
+}
+
+# take_lines <n> — the first n lines of stdin, WITHOUT LEAVING EARLY.
+#
+# `head` closes the pipe the moment it has enough, and whatever is upstream —
+# usually this shell's own printf — is still writing. Bash reports that as
+# `printf: write error: Broken pipe` on stderr, which looks like a fault and is
+# not one. It only shows when the input is bigger than the pipe buffer, so it
+# hides in every test with a small fixture and appears the first time somebody
+# points this at a real screen.
+#
+# Reading to the end costs nothing here: the inputs are trees and match lists
+# already sitting in memory.
+take_lines() { awk -v n="$1" 'NR <= n'; }
+
+# first_line <string> — no pipe at all, which is the cheapest way to be sure.
+first_line() { printf '%s' "${1%%$'\n'*}"; }
+
+# strip_log_block — drop `LOG    n lines` and the lines it introduces.
+#
+# act_report writes the log block as a LOG header followed by lines indented by
+# seven spaces, so both halves are recognisable without knowing what is in them.
+# Everything else — the action's own line, SCREEN, and a --snapshot tree, which
+# is separated by a blank line and not indented — passes through untouched.
+strip_log_block() {
+  awk '
+    /^LOG +[0-9]/       { inlog = 1; next }
+    inlog && /^       / { next }
+    { inlog = 0; print }'
+}
+
+# join_lines <separator> — collapse stdin to one line. Error messages are a
+# single line by contract, and `paste -sd` only honours one delimiter character.
+join_lines() {
+  awk -v sep="$1" 'NR > 1 { printf "%s", sep } { printf "%s", $0 } END { print "" }'
+}
+
+# --- selectors ---------------------------------------------------------------
+#
+# The selector grammar is platform-neutral. Each adapter maps it onto whatever
+# its driver actually calls these things:
+#
+#   id:<s>       iOS accessibilityIdentifier   Android resource-id
+#   label:<s>    iOS accessibility label       Android content-desc
+#   text:<s>     iOS value                     Android text
+#   kind:<s>     iOS XCUIElement type          Android class name — the word
+#                snapshot prints first on the line, for a control that carries
+#                no identifier and no label at all
+#   xy:<x>,<y>   raw point, in the coordinate space tree.sh prints
+#
+# Android genuinely distinguishes content-desc from text, so the grammar has to
+# carry both; mapping iOS `value` onto text: follows from that, and is what
+# makes fields with neither an identifier nor a label addressable at all.
+#
+# And two spellings that name no attribute at all:
+#
+#   <n>          a uid — the nth thing the last snapshot showed
+#   <anything>   a plain string, matched against id, label and value in turn
+#
+# uid_resolve <n> — the point to act on, or a refusal.
+#
+# A uid is a promise about a specific element on a specific screen. Honouring it
+# means proving the element is still there: same type, same identifier, same
+# label, same value, same rectangle. Anything less is a guess, and a guess that
+# lands a tap in somebody's live session is the failure this whole tool is
+# arranged to avoid.
+#
+# Note what is NOT here: no scoring, no runner-up, no threshold. When the screen
+# has moved on, the answer is "read it again", which costs one cheap call.
+uid_resolve() {
+  local want="$1" store row rtype rid rlabel rvalue rx ry rw rh now hit
+  store="$(uid_store)"
+  [ -f "$store" ] \
+    || die "no uid is in play — run $(as_cmd snapshot) first, then use the numbers it prints" 4
+
+  row="$(awk -F'|' -v u="$want" '$1 + 0 == u + 0 { print; exit }' "$store")"
+  [ -n "$row" ] \
+    || die "uid $want was never assigned — the last snapshot printed $(wc -l < "$store" | tr -d ' ') element(s)" 4
+
+  # '|' and not a tab: see the note in snapshot.awk's store mode. An empty
+  # identifier next to an empty value would collapse under a whitespace IFS and
+  # every field after them would shift left.
+  IFS='|' read -r _ _ rtype rid rlabel rvalue rx ry rw rh <<< "$row"
+
+  # Re-read the screen and require the same element to still be on it. Matched
+  # on the attributes, not on the serial: a serial is a position in a tree that
+  # the driver rebuilds on every fetch.
+  #
+  # THE STRINGS MUST BE EXACT; THE RECTANGLE GETS TWO POINTS. Both drivers
+  # report rectangles as floats and this pipeline floors them, so an element
+  # that has not moved can still be reported one point away on a later fetch.
+  # Demanding an exact rectangle would make every uid stale at random, and the
+  # agent would learn to re-snapshot before every action — which is the cost
+  # this mechanism exists to avoid. Two points is the arithmetic; a control that
+  # has actually moved has moved by more than that. The same number, for the
+  # same reason, as the tolerance in snapshot.awk.
+  now="$(snapshot_rows)" || die "could not re-read the screen — run $(as_cmd doctor)" 3
+  hit="$(printf '%s\n' "$now" | awk -F'|' \
+    -v t="$rtype" -v i="$rid" -v l="$rlabel" -v v="$rvalue" \
+    -v x="$rx" -v y="$ry" -v w="$rw" -v h="$rh" '
+      function near(a, b) { d = a - b; return (d < 0 ? -d : d) <= 2 }
+      $1 == "WINDOW" { next }
+      $4 == t && $5 == i && $6 == l && $7 == v &&
+      near($8 + 0, x + 0) && near($9 + 0, y + 0) &&
+      near($10 + 0, w + 0) && near($11 + 0, h + 0) { c++ }
+      END { print c + 0 }')"
+
+  if [ "$hit" -eq 0 ]; then
+    die "uid $want is stale — '$rlabel' is no longer a $rtype at ${rx},${ry} ${rw}x${rh}. Run $(as_cmd snapshot) again" 4
+  fi
+  if [ "$hit" -gt 1 ]; then
+    die "uid $want now matches $hit identical elements — the screen changed under it. Run $(as_cmd snapshot) again" 4
+  fi
+
+  printf '%s,%s' "$(( rx + rw / 2 ))" "$(( ry + rh / 2 ))"
+}
+
+# parse_selector <selector> — sets SEL_KIND, SEL_VALUE and SEL_DESC.
+parse_selector() {
+  [ -n "$1" ] || die "empty selector" 1
+  case "$1" in
+    id:*)    SEL_KIND=id;    SEL_VALUE="${1#id:}" ;;
+    label:*) SEL_KIND=label; SEL_VALUE="${1#label:}" ;;
+    text:*)  SEL_KIND=text;  SEL_VALUE="${1#text:}" ;;
+    # kind:<Type> — THE ELEMENT'S CLASS, WHEN IT HAS NOTHING ELSE.
+    #
+    # Added because snapshot was warning "no identifier" about a
+    # SecureTextField with no label either, and then leaving nothing but a raw
+    # coordinate to reach it with — the one spelling this tool tells people to
+    # avoid, and rightly: after the keyboard went down, the sheet holding that
+    # field moved from y=507 to y=774 and the recorded tap missed entirely.
+    #
+    # A type is not unique on a screen, so this is usually written with --index,
+    # and it refuses exactly as every other selector does when it is not.
+    kind:*)  SEL_KIND=kind;  SEL_VALUE="${1#kind:}" ;;
+    xy:*)    SEL_KIND=xy;    SEL_VALUE="${1#xy:}" ;;
+    any:*)   SEL_KIND=any;   SEL_VALUE="${1#any:}" ;;
+    uid:*)
+      SEL_KIND=xy; SEL_VALUE="$(uid_resolve "${1#uid:}")"
+      SEL_DESC="uid ${1#uid:}"
+      return 0 ;;
+    # Anything with a non-digit in it is a plain string. This arm exists only to
+    # stop such a string reaching the uid arm below it; `case` takes the first
+    # match, so order is the whole mechanism here.
+    *[!0-9]*) SEL_KIND=any; SEL_VALUE="$1" ;;
+    # All digits: a uid. Nothing else in the grammar is a bare number, and
+    # `tap 7` is what anybody reaches for after reading a numbered screen.
+    *)
+      SEL_KIND=xy; SEL_VALUE="$(uid_resolve "$1")"
+      SEL_DESC="uid $1"
+      return 0 ;;
+  esac
+  [ -n "$SEL_VALUE" ] || die "empty selector value in '$1'" 1
+  # How the selector is named in a message. Somebody who wrote `tap Đóng` never
+  # chose an attribute, so telling them "no element with any exactly 'Đóng'" is
+  # answering a question they did not ask in a vocabulary they did not use.
+  if [ "$SEL_KIND" = any ]; then SEL_DESC="'$SEL_VALUE'"
+  else SEL_DESC="$SEL_KIND '$SEL_VALUE'"; fi
+}
+
+DT_RESOLVE_STATE="${TMPDIR:-/tmp}/devicetools.resolve.$$"
+dt_cleanup_add "$DT_RESOLVE_STATE"
+
+# resolve_state — load RESOLVE_HOW and RESOLVE_NOTE from the last call.
+resolve_state() {
+  RESOLVE_HOW=""; RESOLVE_NOTE=""
+  [ -f "$DT_RESOLVE_STATE" ] || return 0
+  IFS=$'\t' read -r RESOLVE_HOW RESOLVE_NOTE < "$DT_RESOLVE_STATE" || true
+  return 0
+}
+
+resolve_note_out() {
+  printf '%s\t%s' "$1" "${2-}" > "$DT_RESOLVE_STATE" 2>/dev/null || true
+}
+
+# match_or_holding <source> <kind> <value> — what the screen says right now.
+#
+# THE CAPTION IS NOT ALWAYS INSIDE THE CONTROL, AND NOBODY SHOULD HAVE TO CARE.
+#
+# Applications put a caption beside the control it names as often as within it,
+# and XCUITest then reports the caption as invisible because the control takes
+# its hit test. A person writing the test sees words on a card and writes the
+# words; whether this app nests them one way and that app another is not their
+# subject, and making it their subject was the mistake here — this began as its
+# own `holding:` selector, which is an implementation detail promoted to grammar.
+#
+# So when the written text matches nothing directly, the smallest control whose
+# bounds contain that text is used. One rule, reported on the line, and still
+# refused when two controls hold the same words: this widens what resolves,
+# never what is guessed at.
+#
+# This is the whole resolver. There was once a second layer above it that
+# scored a recorded fingerprint against the screen when the written selector
+# stopped matching; it was deleted along with the test runner it existed for.
+# An agent re-reads the screen before every action, so it never holds a selector
+# old enough to need rescuing.
+# collapse_nested — a control and its own caption are one thing, not two.
+#
+# Nearly every real screen carries the same words twice: on the Button, and on
+# the StaticText the Button draws inside itself. Reported as two matches, that
+# forced an --index onto the commonest selector anyone writes, and an index is a
+# position in a list nobody can see. There is no ambiguity to protect here — the
+# outer element occupies the inner one's whole area, so both taps land on the
+# same control.
+#
+# Only a strictly larger container absorbs a match. Two elements that merely
+# overlap, or sit side by side, stay two matches and the caller still refuses.
+collapse_nested() {
+  awk -F'|' '
+    { X[NR] = $1; Y[NR] = $2; W[NR] = $3; H[NR] = $4; L[NR] = $0 }
+    END {
+      for (i = 1; i <= NR; i++) {
+        drop = 0
+        for (j = 1; j <= NR && !drop; j++) {
+          if (i == j) continue
+          if (X[j] <= X[i] && Y[j] <= Y[i] \
+              && X[j] + W[j] >= X[i] + W[i] && Y[j] + H[j] >= Y[i] + H[i] \
+              && W[j] * H[j] > W[i] * H[i]) drop = 1
+          # Identical bounds: keep the one that came first in the tree, which is
+          # the container, since a child is always emitted after its parent.
+          else if (X[j] == X[i] && Y[j] == Y[i] && W[j] == W[i] && H[j] == H[i] \
+                   && j < i) drop = 1
+        }
+        if (!drop) print L[i]
+      }
+    }'
+}
+
+match_or_holding() {
+  local m k
+  rm -f "$DT_RESOLVE_STATE" 2>/dev/null || true
+
+  # A PLAIN STRING IS THE DEFAULT WAY TO NAME A CONTROL.
+  #
+  # `tap: Đóng` is what somebody testing the app writes, because it is what they
+  # can see. `tap: { label: Đóng, index: 0 }` is a data structure, and requiring
+  # it makes the person who knows the product least able to describe it.
+  #
+  # THE FIRST KIND THAT MATCHES WINS — not the union of all three. An id that
+  # matches exactly is a better answer than two labels that also do, and merging
+  # them would manufacture an ambiguity the screen does not have and then refuse
+  # over it. Ambiguity WITHIN one kind is still real and is still refused.
+  if [ "$2" = any ]; then
+    for k in id label text; do
+      m="$(match_or_holding "$1" "$k" "$3" || true)"
+      [ -n "$m" ] || continue
+      printf '%s\n' "$m"
+      return 0
+    done
+    return 1
+  fi
+  m="$(match_elements "$1" "$2" "$3" | collapse_nested || true)"
+  if [ -n "$m" ]; then
+    resolve_note_out exact
+    printf '%s\n' "$m"
+    return 0
+  fi
+  [ "$2" = text ] || return 1
+  command -v holding_elements >/dev/null 2>&1 || return 1
+  m="$(holding_elements "$1" "$3" || true)"
+  [ -n "$m" ] || return 1
+  resolve_note_out holding "the text is inside the control rather than on it"
+  printf '%s\n' "$m"
+}
+# parse_xy <value> — sets XY_X and XY_Y from an "x,y" string.
+parse_xy() {
+  case "$1" in
+    *,*) ;;
+    *) die "xy selector needs two numbers: xy:<x>,<y> — got 'xy:$1'" 1 ;;
+  esac
+  XY_X="${1%%,*}"
+  XY_Y="${1##*,}"
+  case "$XY_X$XY_Y" in
+    (*[!0-9]*|"") die "xy coordinates must be non-negative integers — got 'xy:$1'" 1 ;;
+  esac
+}
+
+# holding_absence <source> <text> — the sentence explaining why a holding:
+# selector matched nothing, or nothing at all if the text is simply not there.
+#
+# Two failures wear the same face otherwise: a screen that has not arrived, and
+# a screen that has arrived where the caption sits outside the control's bounds.
+# The first is fixed by waiting, the second by writing a different selector, and
+# sending someone to the wrong one costs a whole debugging session.
+holding_absence() {
+  local rows
+  command -v text_anywhere >/dev/null 2>&1 || return 0
+  rows="$(text_anywhere "$1" "$2" 2>/dev/null || true)"
+  [ -n "$rows" ] || return 0
+  # `| head -1 |` in the middle of this closed the pipe under the shell's own
+  # printf and put `printf: write error: Broken pipe` on stderr. awk takes the
+  # first record itself, so there is no early-exiting reader to write into.
+  printf 'the text is on screen at %s, but no control a user can act on contains it — the caption may sit outside the control bounds, so name the control another way' \
+    "$(printf '%s\n' "$rows" | awk -F'|' 'NR == 1 { printf "%s,%s,%s,%s", $1, $2, $3, $4; exit }')"
+}
+
+# invisible_note <source> <kind> <value> — the sentence for a selector that names
+# something really in the tree, which the driver reports as not visible.
+#
+# THE MESSAGE THIS REPLACES WAS FALSE, AND FALSE IN THE DIRECTION THAT COSTS
+# MOST. `tap label:Cài đặt` answered "nothing on screen contains it" while
+# `snapshot --grep Cài đặt` was listing it two lines above — so the caller is
+# told the screen is wrong when the screen is right and the control is merely
+# underneath something. Reported from a Control Wheel whose four buttons share
+# one rectangle exactly: three of the four are covered, and the driver marks
+# them invisible, which is true and is not "not there".
+#
+# The count of elements sharing that exact rectangle is the evidence for the
+# diagnosis, so it is printed rather than asserted.
+invisible_note() {
+  local row why x y w h type same vis
+  command -v named_anywhere >/dev/null 2>&1 || return 0
+  row="$(named_anywhere "$1" "$2" "$3" 2>/dev/null | awk 'NR == 1 { print; exit }')"
+  [ -n "$row" ] || return 0
+  IFS='|' read -r x y w h type same vis <<< "$row"
+
+  # Two different faults wear the same absence, and the remedy for one is not
+  # the remedy for the other.
+  if [ "${w:-0}" -le 0 ] || [ "${h:-0}" -le 0 ]; then
+    why="it measures ${w}x${h}, so there is no point to tap"
+  elif [ "${same:-1}" -gt 1 ]; then
+    why="the driver reports it as not visible, and $same elements share that rectangle exactly — it is underneath one of them, so clear what covers it or scroll it into view"
+  elif [ "${vis:-0}" = 0 ]; then
+    why="the driver reports it as not visible — clear whatever covers it, or scroll it into view"
+  else
+    return 0
+  fi
+  printf 'it is in the tree as a %s at %s,%s %sx%s, but %s. Reading finds it and acting does not, on purpose: a tap only lands on what a user could have touched' \
+    "$type" "$x" "$y" "$w" "$h" "$why"
+}
+