zig-mobile-runner 0.1.0

package/scripts/run-ios-pilot.sh

@@ -0,0 +1,509 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+CALLER_CWD="$(pwd -P)"
+cd "$ROOT"
+
+# Some sandboxed environments do not allow writing to the default temp directory
+# (/var/folders, /tmp). Use a repo-local TMPDIR so xcrun/mktemp/heredocs work.
+if [[ -z "${TMPDIR:-}" || ! -w "${TMPDIR:-/nonexistent}" ]]; then
+  TMPDIR="$ROOT/traces/tmp"
+  mkdir -p "$TMPDIR"
+  export TMPDIR
+fi
+
+APP_ROOT="${APP_ROOT:-}"
+APP_PATH="${APP_PATH:-}"
+DEVICE="${DEVICE:-booted}"
+IOS_DEVICE_TYPE="${IOS_DEVICE_TYPE:-simulator}"
+TRACE_ROOT="${TRACE_ROOT:-$CALLER_CWD/traces/ios-app-pilot-$(date +%Y%m%d-%H%M%S)}"
+ZMR_BIN="${ZMR_BIN:-$(command -v zmr 2>/dev/null || printf '%s' "$ROOT/zig-out/bin/zmr")}"
+XCRUN="${XCRUN:-xcrun}"
+APP_ID="${APP_ID:-com.example.mobiletest}"
+IOS_SHIM="${IOS_SHIM:-}"
+PREWARM_IOS_SHIM="${PREWARM_IOS_SHIM:-1}"
+RUNS="${RUNS:-1}"
+MIN_PASS_RATE="${MIN_PASS_RATE:-100}"
+MAX_FAILURES="${MAX_FAILURES:-0}"
+MAX_MEAN_MS="${MAX_MEAN_MS:-}"
+MAX_P95_MS="${MAX_P95_MS:-}"
+DRY_RUN=0
+
+usage() {
+  cat <<'USAGE'
+Usage:
+  scripts/run-ios-pilot.sh --app-path <Sample.app|Sample.ipa> [options]
+
+Runs a configurable iOS smoke pilot:
+  1. build/validate zmr
+  2. install a simulator .app or signed physical-device .app/.ipa
+  3. launch/open a deep link through examples/ios-smoke.json
+  4. capture screenshot/log snapshot artifacts
+  5. generate report and normal/redacted .zmrtrace bundles
+
+Options:
+  --app-root <dir>     Optional app repo root, used only for output context.
+  --app-path <path>    Built simulator .app, or signed physical-device .app/.ipa. Required.
+  --device <id>        Simulator UDID/booted or physical device identifier. Default: booted.
+  --ios-device-type <simulator|physical>
+                       Target type. Default: simulator.
+  --app-id <bundle>    Bundle id. Default: com.example.mobiletest.
+  --trace-root <dir>   Output directory. Default: traces/ios-app-pilot-<timestamp>.
+  --zmr-bin <path>     zmr binary. Default: ZMR_BIN, PATH zmr, then zig-out/bin/zmr.
+  --xcrun <path>       xcrun path. Default: xcrun.
+  --ios-shim <path>    Optional XCTest shim command for selector hierarchy/actions.
+  --skip-shim-prewarm  Do not prewarm the XCTest shim before scenario timing.
+  --runs <n>           Run each flow n times. n=1 writes trace bundles; n>1 writes benchmark reports.
+  --min-pass-rate <pct>
+                       Repeated-run gate minimum. Default: 100.
+  --max-failures <n>   Repeated-run gate maximum. Default: 0.
+  --max-mean-ms <ms>   Optional repeated-run mean duration maximum.
+  --max-p95-ms <ms>    Optional repeated-run p95 duration maximum.
+  --dry-run            Print commands without executing them.
+  -h, --help           Show this help.
+
+Notes:
+  Without --ios-shim, iOS V1 is a simulator smoke path: install, launch,
+  deep link, screenshot, logs, and trace export. With --ios-shim, ZMR also
+  uses the shim for hierarchy and selector-grade actions. Physical-device
+  runs require --ios-device-type physical, a concrete --device identifier from
+  `zmr devices`, a signed app artifact, and an app-local XCTest shim for
+  selector-grade flows.
+USAGE
+}
+
+die() {
+  echo "error: $*" >&2
+  exit 2
+}
+
+require_value() {
+  local flag="$1"
+  local value="${2-}"
+  if [[ -z "$value" || "$value" == --* ]]; then
+    die "$flag requires a value"
+  fi
+  printf '%s\n' "$value"
+}
+
+resolve_path_from_cwd() {
+  local value="$1"
+  local absolute dir base probe suffix
+  if [[ -z "$value" ]]; then
+    printf '\n'
+    return 0
+  fi
+  if [[ "$value" == /* ]]; then
+    absolute="$value"
+  else
+    absolute="$CALLER_CWD/$value"
+  fi
+  if [[ -d "$absolute" ]]; then
+    cd "$absolute" && pwd -P
+    return 0
+  fi
+  if [[ -e "$absolute" ]]; then
+    dir="$(dirname "$absolute")"
+    base="$(basename "$absolute")"
+    printf '%s/%s\n' "$(cd "$dir" && pwd -P)" "$base"
+    return 0
+  fi
+  dir="$(dirname "$absolute")"
+  base="$(basename "$absolute")"
+  if [[ -d "$dir" ]]; then
+    printf '%s/%s\n' "$(cd "$dir" && pwd -P)" "$base"
+    return 0
+  fi
+  probe="$absolute"
+  suffix=""
+  while [[ "$probe" != "/" && ! -e "$probe" ]]; do
+    suffix="/$(basename "$probe")$suffix"
+    probe="$(dirname "$probe")"
+  done
+  if [[ -d "$probe" ]]; then
+    printf '%s%s\n' "$(cd "$probe" && pwd -P)" "$suffix"
+    return 0
+  fi
+  while [[ "$absolute" == *"/./"* ]]; do
+    absolute="${absolute//\/.\//\/}"
+  done
+  printf '%s\n' "$absolute"
+}
+
+resolve_command_path_from_cwd() {
+  local value="$1"
+  if [[ -z "$value" || "$value" != */* ]]; then
+    printf '%s\n' "$value"
+  else
+    resolve_path_from_cwd "$value"
+  fi
+}
+
+quote_cmd() {
+  local quoted=()
+  local arg
+  for arg in "$@"; do
+    quoted+=("$(printf '%q' "$arg")")
+  done
+  printf '%s\n' "${quoted[*]}"
+}
+
+run() {
+  echo "+ $(quote_cmd "$@")"
+  if [[ "$DRY_RUN" -eq 0 ]]; then
+    "$@"
+  fi
+}
+
+is_retryable_simctl_text() {
+  local text="$1"
+  [[ "$text" == *"CoreSimulatorService connection became invalid"* ]] ||
+    [[ "$text" == *"Failed to initialize simulator device set"* ]] ||
+    [[ "$text" == *"simdiskimaged"* ]] ||
+    [[ "$text" == *"Connection refused"* ]]
+}
+
+run_ios_install() {
+  if [[ "$IOS_DEVICE_TYPE" == "physical" ]]; then
+    run "$XCRUN" devicectl device install app --device "$DEVICE" "$APP_PATH"
+    return 0
+  fi
+
+  echo "+ $(quote_cmd "$XCRUN" simctl install "$DEVICE" "$APP_PATH")"
+  if [[ "$DRY_RUN" -eq 1 ]]; then
+    return 0
+  fi
+
+  local attempt status err_file err_text
+  err_file="$(mktemp)"
+  for attempt in 1 2 3 4 5 6; do
+    : > "$err_file"
+    set +e
+    "$XCRUN" simctl install "$DEVICE" "$APP_PATH" 2>"$err_file"
+    status=$?
+    set -e
+    if [[ "$status" -eq 0 ]]; then
+      rm -f "$err_file"
+      return 0
+    fi
+    err_text="$(cat "$err_file")"
+    if [[ "$attempt" == "6" ]] || ! is_retryable_simctl_text "$err_text"; then
+      cat "$err_file" >&2
+      rm -f "$err_file"
+      return "$status"
+    fi
+    echo "warning: simctl install hit a transient CoreSimulator error; retrying ($attempt/6)" >&2
+    sleep 0.5
+  done
+}
+
+prewarm_ios_shim() {
+  if [[ -z "$IOS_SHIM" || "$PREWARM_IOS_SHIM" -eq 0 ]]; then
+    return 0
+  fi
+
+  echo "+ printf '{\"cmd\":\"appState\"}\\n' | $(printf '%q' "$IOS_SHIM")"
+  if [[ "$DRY_RUN" -eq 1 ]]; then
+    return 0
+  fi
+
+  if ! printf '{"cmd":"appState"}\n' | "$IOS_SHIM" >/dev/null; then
+    echo "error: iOS XCTest shim prewarm failed" >&2
+    echo "hint: run the printed appState command directly, inspect .zmr/ios-shim-state/xcodebuild.build.log, and rerun with ZMR_IOS_SHIM_FORCE_REBUILD=1 after changing Xcode targets." >&2
+    exit 1
+  fi
+}
+
+physical_device_state_from_json() {
+  local devices_json="$1"
+  local serial="$2"
+  local state
+  for state in connected available disconnected unavailable paired; do
+    if [[ "$devices_json" == *'"serial":"'"$serial"'","state":"'"$state"'"'* ]]; then
+      printf '%s\n' "$state"
+      return 0
+    fi
+  done
+  printf 'unknown\n'
+}
+
+preflight_ios_device() {
+  if [[ "$DRY_RUN" -eq 1 ]]; then
+    return 0
+  fi
+
+  local devices_json
+  devices_json="$("$ZMR_BIN" devices --json --platform ios --ios-device-type "$IOS_DEVICE_TYPE" --xcrun "$XCRUN" 2>/dev/null || true)"
+  if [[ "$IOS_DEVICE_TYPE" == "physical" ]]; then
+    if [[ "$DEVICE" == "booted" ]]; then
+      echo "error: --device must be a physical iOS identifier when --ios-device-type physical is used" >&2
+      echo "errorCode: setup.ios.physical_device_required" >&2
+      exit 2
+    fi
+    if [[ "$devices_json" != *'"serial":"'"$DEVICE"'"'* ]]; then
+      echo "error: physical iOS device not found: $DEVICE" >&2
+      echo "errorCode: setup.ios.physical_device_not_found" >&2
+      echo "hint: connect and trust the device, enable Developer Mode, then run zmr devices --json --platform ios --ios-device-type physical --xcrun $(printf '%q' "$XCRUN")." >&2
+      exit 2
+    fi
+    if [[ "$devices_json" != *'"serial":"'"$DEVICE"'","state":"connected"'* && "$devices_json" != *'"serial":"'"$DEVICE"'","state":"available"'* ]]; then
+      local device_state
+      device_state="$(physical_device_state_from_json "$devices_json" "$DEVICE")"
+      echo "error: physical iOS device is not ready: $DEVICE" >&2
+      echo "state: $device_state" >&2
+      echo "errorCode: setup.ios.physical_device_not_ready" >&2
+      echo "hint: connect and trust the device, enable Developer Mode, confirm zmr devices reports state connected or available, then retry." >&2
+      exit 2
+    fi
+    return 0
+  fi
+  if [[ "$DEVICE" == "booted" ]]; then
+    if [[ "$devices_json" == *'"count":0'* || -z "$devices_json" ]]; then
+      if simctl_has_booted_device ""; then
+        return 0
+      fi
+      if [[ -z "$devices_json" ]]; then
+        echo "warning: could not verify booted iOS simulator during preflight; continuing to simctl install" >&2
+        return 0
+      fi
+      echo "error: no booted iOS simulator found" >&2
+      echo "errorCode: setup.ios.no_booted_simulators" >&2
+      echo "hint: boot a simulator, then run zmr doctor --json --xcrun $(printf '%q' "$XCRUN")." >&2
+      "$ZMR_BIN" doctor --json --xcrun "$XCRUN" >&2 || true
+      exit 2
+    fi
+    return 0
+  fi
+
+  if [[ "$devices_json" != *'"serial":"'"$DEVICE"'"'* ]]; then
+    if simctl_has_booted_device "$DEVICE"; then
+      return 0
+    fi
+    if [[ -z "$devices_json" ]]; then
+      echo "warning: could not verify iOS simulator during preflight; continuing to simctl install" >&2
+      return 0
+    fi
+    echo "error: iOS simulator not found or not booted: $DEVICE" >&2
+    echo "errorCode: setup.ios.no_booted_simulators" >&2
+    echo "hint: boot the requested simulator, then run zmr doctor --json --xcrun $(printf '%q' "$XCRUN")." >&2
+    "$ZMR_BIN" doctor --json --xcrun "$XCRUN" >&2 || true
+    exit 2
+  fi
+}
+
+simctl_has_booted_device() {
+  local wanted="${1:-}"
+  local booted_text
+  local attempt
+  for attempt in 1 2 3 4 5 6; do
+    booted_text="$("$XCRUN" simctl list devices booted 2>/dev/null || true)"
+    if [[ -n "$booted_text" ]]; then
+      if [[ -z "$wanted" && "$booted_text" == *"(Booted)"* ]]; then
+        return 0
+      fi
+      if [[ -n "$wanted" && "$booted_text" == *"$wanted"* && "$booted_text" == *"(Booted)"* ]]; then
+        return 0
+      fi
+    fi
+    sleep 0.5
+  done
+  return 1
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --app-root)
+      APP_ROOT="$(require_value "$1" "${2-}")"
+      shift 2
+      ;;
+    --app-path)
+      APP_PATH="$(require_value "$1" "${2-}")"
+      shift 2
+      ;;
+    --device)
+      DEVICE="$(require_value "$1" "${2-}")"
+      shift 2
+      ;;
+    --ios-device-type)
+      IOS_DEVICE_TYPE="$(require_value "$1" "${2-}")"
+      shift 2
+      ;;
+    --app-id)
+      APP_ID="$(require_value "$1" "${2-}")"
+      shift 2
+      ;;
+    --trace-root)
+      TRACE_ROOT="$(require_value "$1" "${2-}")"
+      shift 2
+      ;;
+    --zmr-bin)
+      ZMR_BIN="$(require_value "$1" "${2-}")"
+      shift 2
+      ;;
+    --xcrun)
+      XCRUN="$(require_value "$1" "${2-}")"
+      shift 2
+      ;;
+    --ios-shim)
+      IOS_SHIM="$(require_value "$1" "${2-}")"
+      shift 2
+      ;;
+    --skip-shim-prewarm)
+      PREWARM_IOS_SHIM=0
+      shift
+      ;;
+    --runs)
+      RUNS="$(require_value "$1" "${2-}")"
+      shift 2
+      ;;
+    --min-pass-rate)
+      MIN_PASS_RATE="$(require_value "$1" "${2-}")"
+      shift 2
+      ;;
+    --max-failures)
+      MAX_FAILURES="$(require_value "$1" "${2-}")"
+      shift 2
+      ;;
+    --max-mean-ms)
+      MAX_MEAN_MS="$(require_value "$1" "${2-}")"
+      shift 2
+      ;;
+    --max-p95-ms)
+      MAX_P95_MS="$(require_value "$1" "${2-}")"
+      shift 2
+      ;;
+    --dry-run)
+      DRY_RUN=1
+      shift
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      die "unknown argument: $1"
+      ;;
+  esac
+done
+
+[[ -n "$APP_PATH" ]] || die "--app-path is required"
+[[ "$RUNS" =~ ^[0-9]+$ && "$RUNS" -ge 1 ]] || die "--runs must be a positive integer"
+[[ "$IOS_DEVICE_TYPE" == "simulator" || "$IOS_DEVICE_TYPE" == "physical" ]] || die "--ios-device-type must be simulator or physical"
+[[ "$MIN_PASS_RATE" =~ ^[0-9]+([.][0-9]+)?$ ]] || die "--min-pass-rate must be a non-negative number"
+[[ "$MAX_FAILURES" =~ ^[0-9]+$ ]] || die "--max-failures must be a non-negative integer"
+[[ -z "$MAX_MEAN_MS" || "$MAX_MEAN_MS" =~ ^[0-9]+$ ]] || die "--max-mean-ms must be a non-negative integer"
+[[ -z "$MAX_P95_MS" || "$MAX_P95_MS" =~ ^[0-9]+$ ]] || die "--max-p95-ms must be a non-negative integer"
+
+APP_PATH="$(resolve_path_from_cwd "$APP_PATH")"
+TRACE_ROOT="$(resolve_path_from_cwd "$TRACE_ROOT")"
+ZMR_BIN="$(resolve_command_path_from_cwd "$ZMR_BIN")"
+XCRUN="$(resolve_command_path_from_cwd "$XCRUN")"
+if [[ -n "$APP_ROOT" ]]; then
+  APP_ROOT="$(resolve_path_from_cwd "$APP_ROOT")"
+fi
+if [[ -n "$IOS_SHIM" ]]; then
+  IOS_SHIM="$(resolve_command_path_from_cwd "$IOS_SHIM")"
+fi
+
+if [[ "$DRY_RUN" -eq 0 ]]; then
+  if [[ "$IOS_DEVICE_TYPE" == "physical" ]]; then
+    [[ -e "$APP_PATH" ]] || die "iOS physical app artifact not found: $APP_PATH"
+  else
+    if [[ "${APP_PATH##*.}" == "ipa" ]]; then
+      die "setup.ios.simulator_app_required: simulator runs require an iphonesimulator .app directory, but got an .ipa. Use a simulator-compatible .app build, or run a device IPA with --ios-device-type physical."
+    fi
+    [[ -d "$APP_PATH" ]] || die "setup.ios.simulator_app_required: simulator runs require an iphonesimulator .app directory: $APP_PATH"
+  fi
+  if [[ -n "$APP_ROOT" ]]; then
+    [[ -d "$APP_ROOT" ]] || die "app repo not found: $APP_ROOT"
+  fi
+fi
+
+echo "iOS pilot output: $TRACE_ROOT"
+if [[ -n "$APP_ROOT" ]]; then
+  echo "App root: $APP_ROOT"
+fi
+if [[ "$DRY_RUN" -eq 1 ]]; then
+  echo "DRY RUN: commands will be printed but not executed"
+fi
+
+run mkdir -p "$TRACE_ROOT" "$(dirname "$ZMR_BIN")"
+
+if [[ ! -x "$ZMR_BIN" ]]; then
+  target_args=()
+  if [[ "$(uname -s)" == "Darwin" && "$(uname -m)" == "arm64" ]]; then
+    target_args=(-target aarch64-macos.15.0)
+  fi
+  run zig build-exe src/main.zig "${target_args[@]}" -O Debug -femit-bin="$ZMR_BIN"
+fi
+
+run "$ZMR_BIN" version
+run "$ZMR_BIN" validate examples/ios-smoke.json
+if [[ -n "$IOS_SHIM" ]]; then
+  run "$ZMR_BIN" validate examples/ios-shim-smoke.json
+fi
+preflight_ios_device
+run_ios_install
+prewarm_ios_shim
+
+if [[ "$RUNS" -eq 1 ]]; then
+  TRACE_DIR="$TRACE_ROOT/ios-smoke"
+  run rm -rf "$TRACE_DIR"
+  if [[ -n "$IOS_SHIM" ]]; then
+    run "$ZMR_BIN" run examples/ios-smoke.json --platform ios --ios-device-type "$IOS_DEVICE_TYPE" --device "$DEVICE" --app-id "$APP_ID" --xcrun "$XCRUN" --ios-shim "$IOS_SHIM" --trace-dir "$TRACE_DIR"
+  else
+    run "$ZMR_BIN" run examples/ios-smoke.json --platform ios --ios-device-type "$IOS_DEVICE_TYPE" --device "$DEVICE" --app-id "$APP_ID" --xcrun "$XCRUN" --trace-dir "$TRACE_DIR"
+  fi
+  run "$ZMR_BIN" report "$TRACE_DIR" --out "$TRACE_DIR/report.html"
+  run "$ZMR_BIN" export "$TRACE_DIR" --out "$TRACE_ROOT/ios-smoke.zmrtrace"
+  run "$ZMR_BIN" export "$TRACE_DIR" --out "$TRACE_ROOT/ios-smoke-redacted.zmrtrace" --redact
+
+  if [[ -n "$IOS_SHIM" ]]; then
+    SHIM_TRACE_DIR="$TRACE_ROOT/ios-shim-smoke"
+    run rm -rf "$SHIM_TRACE_DIR"
+    run "$ZMR_BIN" run examples/ios-shim-smoke.json --platform ios --ios-device-type "$IOS_DEVICE_TYPE" --device "$DEVICE" --app-id "$APP_ID" --xcrun "$XCRUN" --ios-shim "$IOS_SHIM" --trace-dir "$SHIM_TRACE_DIR"
+    run "$ZMR_BIN" report "$SHIM_TRACE_DIR" --out "$SHIM_TRACE_DIR/report.html"
+    run "$ZMR_BIN" export "$SHIM_TRACE_DIR" --out "$TRACE_ROOT/ios-shim-smoke.zmrtrace"
+    run "$ZMR_BIN" export "$SHIM_TRACE_DIR" --out "$TRACE_ROOT/ios-shim-smoke-redacted.zmrtrace" --redact
+  fi
+else
+  benchmark_gate_args=(--min-pass-rate "$MIN_PASS_RATE" --max-failures "$MAX_FAILURES")
+  if [[ -n "$MAX_MEAN_MS" ]]; then
+    benchmark_gate_args+=(--max-mean-ms "$MAX_MEAN_MS")
+  fi
+  if [[ -n "$MAX_P95_MS" ]]; then
+    benchmark_gate_args+=(--max-p95-ms "$MAX_P95_MS")
+  fi
+
+  if [[ -n "$IOS_SHIM" ]]; then
+    ZMR_BIN="$ZMR_BIN" run "$ROOT/scripts/benchmark.sh" --zmr examples/ios-smoke.json --device "$DEVICE" --platform ios --ios-device-type "$IOS_DEVICE_TYPE" --app-id "$APP_ID" --xcrun "$XCRUN" --ios-shim "$IOS_SHIM" --runs "$RUNS" --trace-root "$TRACE_ROOT/ios-smoke-benchmark" "${benchmark_gate_args[@]}"
+  else
+    ZMR_BIN="$ZMR_BIN" run "$ROOT/scripts/benchmark.sh" --zmr examples/ios-smoke.json --device "$DEVICE" --platform ios --ios-device-type "$IOS_DEVICE_TYPE" --app-id "$APP_ID" --xcrun "$XCRUN" --runs "$RUNS" --trace-root "$TRACE_ROOT/ios-smoke-benchmark" "${benchmark_gate_args[@]}"
+  fi
+  run "$ZMR_BIN" report "$TRACE_ROOT/ios-smoke-benchmark" --out "$TRACE_ROOT/ios-smoke-benchmark/report.html"
+
+  if [[ -n "$IOS_SHIM" ]]; then
+    ZMR_BIN="$ZMR_BIN" run "$ROOT/scripts/benchmark.sh" --zmr examples/ios-shim-smoke.json --device "$DEVICE" --platform ios --ios-device-type "$IOS_DEVICE_TYPE" --app-id "$APP_ID" --xcrun "$XCRUN" --ios-shim "$IOS_SHIM" --runs "$RUNS" --trace-root "$TRACE_ROOT/ios-shim-smoke-benchmark" "${benchmark_gate_args[@]}"
+    run "$ZMR_BIN" report "$TRACE_ROOT/ios-shim-smoke-benchmark" --out "$TRACE_ROOT/ios-shim-smoke-benchmark/report.html"
+  fi
+fi
+
+echo
+echo "iOS pilot complete."
+echo "Output directory: $TRACE_ROOT"
+if [[ "$RUNS" -eq 1 ]]; then
+  echo "Shareable bundle:"
+  echo "  $TRACE_ROOT/ios-smoke-redacted.zmrtrace"
+  if [[ -n "$IOS_SHIM" ]]; then
+    echo "  $TRACE_ROOT/ios-shim-smoke-redacted.zmrtrace"
+  fi
+else
+  echo "Benchmark reports:"
+  echo "  $TRACE_ROOT/ios-smoke-benchmark/report.html"
+  if [[ -n "$IOS_SHIM" ]]; then
+    echo "  $TRACE_ROOT/ios-shim-smoke-benchmark/report.html"
+  fi
+fi
+echo "Viewer:"
+echo "  $ROOT/viewer/index.html"

package/shims/android/README.md

@@ -0,0 +1,21 @@
+# ZMR Android Shim
+
+This directory contains the native Android instrumentation shim scaffold that
+supplements the current ADB/UI Automator adapter.
+
+Current status:
+
+- `src/android.zig` provides the production preview path through ADB, shell
+  input, screenshots, logcat, and UI Automator XML.
+- `src/android.zig` can run a configured shim command with one JSON request on
+  stdin and one JSON response on stdout.
+- `scripts/install-android-shim.sh` writes an app-local `.zmr/android-shim`
+  command and copies the instrumentation source file into the app repo for
+  inclusion in `androidTest`.
+
+V1 target:
+
+- Faster hierarchy retrieval than repeated shell UI Automator dumps.
+- Reliable tap, type, swipe, and key actions with ADB fallback.
+- App idle/settle signals where Android APIs expose them reliably.
+- Clean error envelopes that flow into existing ZMR traces.

package/shims/android/ZMRShimInstrumentedTest.java

@@ -0,0 +1,152 @@
+package dev.zmr.shim;
+
+import android.graphics.Rect;
+import android.os.Bundle;
+import android.view.KeyEvent;
+
+import androidx.test.ext.junit.runners.AndroidJUnit4;
+import androidx.test.platform.app.InstrumentationRegistry;
+import androidx.test.uiautomator.By;
+import androidx.test.uiautomator.UiDevice;
+import androidx.test.uiautomator.UiObject2;
+import androidx.test.uiautomator.Until;
+
+import org.json.JSONArray;
+import org.json.JSONObject;
+import org.junit.Test;
+import org.junit.runner.RunWith;
+
+import java.io.File;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.util.List;
+
+@RunWith(AndroidJUnit4.class)
+public final class ZMRShimInstrumentedTest {
+    @Test
+    public void testRunZMRCommand() throws Exception {
+        Bundle args = InstrumentationRegistry.getArguments();
+        String requestFile = args.getString("zmrRequestFile");
+        String responseFile = args.getString("zmrResponseFile");
+        if (requestFile == null || responseFile == null) {
+            throw new IllegalArgumentException("zmrRequestFile and zmrResponseFile are required");
+        }
+
+        String request = new String(Files.readAllBytes(new File(requestFile).toPath()), StandardCharsets.UTF_8);
+        JSONObject command = new JSONObject(request);
+        JSONObject response = run(command, UiDevice.getInstance(InstrumentationRegistry.getInstrumentation()));
+        Files.write(new File(responseFile).toPath(), response.toString().getBytes(StandardCharsets.UTF_8));
+    }
+
+    private JSONObject run(JSONObject command, UiDevice device) throws Exception {
+        String cmd = command.optString("cmd", "");
+        switch (cmd) {
+            case "snapshot":
+                return ok().put("nodes", snapshot(device));
+            case "tap":
+                device.click(command.getInt("x"), command.getInt("y"));
+                return ok();
+            case "type":
+                device.executeShellCommand("input text " + escapeInputText(command.optString("text", "")));
+                return ok();
+            case "eraseText":
+                int count = command.optInt("maxChars", 0);
+                for (int i = 0; i < count; i += 1) {
+                    device.pressKeyCode(KeyEvent.KEYCODE_DEL);
+                }
+                return ok();
+            case "hideKeyboard":
+            case "pressBack":
+                device.pressBack();
+                return ok();
+            case "swipe":
+                device.swipe(
+                    command.getInt("x1"),
+                    command.getInt("y1"),
+                    command.getInt("x2"),
+                    command.getInt("y2"),
+                    Math.max(1, command.optInt("durationMs", 250) / 5)
+                );
+                return ok();
+            case "settle":
+                device.waitForIdle(command.optLong("durationMs", 1000));
+                return ok();
+            case "appState":
+                return ok().put("state", "ready");
+            default:
+                return error("unknown.command", "unsupported command: " + cmd);
+        }
+    }
+
+    private JSONArray snapshot(UiDevice device) throws Exception {
+        device.waitForIdle();
+        List<UiObject2> objects = device.wait(Until.findObjects(By.depth(0)), 1000);
+        JSONArray nodes = new JSONArray();
+        appendChildren(nodes, device.findObject(By.depth(0)), "root");
+        if (nodes.length() == 0 && objects != null) {
+            for (int i = 0; i < objects.size(); i += 1) {
+                appendNode(nodes, objects.get(i), "node:" + i);
+            }
+        }
+        return nodes;
+    }
+
+    private void appendChildren(JSONArray nodes, UiObject2 object, String prefix) throws Exception {
+        if (object == null) return;
+        appendNode(nodes, object, prefix);
+        List<UiObject2> children = object.getChildren();
+        for (int i = 0; i < children.size(); i += 1) {
+            appendChildren(nodes, children.get(i), prefix + ":" + i);
+        }
+    }
+
+    private void appendNode(JSONArray nodes, UiObject2 object, String fallbackId) throws Exception {
+        Rect bounds = object.getVisibleBounds();
+        String resourceName = object.getResourceName();
+        String text = object.getText();
+        String description = object.getContentDescription();
+        String id = resourceName != null && !resourceName.isEmpty() ? "id:" + resourceName : fallbackId;
+
+        JSONObject node = new JSONObject();
+        node.put("id", id);
+        node.put("type", object.getClassName());
+        node.put("label", text == null ? "" : text);
+        node.put("identifier", resourceName == null ? "" : resourceName);
+        node.put("contentDescription", description == null ? "" : description);
+        node.put("enabled", object.isEnabled());
+        node.put("visible", bounds.width() > 0 && bounds.height() > 0);
+        node.put("selected", object.isSelected());
+        node.put("bounds", new JSONObject()
+            .put("x", bounds.left)
+            .put("y", bounds.top)
+            .put("width", bounds.width())
+            .put("height", bounds.height()));
+        nodes.put(node);
+    }
+
+    private JSONObject ok() throws Exception {
+        return new JSONObject().put("status", "ok");
+    }
+
+    private JSONObject error(String code, String message) throws Exception {
+        return new JSONObject()
+            .put("status", "error")
+            .put("code", code)
+            .put("message", message);
+    }
+
+    private String escapeInputText(String value) {
+        return value
+            .replace("\\", "\\\\")
+            .replace(" ", "%s")
+            .replace("&", "\\&")
+            .replace("<", "\\<")
+            .replace(">", "\\>")
+            .replace(";", "\\;")
+            .replace("|", "\\|")
+            .replace("*", "\\*")
+            .replace("~", "\\~")
+            .replace("\"", "\\\"")
+            .replace("'", "\\'");
+    }
+}