@aarwitz/tapp 0.15.0

package/docs/application-model.md

@@ -0,0 +1,276 @@
+# Application model and `tapp init`
+
+`tapp init` is the deterministic import, exploration, and planning entrypoint of Tapp's customer
+journey. It turns a repository into three platform-neutral, repository-native artifacts:
+
+- `.autotap/ui-map.json` — observed UI states, controls, and transitions from real exploration;
+- `.autotap/application-model.json` — what Tapp can support with evidence;
+- `.autotap/release-plan.json` — the compact set of committed and proposed business guarantees a
+  customer must review before generation.
+
+Plain `tapp init` performs source/artifact inspection only. `tapp init --explore` additionally uses
+the same keyless QA engine as `tapp qa` to build/install/launch or connect to one selected real
+target, merge the observed map, and construct the model and plan from that runtime evidence. It
+does not generate or approve tests, call AI, or claim contract validation. When iOS repository
+resolution actually builds and installs the detected Xcode container, the model records the exact
+scheme as runtime-observed validation and removes the corresponding confirmation blocker. Merely
+supplying a bundle id or prebuilt `.app` does not prove repository build configuration.
+
+## First inspection
+
+```bash
+# Read-only preview. For web, provide the owned runtime URL if already known.
+tapp init . --url http://127.0.0.1:3000 --dry-run \
+  --json-out /tmp/tapp-init-preview.json
+
+# Create canonical artifacts. Existing files are never overwritten implicitly.
+tapp init . --url http://127.0.0.1:3000
+
+# Build/start the detected web target, explore it, persist its UI Map, then stop it.
+tapp init . --explore --platform web --actions 40 --timeout 600
+
+# Or connect to an already-running owned environment.
+tapp init . --explore --platform web --url http://127.0.0.1:3000 \
+  --actions 40 --timeout 600
+
+# iOS can resolve a repository/Xcode container/.app/bundle id and build when needed.
+tapp init . --explore --platform ios --target .
+
+# Android can install an APK, then launch the explicit application id.
+tapp init . --explore --platform android \
+  --apk app/build/outputs/apk/debug/app-debug.apk --app-id com.acme.app
+
+# Re-inspect after source/UI Map changes while preserving explicit review decisions.
+tapp init . --url http://127.0.0.1:3000 --refresh
+
+# Re-explore after review without losing approve/reject/defer choices.
+tapp init . --refresh --explore --platform web --url http://127.0.0.1:3000
+```
+
+MCP clients use `tapp_init` with `operation: inspect|write|refresh|explore`. `inspect` is the safe
+default. `explore` writes real evidence, so the CLI rejects `--explore --dry-run`; the CLI also
+requires `--refresh --explore` once model/plan artifacts exist. Credentials are passed only to the
+runtime and are never written into the model, map, or plan.
+
+Successful repository-driven iOS build validation is portable and durable. The application model
+stores the repository-relative container, scheme, configuration, bundle id, and a
+`tapp-capture:<id>` evidence reference—never the local DerivedData or checkout path. A later
+source-only `tapp init --refresh` retains that validation when it still names the same detected
+container. Tapp does not infer equivalent proof from an installed application, an explicit bundle
+id, or a prebuilt artifact; those paths can demonstrate runtime reachability but cannot silently
+confirm the repository's Xcode scheme.
+
+## Actors and credential bindings
+
+Configure named actors once instead of repeating credentials or session policy across tests:
+
+```bash
+tapp actor set alice . --role member --session isolated --provisioning seeded \
+  --credential email=ALICE_EMAIL --credential password=ALICE_PASSWORD
+tapp actor set bob . --role member --session isolated --provisioning seeded \
+  --credential email=BOB_EMAIL --credential password=BOB_PASSWORD
+tapp actor list .
+tapp init . --refresh
+```
+
+This writes `.autotap/project.json`. The file contains roles, `default`/`isolated` session policy,
+provisioning mode, same-origin lifecycle declarations, and environment-variable *names*. The CLI
+and MCP `tapp_actor_config` reject credential values and refuse to replace an actor without an
+explicit `--replace`/`replace: true`. Contracts refer to `$ALICE_EMAIL`-style placeholders. Tapp
+merges those reviewed placeholders with the central configuration, blocks missing/conflicting
+bindings, and never copies resolved values into the application model, release plan, UI Map, CI
+manifest, or generated workflow.
+
+When web `--url` is omitted, Tapp selects one detected browser target, runs only its internally
+derived lockfile-backed install command, runs its declared build script when present, and starts its
+`start`, `dev`, `serve`, or `preview` package script with argument-array process execution (never
+generated shell source). A static site with no script uses Tapp's local read-only static server. The
+runtime binds to an available loopback port, writes its log under the Tapp runtime directory, and is
+terminated after exploration even when QA fails. Multiple web targets, an unlocked dependency
+graph, an unrecognized start path, or backend-specific configuration produce explicit remediation;
+provide `--target` and/or an already-running owned `--url` in those cases. Running repository build
+scripts executes repository code and should only be used for a checkout the customer trusts.
+The managed loop never persists its ephemeral loopback URL as customer configuration. The model
+records `runtime.management: tapp-managed`, and the portable gate/Action reconstructs the same
+start/wait/stop lifecycle later. An explicitly supplied owned URL remains `customer-managed`.
+
+## What the model records
+
+Application Model v1 records:
+
+- detected iOS simulator, Android application, and browser targets;
+- inspectable build commands, project/module/container paths, scheme candidates, application ids,
+  owned URLs, missing confirmations, and exact runtime-observed target validation where Tapp itself
+  completed the repository build/install path;
+- actors, roles, provisioning modes, credential requirements/environment bindings, and
+  session-isolation boundaries without credential values;
+- business entities and capabilities explicitly declared by reviewed contracts or conservatively
+  derived from reusable Task names;
+- authored critical journeys, revenue paths, and cross-actor system invariants;
+- the shared UI Map's observed state/transition/control counts and uncovered ids;
+- the latest import exploration's verdict and explicit inconclusive status, when available;
+- existing Tasks and contracts;
+- blocking requirements and exact remediation.
+
+Every fact identifies its evidence class. The current deterministic importer uses:
+
+- `source-observed` for repository files and build metadata;
+- `runtime-observed` for a successful exact target build/install/exploration, with portable evidence;
+- `reviewed-artifact` for committed Tasks, contracts, and UI Map evidence;
+- `task-derived` or another source-derived status when a fact still requires review;
+- `authored-unvalidated` when a committed contract exists without current-revision replay proof.
+
+Runtime observation, source inference, optional AI proposals, and human decisions must not be
+collapsed into one confidence label. The artifact explicitly records that remote AI was not used.
+
+## Release-plan quality
+
+The deterministic planner starts with committed contracts, then proposes only evidence-grounded
+gaps:
+
+- a conservative cross-actor propagation guarantee when two explicitly configured isolated actors,
+  deterministic setup/teardown, compatible authentication/precondition screens, and an exact
+  content-producing Task output jointly prove that the proposal is grounded;
+- reusable Tasks not composed by a reviewed contract;
+- uncovered UI states carrying business signals such as authentication, pricing, checkout,
+  account, messaging, or settings behavior.
+
+Error pages, blank pages, loading surfaces, changelogs, and generic feature-description pages remain
+visible as UI Map coverage gaps but do not automatically become business contracts. The target is
+approximately 5–15 contracts for a sufficiently rich product, not an artificial quota for a small
+fixture. Every proposal includes business value, risk, criticality, actors, platforms, grounding,
+and the real-surface validation required before it can be trusted.
+
+## Explicit review
+
+```bash
+tapp plan show .autotap/release-plan.json
+tapp plan review .autotap/release-plan.json \
+  --approve signInWorks,checkoutWorks \
+  --reject marketingPageReachable \
+  --defer adminAuditWorks
+
+# Only after review: generate grounded Task + contract drafts under .autotap/proposals/.
+tapp plan generate .autotap/release-plan.json --project-dir .
+
+# Replay the draft on the real target and attach evidence to the plan.
+# Omit --url to build/start/stop the detected managed browser target.
+tapp plan validate .autotap/release-plan.json --project-dir . --platform web
+# Or connect to an already-running owned environment.
+tapp plan validate .autotap/release-plan.json --project-dir . \
+  --platform web --url http://127.0.0.1:3000
+
+# Explicitly accept only fully validated drafts into canonical reviewed locations.
+tapp plan promote .autotap/release-plan.json --project-dir . \
+  --item checkoutWorks
+```
+
+The MCP equivalent is `tapp_release_plan` with `read|review|generate|validate|promote`. Review
+changes decision metadata only. It cannot silently
+edit a Task, contract, selector, or assertion. On `tapp init --refresh`, decisions, constraints, and
+review notes are carried forward by stable item id; reviewed items no longer derived from current
+evidence are retained and marked stale instead of disappearing.
+
+A source-only refresh preserves recorded replay evidence. `tapp init --refresh --explore` carries
+the history forward but invalidates trust for affected generated Tasks and contracts: prior
+platform results move to historical evidence, status becomes `requires-revalidation`, and replay is
+required before the draft can be trusted against the newly observed revision. Exploration never
+silently self-heals or accepts the prior selector path.
+
+The macOS desktop Coverage experience reads these same files. Its **Application** tab explains
+detected targets, actors, capabilities, journeys, Tasks, contracts, and exact remediation. Its
+**Release Plan** tab writes explicit approve/reject/defer decisions atomically into the canonical
+plan while preserving fields from newer engine versions; committed contract intent is not editable
+through these proposal controls. Flow Map merges the repository `.autotap/ui-map.json` with current
+run evidence instead of building a separate desktop-only graph.
+
+Schema compatibility can be rehearsed headlessly after building the desktop app:
+
+```bash
+AutoTap.app/Contents/MacOS/AutoTap --verify-artifacts /path/to/repository \
+  --out /tmp/tapp-desktop-artifacts.json
+```
+
+`plan generate` handles only explicitly approved proposals. Grounded cross-actor proposals preserve
+actor-attributed Task calls, captured output variables, bounded eventual assertions, and the
+reviewed project lifecycle, then compile through the isolated Scenario executor. Existing
+Task-backed proposals compose those reviewed Tasks. For UI-Map-only proposals, it finds an observed path from each platform's
+recorded entry state, deduplicates shared semantic transitions into compositional Task drafts under
+`.autotap/proposals/tasks/`, grounds every Task in exact node/edge ids, and writes the contract draft
+under `.autotap/proposals/contracts/`. Proposal Tasks are visible only to proposal contracts; an
+ordinary committed contract or CI glob cannot silently consume one.
+
+Generation blocks when entry-state evidence is missing, the target is unreachable, an observed
+action cannot be represented deterministically, or platform paths require incompatible semantic
+composition. It never overwrites a draft, statically compiles each declared platform, and marks all
+outputs untrusted. Missing non-secret Task inputs stay blocked until the plan has explicit bindings;
+standard email/password secrets remain placeholders. Successful grounding and compilation are not
+real-surface evidence and never promote drafts into `.autotap/tasks` or `.autotap/contracts`.
+
+`plan validate` invokes the ordinary deterministic contract executor and records pass/fail evidence
+per declared platform. A multi-platform draft remains only partially validated until every declared
+platform passes. Failed replay remains visible and sets `trusted: false`; there is no selector
+substitution or automatic assertion update.
+
+`plan promote` is the explicit acceptance boundary. It refuses any contract or generated Task that
+has not passed every declared platform, preflights every destination, never overwrites a reviewed
+artifact, moves accepted files from `.autotap/proposals/{tasks,contracts}` into
+`.autotap/{tasks,contracts}`, and applies their exact node/edge coverage to the canonical UI Map.
+Shared Task paths in still-unpromoted proposals are rewritten to the canonical file. Promotion does
+not commit, push, or install CI; the resulting repository patch remains reviewable by the customer.
+
+## Baseline and CI handoff
+
+After promotion, complete the local onboarding loop with:
+
+```bash
+# Runs the ordinary autonomous QA + committed suites gate. Builds native targets when possible;
+# web targets can be detected, built, started, awaited, and stopped without a durable URL.
+tapp baseline create . --platform web
+
+# Or import an already-retained successful full-gate report after review.
+tapp baseline create . --platform web --from /path/to/tapp-report.json
+
+# Generate one target-aware job per model target plus a machine-readable manifest.
+tapp ci install . --action-ref aarwitz/tapp@v0.13.1
+```
+
+Baseline creation rejects non-gate JSON, missing or mismatched target identity, platform mismatch,
+failed Flows/Scenarios/contracts, `blocked`, and `inconclusive`. It writes atomically to
+`.autotap/baselines/<platform>/<target-id>.json` and requires `--replace` to supersede reviewed
+evidence. Capture-local paths are replaced with portable `tapp-capture:` references before the
+repository artifact is written. The gate also checks baseline platform and target identity before
+comparing findings. On iOS, the same validated launch arguments and string-valued launch
+environment are passed to autonomous exploration and deterministic Flow/contract replay; invalid
+JSON or unsupported value types fail before execution rather than silently testing different app
+configurations.
+
+CI installation writes `.github/workflows/tapp.yml` and `.autotap/ci.json`, never overwrites by
+default, and refuses unresolved iOS schemes, Android ids, browser lockfiles, or runtimes. The
+workflow uses exact contract paths, maps each actor environment binding to a same-named GitHub
+Secret, uses the first/default actor for autonomous-login inputs, preserves the remaining bindings
+for deterministic multi-actor replay, and supports managed web startup, Android emulator
+provisioning, and the target-specific baseline. It does not commit,
+push, enable branch protection, or create remote resources. Use MCP `tapp_ci_setup` for the same
+read-only render, baseline import, and guarded install engine.
+
+## Current boundary
+
+Repository detection, one-target real exploration, first-map merge, evidence classification,
+runtime-observed iOS scheme confirmation, durable source-only refresh, deterministic planning, safe
+persistence, approve/reject/defer review, and compile-checked Task-backed draft generation are
+implemented. An empty map or a latest exploration marked inconclusive remains a blocking
+requirement; observing a login wall is not treated as useful coverage.
+
+`tapp init` does not yet orchestrate every detected target in one invocation, provision arbitrary
+web backends/services, automatically replay every approved draft, or promote validated drafts without
+explicit customer acceptance. Baseline creation and a reviewable per-target GitHub CI patch are now
+implemented as explicit post-promotion commands, but the generated workflow has not yet passed on
+current GitHub-hosted iOS, Android, and web runners. Task generation currently handles observed
+reachable navigation. Deterministic business planning is deliberately limited to cross-actor
+content propagation and one checkout-to-order-history persistence pattern supported by exact Task
+input/output, screen, actor, UI Map, and lifecycle evidence. General forms, broader payment shapes,
+dynamic value capture, messaging/reactions, role-asymmetric invariants, and incompatible platform
+journeys still require reviewed authoring. Optional
+AI business reasoning is also not wired into this path. Those missing stages remain completion
+blockers.

package/docs/scenarios.md

@@ -0,0 +1,95 @@
+# Multi-actor Scenarios
+
+A Scenario is Tapp's low-level deterministic multi-actor execution format in `.autotap/scenarios/*.yml`. It uses the same semantic actions, polling assertions, timeouts, evidence markers, and merge policy as a Flow, but adds isolated named actors, shared variables, and explicit lifecycle steps. The customer-facing business authoring layer is a TypeScript [release contract](release-contracts.md), which composes reusable Tasks and compiles to this runtime instead of duplicating UI steps.
+
+Ordinary replay is keyless. AI may propose a Scenario during authoring, but no model, API key, or coding agent participates when CI executes it.
+
+## Current support
+
+Web replay is implemented through one isolated Playwright browser context per actor. Cookies, local storage, and in-browser session state cannot leak between actors; all contexts point at the same deployed application and backend. The Action, portable gate, CLI, and MCP surface all consume the same file.
+
+iOS and Android still support sequential account switching inside ordinary Flows, but do not yet have first-class isolated multi-actor Scenario drivers. Tapp rejects those platform combinations instead of presenting sequential login/logout as equivalent proof.
+
+## Contract
+
+```yaml
+name: Alice publishes and Bob sees it
+kind: scenario
+platform: web
+url: http://127.0.0.1:4180
+timeoutMs: 6000
+vars:                         # shared deterministic data
+  POST: Scenario post 7319
+actors:
+  alice:
+    vars:                     # actor-scoped credentials/session inputs
+      EMAIL: alice@example.test
+      PASSWORD: demo
+  bob:
+    vars:
+      EMAIL: bob@example.test
+      PASSWORD: demo
+setup:
+  - request:                  # bounded, same-origin HTTP; never arbitrary shell
+      method: POST
+      path: /__tapp/reset
+      status: 200
+steps:
+  - actor: alice
+    type: { field: Email, value: $EMAIL }
+  - actor: alice
+    type: { field: Password, value: $PASSWORD }
+  - actor: alice
+    tap: Sign in
+  - actor: alice
+    type: { field: Post text, value: $POST }
+  - actor: alice
+    tap: Publish
+  - actor: bob
+    assert_exists: { target: $POST, timeoutMs: 6000 }
+teardown:
+  - request: { method: POST, path: /__tapp/reset, status: 200 }
+```
+
+- `actors` must contain at least two names. Every journey step names one of them.
+- Actor variables override shared variables. A committed value such as `$ALICE_PASSWORD` resolves only that explicitly referenced environment variable at run time; Tapp does not serialize the surrounding environment.
+- `setup` and `teardown` currently accept bounded HTTP request steps on the target origin. Teardown runs after a journey failure so state is still cleaned up.
+- Flow assertions poll until their bounded timeout. This models eventual consistency without blind sleeps or unbounded retries. A condition that never becomes true fails visibly.
+- Typed values are not written to step evidence. Results include actor, action, selector, status, and error; failures capture that actor's screen and final screenshots for all actors.
+- A failed Scenario always blocks the release gate, independently of whether autonomous single-user exploration found a problem.
+
+## Run it
+
+```bash
+tapp scenario validate .autotap/scenarios/social-system.yml
+ALICE_EMAIL=alice@example.test ALICE_PASSWORD=demo \
+BOB_EMAIL=bob@example.test BOB_PASSWORD=demo \
+  tapp scenario run .autotap/scenarios/social-system.yml
+
+tapp ci --platform web --url http://127.0.0.1:4180 \
+  --scenarios '.autotap/scenarios/*.yml' \
+  --json-out tapp-report.json --md-out tapp-report.md
+```
+
+GitHub Action:
+
+```yaml
+- uses: aarwitz/tapp@main
+  with:
+    platform: web
+    url: http://127.0.0.1:4180
+    scenarios: .autotap/scenarios/*.yml
+```
+
+MCP clients call `tapp_scenario_run` with `scenarioPath`, or an inline reviewed Scenario. The structured result identifies `kind: scenario`, actual executed/total steps, and actor-tagged steps.
+
+## Verified fixture and boundaries
+
+`SocialDemo/.autotap/contracts/social-system.contract.ts` is the reference system guarantee; the Scenario remains its low-level execution proof and backwards-compatible escape hatch. On 2026-08-04 the contract passed 41/41 compiled steps using two isolated contexts against one delayed shared backend. With `SOCIAL_DEMO_FAULT=hide-cross-actor-posts`, the unchanged contract failed for Bob at 19/41 and the portable merge gate exited non-zero specifically because one release contract failed.
+
+The fixture's `.autotap/project.json` is the central actor contract. It records Alice and Bob's
+roles, isolated sessions, seeded provisioning, reset lifecycle, and four environment-variable
+names. The release contract and Scenario consume those names; neither stores the public fixture
+values. Customer values belong in the local environment or CI secret store.
+
+This proves the contract and web implementation, not universal multi-user reliability. Real customers still need reset/provisioning hooks or dedicated test data, enough accessibility semantics to select controls, and a test backend whose eventual-consistency budget is known.

package/mcp-server/src/android-driver.js

@@ -0,0 +1,287 @@
+// Native black-box Android driver: the UIAutomator/ADB counterpart to Tapp's
+// generic XCUITest harness. It can attach to any debuggable or release APK
+// without linking a Tapp SDK into the app.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { execFile } from "node:child_process";
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+function executable(name, env = process.env) {
+  const suffix = process.platform === "win32" ? ".exe" : "";
+  const homes = [
+    env.ANDROID_SDK_ROOT,
+    env.ANDROID_HOME,
+    env.HOME && path.join(env.HOME, "Library", "Android", "sdk"),
+    env.HOME && path.join(env.HOME, "Android", "Sdk"),
+    "/opt/homebrew/share/android-commandlinetools",
+    "/usr/local/share/android-commandlinetools",
+  ].filter(Boolean);
+  for (const home of homes) {
+    const p = path.join(home, "platform-tools", name + suffix);
+    if (fs.existsSync(p)) return p;
+  }
+  for (const dir of String(env.PATH || "").split(path.delimiter)) {
+    const p = path.join(dir, name + suffix);
+    if (fs.existsSync(p)) return p;
+  }
+  return null;
+}
+
+export function resolveAdbPath(env = process.env) {
+  return executable("adb", env);
+}
+
+function runFile(command, args, { encoding = "utf8", timeout = 30_000, maxBuffer = 16 * 1024 * 1024 } = {}) {
+  return new Promise((resolve) => {
+    execFile(command, args, { encoding, timeout, maxBuffer }, (error, stdout, stderr) => {
+      resolve({ code: error?.code && Number.isInteger(error.code) ? error.code : error ? 1 : 0, stdout, stderr, error });
+    });
+  });
+}
+
+function entityDecode(value) {
+  return String(value || "")
+    .replaceAll(""", '"').replaceAll("'", "'")
+    .replaceAll("&lt;", "<").replaceAll("&gt;", ">").replaceAll("&amp;", "&");
+}
+
+function bounds(value) {
+  const m = String(value || "").match(/^\[(\d+),(\d+)\]\[(\d+),(\d+)\]$/);
+  if (!m) return { x: 0, y: 0, w: 0, h: 0 };
+  const [, x1, y1, x2, y2] = m.map(Number);
+  return { x: x1, y: y1, w: Math.max(0, x2 - x1), h: Math.max(0, y2 - y1) };
+}
+
+export function parseUiAutomatorXml(xml) {
+  const nodes = [];
+  for (const match of String(xml || "").matchAll(/<node\s+([^>]*?)(?:\/?>)/g)) {
+    const attrs = {};
+    for (const a of match[1].matchAll(/([\w:-]+)="([^"]*)"/g)) attrs[a[1]] = entityDecode(a[2]);
+    const frame = bounds(attrs.bounds);
+    const text = attrs.text || "";
+    const description = attrs["content-desc"] || "";
+    const resourceId = attrs["resource-id"] || "";
+    nodes.push({
+      type: attrs.class || "android.view.View",
+      id: resourceId,
+      label: description || text,
+      text,
+      value: text,
+      description,
+      package: attrs.package || "",
+      enabled: attrs.enabled !== "false",
+      clickable: attrs.clickable === "true",
+      focusable: attrs.focusable === "true",
+      focused: attrs.focused === "true",
+      scrollable: attrs.scrollable === "true",
+      secure: attrs.password === "true",
+      selected: attrs.selected === "true",
+      hittable: attrs.enabled !== "false" && attrs["visible-to-user"] !== "false" && frame.w > 0 && frame.h > 0,
+      ...frame,
+    });
+  }
+  return nodes;
+}
+
+export function androidElementKey(element) {
+  return element.id || element.description || element.text || `${element.type}:${element.x},${element.y}`;
+}
+
+export function findAndroidElement(elements, target, { hittable = false } = {}) {
+  const wanted = String(target || "").trim();
+  if (!wanted) return null;
+  const pool = hittable ? elements.filter((e) => e.hittable) : elements;
+  const exact = (value) => value && value.localeCompare(wanted, undefined, { sensitivity: "accent" }) === 0;
+  return pool.find((e) => exact(e.id))
+    || pool.find((e) => e.id && e.id.endsWith(`/${wanted}`))
+    || pool.find((e) => exact(e.description))
+    || pool.find((e) => exact(e.text))
+    || pool.find((e) => exact(e.label))
+    || pool.find((e) => [e.description, e.text, e.label].some((v) => v && v.toLowerCase().includes(wanted.toLowerCase())))
+    || null;
+}
+
+export function detectAndroidScreen(elements, activity = "") {
+  const explicit = elements.find((e) => /\/(screen_title|toolbar_title|title)$/.test(e.id) && e.text);
+  if (explicit) return explicit.text;
+  const described = elements.find((e) => /^screen:/i.test(e.description));
+  if (described) return described.description.replace(/^screen:\s*/i, "");
+  const topText = elements
+    .filter((e) => e.text && e.y < 260 && !/statusbar|navigationbar/i.test(e.type))
+    .sort((a, b) => a.y - b.y || a.x - b.x)[0];
+  if (topText) return topText.text;
+  const component = String(activity || "").split("/").at(-1)?.replace(/^\./, "").replace(/Activity$/, "");
+  return component || "Unknown";
+}
+
+export function isAndroidAppSnapshot(snapshot, appId) {
+  if (!snapshot || !appId) return false;
+  if (String(snapshot.activity || "").startsWith(`${appId}/`)) return true;
+  return snapshot.elements.some((e) => e.package === appId);
+}
+
+export class AndroidDriver {
+  constructor({ adbPath = resolveAdbPath(), serial = "", appId = "" } = {}) {
+    if (!adbPath) throw new Error("Android testing needs adb. Install Android SDK platform-tools or set ANDROID_SDK_ROOT.");
+    this.adbPath = adbPath;
+    this.serial = serial;
+    this.appId = appId;
+  }
+
+  args(args) { return this.serial ? ["-s", this.serial, ...args] : args; }
+  async adb(args, options) { return runFile(this.adbPath, this.args(args), options); }
+
+  async ensureDevice() {
+    const r = await runFile(this.adbPath, ["devices", "-l"]);
+    if (r.code !== 0) throw new Error((r.stderr || "adb devices failed").trim());
+    const devices = String(r.stdout).split(/\r?\n/).slice(1)
+      .map((line) => line.trim().split(/\s+/)).filter((p) => p[0] && p[1] === "device");
+    if (this.serial) {
+      if (!devices.some(([serial]) => serial === this.serial)) throw new Error(`Android device ${this.serial} is not connected and authorized`);
+    } else if (devices.length) {
+      this.serial = devices[0][0];
+    } else {
+      throw new Error("No connected Android emulator/device. Start an emulator or connect a device with USB debugging enabled.");
+    }
+    return { serial: this.serial };
+  }
+
+  async install(apkPath) {
+    const r = await this.adb(["install", "-r", "-t", apkPath], { timeout: 180_000 });
+    if (r.code !== 0 || !String(r.stdout).includes("Success")) throw new Error((r.stderr || r.stdout || "APK install failed").trim());
+    return true;
+  }
+
+  async forceStop() {
+    if (this.appId) await this.adb(["shell", "am", "force-stop", this.appId]);
+  }
+
+  async clearData() {
+    if (!this.appId) throw new Error("appId is required to clear Android app data");
+    const r = await this.adb(["shell", "pm", "clear", this.appId]);
+    if (!String(r.stdout).includes("Success")) throw new Error((r.stderr || r.stdout || "Could not clear app data").trim());
+  }
+
+  async launch({ clearData = false } = {}) {
+    await this.ensureDevice();
+    if (!this.appId) throw new Error("Android appId is required");
+    await this.forceStop();
+    if (clearData) await this.clearData();
+    const resolved = await this.adb(["shell", "cmd", "package", "resolve-activity", "--brief", "-c", "android.intent.category.LAUNCHER", this.appId]);
+    const component = String(resolved.stdout || "").split(/\r?\n/).map((s) => s.trim()).findLast((s) => s.includes("/"));
+    if (!component) throw new Error(`No launchable Activity found for ${this.appId}`);
+    const r = await this.adb(["shell", "am", "start", "-W", "-n", component], { timeout: 30_000 });
+    if (r.code !== 0 || !/Status:\s*ok/i.test(String(r.stdout))) throw new Error((r.stderr || r.stdout || `Could not launch ${this.appId}`).trim());
+    await sleep(600);
+    return this.snapshot();
+  }
+
+  async currentActivity() {
+    const activity = await this.adb(["shell", "dumpsys", "activity", "activities"]);
+    const atext = String(activity.stdout || "");
+    const resumed = (atext.match(/mResumedActivity:.*?\s([\w.$]+\/[\w.$]+)/) || atext.match(/topResumedActivity=.*?\s([\w.$]+\/[\w.$]+)/) || [])[1];
+    if (resumed) return resumed;
+    const window = await this.adb(["shell", "dumpsys", "window", "windows"]);
+    const wtext = String(window.stdout || "");
+    return (wtext.match(/mCurrentFocus=.*?\s([\w.$]+\/[\w.$]+)/) || wtext.match(/mFocusedApp=.*?\s([\w.$]+\/[\w.$]+)/) || [])[1] || "";
+  }
+
+  async dumpXml() {
+    let r = await this.adb(["exec-out", "uiautomator", "dump", "/dev/tty"], { timeout: 20_000, maxBuffer: 24 * 1024 * 1024 });
+    let output = String(r.stdout || "");
+    let at = output.indexOf("<?xml");
+    if (r.code !== 0 || at < 0) {
+      const remote = `/sdcard/tapp-window-${process.pid}.xml`;
+      await this.adb(["shell", "uiautomator", "dump", remote], { timeout: 20_000 });
+      r = await this.adb(["exec-out", "cat", remote], { timeout: 20_000, maxBuffer: 24 * 1024 * 1024 });
+      await this.adb(["shell", "rm", "-f", remote]);
+      output = String(r.stdout || "");
+      at = output.indexOf("<?xml");
+    }
+    if (at < 0) throw new Error((r.stderr || "UIAutomator produced no XML hierarchy").trim());
+    return output.slice(at);
+  }
+
+  async snapshot() {
+    const [xml, activity] = await Promise.all([this.dumpXml(), this.currentActivity()]);
+    const elements = parseUiAutomatorXml(xml);
+    return { screenTitle: detectAndroidScreen(elements, activity), elements, activity, xml };
+  }
+
+  async screenshot(filePath) {
+    const r = await this.adb(["exec-out", "screencap", "-p"], { encoding: "buffer", timeout: 30_000, maxBuffer: 32 * 1024 * 1024 });
+    if (r.code !== 0 || !r.stdout?.length) throw new Error("Android screenshot failed");
+    if (filePath) {
+      fs.mkdirSync(path.dirname(filePath), { recursive: true });
+      fs.writeFileSync(filePath, r.stdout);
+    }
+    return r.stdout;
+  }
+
+  async settle(timeoutMs = 2200) {
+    const deadline = Date.now() + timeoutMs;
+    let previous = "";
+    let stable = 0;
+    let latest;
+    while (Date.now() < deadline) {
+      latest = await this.snapshot();
+      const fingerprint = latest.elements.map((e) => `${androidElementKey(e)}:${e.text}:${e.x},${e.y}`).join("|");
+      if (fingerprint === previous) stable += 1; else stable = 0;
+      if (stable >= 1) return latest;
+      previous = fingerprint;
+      await sleep(180);
+    }
+    return latest || this.snapshot();
+  }
+
+  async tap(target, snapshot) {
+    const snap = snapshot || await this.snapshot();
+    const element = findAndroidElement(snap.elements, target, { hittable: true });
+    if (!element) return { status: "not_found", detail: `could not find ‘${target}’` };
+    const x = Math.round(element.x + element.w / 2);
+    const y = Math.round(element.y + element.h / 2);
+    const r = await this.adb(["shell", "input", "tap", String(x), String(y)]);
+    return r.code === 0 ? { status: "ok", element } : { status: "not_hittable", detail: String(r.stderr || "tap failed") };
+  }
+
+  async type(target, value, snapshot) {
+    const snap = snapshot || await this.snapshot();
+    const element = target ? findAndroidElement(snap.elements, target, { hittable: true }) : snap.elements.find((e) => e.focused);
+    if (!element) return { status: "not_found", detail: `no field ‘${target}’ to type into` };
+    await this.tap(androidElementKey(element), snap);
+    await this.adb(["shell", "input", "keyevent", "KEYCODE_MOVE_END"]);
+    await this.adb(["shell", "input", "keyevent", "--longpress", "KEYCODE_DEL"]);
+    // ADB input uses %s for spaces. Keep it as an argv value so the shell never
+    // interprets credentials or punctuation.
+    const encoded = String(value).replaceAll("%", "%25").replaceAll(" ", "%s");
+    const r = await this.adb(["shell", "input", "text", encoded]);
+    return r.code === 0 ? { status: "ok", element } : { status: "not_hittable", detail: String(r.stderr || "type failed") };
+  }
+
+  async back() { await this.adb(["shell", "input", "keyevent", "KEYCODE_BACK"]); return { status: "ok" }; }
+
+  async swipe(direction = "up") {
+    const points = {
+      up: [540, 1500, 540, 500], down: [540, 500, 540, 1500],
+      left: [900, 1000, 180, 1000], right: [180, 1000, 900, 1000],
+    }[direction.toLowerCase()] || [540, 1500, 540, 500];
+    await this.adb(["shell", "input", "swipe", ...points.map(String), "250"]);
+    return { status: "ok" };
+  }
+
+  async waitFor(target, timeoutMs = 6000) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+      const snap = await this.snapshot();
+      if (snap.screenTitle.toLowerCase() === String(target).toLowerCase() || findAndroidElement(snap.elements, target)) return snap;
+      await sleep(250);
+    }
+    return null;
+  }
+}
+
+export function androidCaptureDir(prefix = "android") {
+  return fs.mkdtempSync(path.join(os.tmpdir(), `tapp-${prefix}-`));
+}