@aarwitz/tapp 0.17.0 → 0.17.1

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "tapp",
   "description": "Give Claude hands and eyes on iOS, Android, and web apps, with exploration, replayable flows, evidence, and deterministic CI gates.",
-  "version": "0.17.0",
+  "version": "0.17.1",
   "author": {
     "name": "Aaron Horowitz",
     "url": "https://github.com/aarwitz"
@@ -24,7 +24,7 @@
       "command": "npx",
       "args": [
         "-y",
-        "@aarwitz/tapp@0.17.0",
+        "@aarwitz/tapp@0.17.1",
         "mcp"
       ],
       "cwd": "${CLAUDE_PROJECT_DIR}"

package/AGENTS.md

@@ -14,6 +14,7 @@ bundle id, or (web) an http(s) URL. You never need to know a bundle id up front.
 
 ```bash
 npx -y @aarwitz/tapp@latest explore [target]     # autonomous exploration → findings + evidence (observation, not a gate; ≈ tapp_explore)
+npx -y @aarwitz/tapp@latest focus "SCREEN OR CONTROL" [target] # source-locate + shortest observed route + screenshot
 npx -y @aarwitz/tapp@latest explore https://your-app.example --watch  # web: visibly follow the same exploration
 npx -y @aarwitz/tapp@latest open [target]   # launch + screen summary + screenshot saved to a file (≈ tapp_open_app)
 npx -y @aarwitz/tapp@latest tree [target]   # accessibility tree, --json for every element (≈ tapp_ui_tree)
@@ -60,6 +61,7 @@ installs, returns the bundle id) → `tapp_explore {appBundleId}`.
 | The user wants… | Use | NOT |
 |---|---|---|
 | "Show me / screenshot a screen" | `tapp_open_app` (launch + screenshot + tree, ~15s) | `tapp_explore` (a full multi-minute exploration) |
+| "Find/reach this named screen or control" | `tapp_session_start` with `focus`, or `tapp_focus`; plain CLI: `tapp focus` | screenshot-by-screenshot wandering |
 | "Tap through / drive / fill a form / log in" | `tapp_session_start` → `session_act` loop | repeated `open_app` calls (cold relaunch each time) |
 | "Is my app broken? Find bugs" | `tapp_explore` — `appBundleId` for iOS, `androidAppId` for Android, `url` for owned web apps; returns an observation (findings + evidence), not a ship verdict — gate a merge with the CI gate (`tapp ci` CLI / the GitHub Action) + a contract | a manual session (exploration is autonomous) |
 | "Make this flow a repeatable test" | drive it in a session, then `tapp_flow_save`; replay with `tapp_flow_run` | re-driving it by hand every time |
@@ -67,8 +69,15 @@ installs, returns the bundle id) → `tapp_explore {appBundleId}`.
 
 ## Session driving (the Playwright loop)
 
+After an initial grounding exploration, use the source-connected fast path for any named
+destination. Tapp searches the repository, matches the requested surface to `.tapp/ui-map.json`, and executes only the shortest
+runtime-observed route. Source tells Tapp where intent lives; observed UI evidence authorizes taps.
+If it returns source evidence without a route, inspect the cited file/navigation source—do not
+wander blindly or invent a route. URL-only targets correctly have no source advantage.
+
 ```
-tapp_session_start { appBundleId: "com.acme.app" }     → fresh launch + initial tree
+tapp_session_start { appBundleId: "com.acme.app", focus: "Save storefront settings visible above keyboard", projectDir: "." }
+tapp_focus         { query: "Save storefront settings visible above keyboard" } → one-call shortest observed route
 tapp_session_act   { action: "login", email: "qa@x.com", password: "…" } → atomic fill + submit + verify
 tapp_session_act   { action: "tap",  id: "Email" }      → tap by a11y id OR visible label
 tapp_session_act   { action: "type", text: "qa@x.com" } → types into the focused field

package/Harness/OCQAHarnessUITests/ExplorerTests.swift

@@ -82,6 +82,31 @@ class ExplorerTests: XCTestCase {
         return fallback
     }
 
+    /// Opens the visual-evidence boundary only after the target app is foregrounded and its first
+    /// UI has settled. The host starts simulator recording (and clients may reveal a live preview)
+    /// at this point, then acknowledges it. The wait is deliberately bounded: video/preview
+    /// failure must never prevent the actual exploration from running.
+    private func signalSettledVisualReady() {
+        let readyPath = resolve("OCQA_VISUAL_READY_PATH")
+        guard !readyPath.isEmpty else { return }
+        let readyURL = URL(fileURLWithPath: readyPath)
+        try? FileManager.default.createDirectory(at: readyURL.deletingLastPathComponent(), withIntermediateDirectories: true)
+        try? Data("ready\n".utf8).write(to: readyURL, options: .atomic)
+        print("OCQA_STATE:visual_ready")
+
+        let startedPath = resolve("OCQA_RECORDING_STARTED_PATH")
+        guard !startedPath.isEmpty else { return }
+        let deadline = Date().addingTimeInterval(5.0)
+        while Date() < deadline && !FileManager.default.fileExists(atPath: startedPath) {
+            Thread.sleep(forTimeInterval: 0.05)
+        }
+        if FileManager.default.fileExists(atPath: startedPath) {
+            print("OCQA_STATE:visual_capture_started")
+        } else {
+            print("OCQA_STATE:visual_capture_ack_timeout")
+        }
+    }
+
     private func loadConfig() {
         // OCQA_CONFIG_PATH (forwarded from the host via TEST_RUNNER_OCQA_CONFIG_PATH) is
         // authoritative and per-run — checked FIRST so each device reads its own config and
@@ -585,14 +610,34 @@ class ExplorerTests: XCTestCase {
     /// the password it just typed.
     private func sessionLogin(email: String, password: String) -> (status: String, detail: String) {
         waitForUIStability(timeout: 2.0)
-        let textFields = app.textFields.allElementsBoundByIndex.filter { $0.exists && $0.frame.width > 0 }
-        let secureFields = app.secureTextFields.allElementsBoundByIndex.filter { $0.exists && $0.frame.width > 0 }
-        let emailField = textFields.first { f in
-            let hint = (f.identifier + " " + (f.placeholderValue ?? "") + " " + f.label).lowercased()
-            return hint.contains("email") || hint.contains("e-mail") || hint.contains("user")
-        } ?? (secureFields.isEmpty ? nil : textFields.first)
+        // A recorded Flow invokes login immediately after a cold launch, while a human-driven
+        // session naturally invokes it after inspecting the first tree. Poll the SAME finder for
+        // a bounded interval so those two entry paths behave identically when login fields appear
+        // after an asynchronous launch transition.
+        var textFields: [XCUIElement] = []
+        var secureFields: [XCUIElement] = []
+        var emailField: XCUIElement?
+        var passwordField: XCUIElement?
+        let fieldsDeadline = Date().addingTimeInterval(8.0)
+        repeat {
+            textFields = app.textFields.allElementsBoundByIndex.filter { $0.exists && $0.frame.width > 0 }
+            secureFields = app.secureTextFields.allElementsBoundByIndex.filter { $0.exists && $0.frame.width > 0 }
+            let plainPasswordIndex = textFields.firstIndex { f in
+                let hint = (f.identifier + " " + (f.placeholderValue ?? "") + " " + f.label).lowercased()
+                return hint.contains("password") || hint.contains("passcode")
+            }
+            passwordField = secureFields.first ?? plainPasswordIndex.map { textFields[$0] }
+            emailField = textFields.first { f in
+                let hint = (f.identifier + " " + (f.placeholderValue ?? "") + " " + f.label).lowercased()
+                return hint.contains("email") || hint.contains("e-mail") || hint.contains("user")
+            } ?? textFields.enumerated().first(where: { index, _ in
+                passwordField != nil && (plainPasswordIndex.map { index != $0 } ?? true)
+            })?.element
+            if emailField != nil && passwordField != nil { break }
+            Thread.sleep(forTimeInterval: 0.25)
+        } while Date() < fieldsDeadline
         guard let emailF = emailField else { return ("no_login_form", "no email/username field visible") }
-        guard let passF = secureFields.first else { return ("no_login_form", "no password (secure) field visible") }
+        guard let passF = passwordField else { return ("no_login_form", "no password field visible") }
 
         replaceText(on: emailF, with: email)
         replaceText(on: passF, with: password)
@@ -1031,6 +1076,8 @@ class ExplorerTests: XCTestCase {
         _ = app.descendants(matching: .any).firstMatch.waitForExistence(timeout: 3)
         _ = waitForUIStability(timeout: 2.0)
 
+        signalSettledVisualReady()
+
         print("OCQA_STATE:exploration_started max_actions=\(maxActions)")
 
         let testEmail = resolve("OCQA_TEST_EMAIL")

package/README.md

@@ -9,9 +9,9 @@
 [![Install in Cursor](https://img.shields.io/badge/Cursor-Install_MCP-000000)](cursor://anysphere.cursor-deeplink/mcp/install?name=tapp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBhYXJ3aXR6L3RhcHBAbGF0ZXN0IiwibWNwIl19)
 [![VS Code MCP](https://img.shields.io/badge/VS_Code-Install_MCP-0098FF)](https://insiders.vscode.dev/redirect/mcp/install?name=tapp&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40aarwitz%2Ftapp%40latest%22%2C%22mcp%22%5D%7D)
 
-**Tapp gives coding agents hands and eyes on real iOS, Android, and web apps.** It can inspect and
-drive screens, explore for technical failures, save journeys as deterministic tests, and gate
-reviewed behavior in CI.
+**Tapp lets coding agents verify UI changes on real iOS, Android, and web surfaces, then turns
+reviewed proof into deterministic CI checks.** It can inspect and drive screens, explore for
+technical failures, and save important journeys as replayable tests.
 
 Exploration reports findings, coverage, evidence, and limits. Only the repository-connected gate
 returns `pass`, `fail`, or `inconclusive`. Tapp does not turn an autonomous crawl into a subjective
@@ -45,10 +45,11 @@ npx -y skills add aarwitz/tapp --skill tapp
 ```
 
 This installs the open Agent Skills workflow into the current project and lets the agent run the npm
-CLI directly; no MCP server, plugin, account, API key, global Tapp install, or pasted prompt block is
-required. Add `-g` for a user-wide install, or `--agent claude-code`, `--agent codex`, and similar
-selectors to constrain the clients. Start or restart the agent from the application repository and
-use the short prompt above.
+CLI directly. Inspecting, focused evidence, autonomous exploration, deterministic replay, and gating
+need no MCP server, plugin, account, API key, global Tapp install, or pasted prompt block. Add `-g`
+for a user-wide install, or `--agent claude-code`, `--agent codex`, and similar selectors to constrain
+the clients. Start or restart the agent from the application repository and use the short prompt
+above.
 
 **Claude Code — optional enhanced skill and MCP tools:**
 
@@ -57,9 +58,10 @@ claude plugin marketplace add aarwitz/tapp
 claude plugin install tapp@tapp
 ```
 
-The plugin bundles the same `tapp` Agent Skill with the matching npm-backed MCP server. Use it when
-you want inline screenshot tool results and a persistent interactive tap/read/type session; it is
-not required for the core skill-to-CLI workflow.
+The plugin bundles the same `tapp` Agent Skill with the matching npm-backed MCP server. Add it when
+you want inline screenshot results or when the agent must interactively tap, type, and record an
+arbitrary multi-step journey in one persistent session. It is not required for the core
+skill-to-CLI workflow.
 
 **No agent integration:** run the npm package directly from an app repository in one line:
 
@@ -75,7 +77,7 @@ Android and web remain available through the skill's CLI/MCP workflow.
 ```
 you:    "Add a logout button to the settings screen"
 agent:  *writes the Swift*
-agent:  *tapp: builds, opens the app, navigates to Settings, screenshots it*
+agent:  *tapp: finds Settings in source, follows its previously observed route, screenshots it*
 agent:  "Done — and here it is working on the simulator: [screenshot]"
 ```
 
@@ -84,13 +86,19 @@ agent:  "Done — and here it is working on the simulator: [screenshot]"
 Requirements: **Node ≥ 18**. iOS needs **macOS + Xcode**; Android needs `adb` plus a connected
 emulator/device; web needs Playwright + Chromium.
 
-From the app repository, let the agent see the current screen and then explore it:
+From the app repository, ground Tapp once, then use the smallest operation for later checks:
 
 ```bash
-npx -y @aarwitz/tapp@latest open   # builds/launches as needed; prints a screenshot path + screen summary
-npx -y @aarwitz/tapp@latest explore     # explores the real app; prints findings + evidence (an observation, not a gate)
+npx -y @aarwitz/tapp@latest init . --explore # first run: detect/build, explore, and ground .tapp/ui-map.json
+npx -y @aarwitz/tapp@latest open            # one current screen + screenshot
+npx -y @aarwitz/tapp@latest focus "Save storefront settings visible above keyboard" # source + observed-route fast path
+npx -y @aarwitz/tapp@latest explore         # later broad exploration (observation, not a gate)
 ```
 
+Source tells `focus` where the requested UI likely lives; only a route already observed in
+`.tapp/ui-map.json` authorizes navigation. If a fresh repository has no such route yet, Tapp returns
+the source evidence instead of guessing through the app.
+
 Claude Code can read the saved image with its file-reading tool; Codex can open it with
 `view_image`. The agent should report what the screenshot proves, relay the exploration findings
 as-is (an observation, not a merge decision — `tapp ci` gates that), and link the HTML evidence
@@ -123,6 +131,9 @@ npx -y @aarwitz/tapp@latest baseline create . --platform web
 npx -y @aarwitz/tapp@latest ci install .
 ```
 
+Actor setup refuses to overwrite an existing actor. Repeat `actor set` with `--replace` only when
+you intend to replace that actor's reviewed role, session, provisioning, or credential bindings.
+
 In a repository containing multiple apps (for example, iOS plus web),
 `tapp init . --explore` without an explicit target does not guess from detection order—even when a
 prior choice is recorded. A human terminal gets a numbered
@@ -326,7 +337,7 @@ jobs:
     timeout-minutes: 45
     steps:
       - uses: actions/checkout@v4
-      - uses: aarwitz/tapp@main # pin to the newest release tag for production
+      - uses: aarwitz/tapp@v0.17.1 # or pin the reviewed release commit SHA
         with:
           project: MyApp.xcodeproj # or MyApp.xcworkspace
           scheme: MyApp
@@ -376,7 +387,7 @@ Android CI runs on Linux with an emulator/device already connected. The Action c
 or accept a prebuilt one:
 
 ```yaml
-- uses: aarwitz/tapp@main
+- uses: aarwitz/tapp@v0.17.1 # or pin the reviewed release commit SHA
   with:
     platform: android
     android-app-id: com.acme.app

package/bin/tapp.js

@@ -254,6 +254,7 @@ async function resolveTargetOrExit(engine, input) {
 function safeCommandUsage(verb) {
   const usage = {
     explore: "tapp explore [target] [--platform ios|android|web] [--actions N] [--timeout SEC] [--email VALUE] [--password VALUE] [--baseline FILE] [--json FILE]\n  Web: [--watch] opens Tapp's controlled browser and shows its actions\n  iOS launch configuration: [--launch-arg VALUE ...] [--launch-env '{\"KEY\":\"VALUE\"}']\n  Android: [--app-id ID] [--apk FILE] [--serial ID] [--keep-data]",
+    focus: "tapp focus \"SCREEN OR CONTROL\" [target] [--platform ios|android|web] [--project-dir REPO] [--map FILE] [--out FILE]",
     init: "tapp init [repo] [--explore] [--refresh] [--platform PLATFORM] [--target NAME] [--url URL] [--watch] [--dry-run]",
     open: "tapp open [target] [--platform ios|android|web] [--out FILE] [--tap TEXT] [--wait-for TEXT]",
     tree: "tapp tree [target] [--platform ios|android|web] [--json] [--tap TEXT] [--wait-for TEXT]",
@@ -288,6 +289,16 @@ if (["--help", "-h"].includes(command)) {
   command = "help";
   rest = [];
 }
+const knownCommands = new Set([
+  "help", "version", "--version", "-v", "mcp", "init", "focus", "explore", "qa", "open",
+  "tree", "shot", "screenshot", "apps", "build", "flow", "task", "contract", "scenario", "map",
+  "pr", "plan", "baseline", "ci", "actor", "app", "studio", "report", "doctor", "install",
+]);
+if (!knownCommands.has(command)) {
+  console.error(`❌ Unknown command: ${command}`);
+  console.error("Run `npx -y @aarwitz/tapp@latest --help` for the command reference.");
+  process.exit(2);
+}
 const safeHelpRequested = (rest.includes("--help") || rest.includes("-h"))
   && !["help", "version", "--version", "-v"].includes(command)
   && (command !== "ci" || rest[0] === "install");
@@ -529,6 +540,63 @@ switch (command) {
   // ---- Zero-config verbs: the same engine the MCP tools use (exported by index.js),
   // invokable by any agent or human with no server setup at all.
 
+  case "focus": {
+    const { flags, positionals } = parseVerbArgs(rest);
+    const query = positionals[0] || "";
+    if (!query) {
+      console.error('usage: tapp focus "SCREEN OR CONTROL" [target] [--platform ios|android|web] [--project-dir REPO] [--map FILE] [--out FILE]');
+      process.exit(2);
+    }
+    let projectDir;
+    try { projectDir = fs.realpathSync(path.resolve(typeof flags["project-dir"] === "string" ? flags["project-dir"] : process.cwd())); }
+    catch { console.error("❌ --project-dir must be an existing repository directory"); process.exit(2); }
+    const target = positionals[1] || (typeof flags.url === "string" ? flags.url : "");
+    const platform = requestedPlatform(flags, target);
+    if (!["ios", "android", "web"].includes(platform)) { console.error("❌ --platform must be ios|android|web"); process.exit(2); }
+    const engine = await engineImport();
+    let started = null;
+    try {
+      if (platform === "ios") {
+        requireMacFor("iOS focused navigation");
+        const sim = await engine.ensureBootedSim({ autoBoot:true });
+        if (sim.error) throw new Error(sim.error);
+        const bundleId = await resolveTargetOrExit(engine, target || projectDir);
+        const launch = iosLaunchOptions(flags, rest);
+        started = await engine.startIosInteractiveSession(bundleId, engine.explorationEnvFromArgs({ testEmail:flags.email, testPassword:flags.password, ...launch }));
+      } else if (platform === "android") {
+        const android = androidTarget(flags, target);
+        started = await engine.startAndroidInteractiveSession(android.appId, { serial:android.serial, apkPath:android.apkPath, clearData:flags["keep-data"] !== true });
+      } else {
+        if (!/^https?:\/\//i.test(target)) { console.error("❌ Web focus needs an http(s) target URL"); process.exit(2); }
+        started = await engine.startWebInteractiveSession(target);
+      }
+      if (started.error) throw new Error(started.error);
+      const focused = await engine.focusInteractiveSession({ projectDir, query, platform, mapPath:typeof flags.map === "string" ? flags.map : "" });
+      const { focusedTargetSummary } = await import(path.join(packageRoot, "mcp-server", "src", "focused-navigation.js"));
+      console.log(focusedTargetSummary(focused));
+      if (focused.execution?.status === "reached") {
+        console.log(`\n⚡ Reached in ${(focused.execution.steps || []).length} route action(s).\n`);
+        console.log(engine.formatScreen(focused.screenTitle, focused.elements));
+        const frame = await engine.captureInteractiveSessionFrame(Number(flags.width) || 900);
+        if (!frame.error) {
+          const out = saveShot(frame, typeof flags.out === "string" ? path.resolve(flags.out) : null, `focus-${Date.now()}.${frame.mimeType === "image/png" ? "png" : "jpg"}`);
+          console.log(`\n📸 Screenshot: ${out}`);
+        }
+      } else if (focused.execution?.status === "failed") {
+        console.error(`\n❌ Observed route stopped: ${focused.execution.reason}`);
+        process.exitCode = 1;
+      } else {
+        console.error("\nℹ️  Tapp located the source but did not drive an unobserved route. Ground the UI Map with `npx -y @aarwitz/tapp@latest init . --explore`.");
+      }
+    } catch (error) {
+      console.error(`❌ ${error.message || String(error)}`);
+      process.exitCode = 1;
+    } finally {
+      if (started) await engine.endInteractiveSession();
+    }
+    break;
+  }
+
   case "explore":
   case "qa": {
     // `explore` is the canonical verb (ADR-0005: exploration observes; the gate judges). `qa` is a
@@ -1003,7 +1071,9 @@ switch (command) {
       invocation = ["bash", [path.join(packageRoot, "scripts", "run-flow.sh"), absolute, typeof flags["bundle-id"] === "string" ? flags["bundle-id"] : flow.app || ""]];
     }
     const result = spawnSync(invocation[0], invocation[1], { stdio: "inherit", env });
-    console.log(`\nEvidence: ${evidenceDir}`);
+    const evidenceWritten = fs.existsSync(evidenceDir) && fs.readdirSync(evidenceDir).length > 0;
+    if (evidenceWritten) console.log(`\nEvidence: ${evidenceDir}`);
+    else console.error("\n⚠️ Evidence unavailable — the platform runner did not write any artifacts for this Flow run.");
     process.exit(result.status ?? 1);
   }
 
@@ -1620,6 +1690,7 @@ Core — inspect, explore, gate (no Tapp account or server required):
   tapp explore [target]    Autonomous exploration → findings + evidence (an observation, NOT a
                            release decision — run 'npx -y @aarwitz/tapp@latest ci' to gate a merge)
                            (web: --watch · all: --platform ios|android|web · --actions N)
+  tapp focus "goal" [target] Source-locate a named screen/control and take the shortest observed route
   tapp contract run FILE   Replay a business-level release contract — the guarantees that must hold
   tapp ci ...              Merge-blocking release gate — explore + suites + baseline → pass/fail/inconclusive
                            (see: tapp ci --help)

package/docs/scenarios.md

@@ -74,7 +74,7 @@ tapp ci --platform web --url http://127.0.0.1:4180 \
 GitHub Action:
 
 ```yaml
-- uses: aarwitz/tapp@main
+- uses: aarwitz/tapp@v0.17.1 # or pin the reviewed release commit SHA
   with:
     platform: web
     url: http://127.0.0.1:4180

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

@@ -305,14 +305,25 @@ export class AndroidDriver {
     return r.stdout;
   }
 
-  async settle(timeoutMs = 2200) {
+  async settle(timeoutMs = 2200, previousSnapshot = null) {
     const deadline = Date.now() + timeoutMs;
+    const fingerprintOf = (snapshot) => (snapshot?.elements || [])
+      .map((e) => `${androidElementKey(e)}:${e.text}:${e.x},${e.y}`).join("|");
+    const previousScreen = String(previousSnapshot?.screenTitle || "");
+    const previousFingerprint = fingerprintOf(previousSnapshot);
     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("|");
+      const fingerprint = fingerprintOf(latest);
+      // UIAutomator's dump command itself waits for the UI to become idle. If its first complete
+      // snapshot proves that the requested interaction changed the screen, a second identical
+      // dump adds roughly two seconds without adding evidence. Preserve the two-snapshot stability
+      // requirement when nothing changed (including delayed navigation and no-op controls).
+      if (previousSnapshot && fingerprint && (
+        String(latest.screenTitle || "") !== previousScreen || fingerprint !== previousFingerprint
+      )) return latest;
       if (fingerprint === previous) stable += 1; else stable = 0;
       if (stable >= 1) return latest;
       previous = fingerprint;