@aarwitz/tapp 0.17.14 → 0.17.16

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.14",
+  "version": "0.17.16",
   "author": {
     "name": "Aaron Horowitz",
     "url": "https://github.com/aarwitz"
@@ -24,7 +24,7 @@
       "command": "npx",
       "args": [
         "-y",
-        "@aarwitz/tapp@0.17.14",
+        "@aarwitz/tapp@0.17.16",
         "mcp"
       ],
       "cwd": "${CLAUDE_PROJECT_DIR}"

package/Harness/OCQAHarnessUITests/ExplorerTests.swift

@@ -231,6 +231,11 @@ class ExplorerTests: XCTestCase {
         for query in queries {
             let element = query[identifier]
             if element.exists && element.isHittable {
+                if !waitForEnabled(element) {
+                    print("OCQA_ACTION:{\"type\":\"tap\",\"identifier\":\"\(identifier)\",\"status\":\"disabled\"}")
+                    Thread.sleep(forTimeInterval: 0.5)
+                    return
+                }
                 element.tap()
                 print("OCQA_ACTION:{\"type\":\"tap\",\"identifier\":\"\(identifier)\"}")
                 Thread.sleep(forTimeInterval: 0.5)
@@ -240,8 +245,12 @@ class ExplorerTests: XCTestCase {
         let predicate = NSPredicate(format: "label == %@", identifier)
         let match = app.descendants(matching: .any).matching(predicate).firstMatch
         if match.exists && match.isHittable {
-            match.tap()
-            print("OCQA_ACTION:{\"type\":\"tap\",\"label\":\"\(identifier)\"}")
+            if !waitForEnabled(match) {
+                print("OCQA_ACTION:{\"type\":\"tap\",\"label\":\"\(identifier)\",\"status\":\"disabled\"}")
+            } else {
+                match.tap()
+                print("OCQA_ACTION:{\"type\":\"tap\",\"label\":\"\(identifier)\"}")
+            }
         } else {
             print("OCQA_ACTION:{\"type\":\"tap\",\"identifier\":\"\(identifier)\",\"status\":\"not_found\"}")
         }
@@ -434,10 +443,27 @@ class ExplorerTests: XCTestCase {
     /// Returns "ok" if tapped, "not_hittable" if the element exists but couldn't be tapped (disabled,
     /// or covered by the keyboard even after dismissing it), or "not_found" if nothing matched. The
     /// distinction tells the caller whether to enter valid input first vs. that the target is absent.
+    /// A disabled control is still `exists` and still `isHittable`, so tapping one
+    /// succeeds and reports a normal action while nothing happens: the step passes and
+    /// the flow carries on against a screen that never advanced. Wait before calling it
+    /// disabled — a button guarded by form validation becomes enabled a moment after the
+    /// last field is filled, and failing on that would be its own kind of wrong answer.
+    private func waitForEnabled(_ element: XCUIElement, timeout: TimeInterval = 3) -> Bool {
+        if element.isEnabled { return true }
+        let deadline = Date().addingTimeInterval(timeout)
+        while Date() < deadline {
+            if element.isEnabled { return true }
+            Thread.sleep(forTimeInterval: 0.15)
+        }
+        return false
+    }
+
     private func sessionTapById(_ identifier: String) -> String {
         var existedButNotHittable = false
+        var existedButDisabled = false
         func tryTap(_ el: XCUIElement) -> Bool {
             guard el.exists else { return false }
+            if !waitForEnabled(el) { existedButDisabled = true; return false }
             if el.isHittable { el.tap(); return true }
             // Often covered by the keyboard (a submit button below filled fields) — dismiss + retry,
             // like Playwright auto-scrolls a target into view.
@@ -472,6 +498,9 @@ class ExplorerTests: XCTestCase {
         // label) — "Password" must reach the secureTextField or a later `type` lands in whatever
         // field still has keyboard focus.
         if let field = resolveFieldByHint(identifier), tryTap(field) { return "ok" }
+        // "disabled" outranks the others: the control was found and refused to act, which
+        // is a different answer from "it is not here" and needs a different fix.
+        if existedButDisabled { return "disabled" }
         return existedButNotHittable ? "not_hittable" : "not_found"
     }
 
@@ -827,8 +856,19 @@ class ExplorerTests: XCTestCase {
 
             switch action {
             case "tap":
-                status = sessionTapById(target) == "ok" ? "pass" : "fail"
-                if status == "fail" { detail = "could not tap ‘\(target)’" }
+                let tapStatus = sessionTapById(target)
+                status = tapStatus == "ok" ? "pass" : "fail"
+                if status == "fail" {
+                    // Name which of the three it was. "Disabled" in particular sends the
+                    // author somewhere completely different from "not found": the control
+                    // is right there, and something upstream in the flow has not satisfied
+                    // whatever guards it.
+                    switch tapStatus {
+                    case "disabled":     detail = "‘\(target)’ is on screen but disabled — an earlier step has not met whatever enables it"
+                    case "not_hittable": detail = "‘\(target)’ exists but could not be reached, even after dismissing the keyboard and scrolling"
+                    default:             detail = "could not find ‘\(target)’ on this screen"
+                    }
+                }
             case "type":
                 status = sessionType(value, id: target.isEmpty ? nil : target) ? "pass" : "fail"
                 if status == "fail" { detail = lastTypeFailure.isEmpty ? "no field ‘\(target)’ to type into" : lastTypeFailure }
@@ -4792,23 +4832,46 @@ class ExplorerTests: XCTestCase {
             } while Date() < deadline
             return focused()
         }
-        for attempt in 0..<3 {
+        // A field further down a form is usually UNDER the keyboard that the previous
+        // field opened, so every tap below lands on a key instead and three attempts
+        // report "never took keyboard focus" for a field that was simply unreachable.
+        // sessionTapById already dismisses and scrolls for taps; typing needs the same
+        // or no form taller than the keyboard can be filled at all.
+        func keyboardCovers(_ el: XCUIElement) -> Bool {
+            let keyboard = app.keyboards.firstMatch
+            guard keyboard.exists else { return false }
+            let f = el.frame, k = keyboard.frame
+            return f.intersects(k) || f.minY >= k.minY
+        }
+
+        for attempt in 0..<5 {
             switch attempt {
             case 0:
                 if element.isHittable { element.tap() } else { element.coordinate(withNormalizedOffset: CGVector(dx: 0.5, dy: 0.5)).tap() }
             case 1:
                 element.coordinate(withNormalizedOffset: CGVector(dx: 0.5, dy: 0.5)).tap()
-            default:
+            case 2:
                 // Frame may be stale by a few rows: tap just inside its top edge, which stays
                 // within the visible control when content shifted up.
                 element.coordinate(withNormalizedOffset: CGVector(dx: 0.35, dy: 0.2)).tap()
+            case 3:
+                // Get the keyboard out of the way and try where the field now sits.
+                dismissKeyboardIfPresent()
+                waitForAnimationsToSettle()
+                if element.isHittable { element.tap() } else { element.coordinate(withNormalizedOffset: CGVector(dx: 0.5, dy: 0.5)).tap() }
+            default:
+                // Still out of reach: bring it up the screen, then tap.
+                dismissKeyboardIfPresent()
+                app.swipeUp()
+                Thread.sleep(forTimeInterval: 0.25)
+                if element.isHittable { element.tap() } else { element.coordinate(withNormalizedOffset: CGVector(dx: 0.5, dy: 0.5)).tap() }
             }
             if settleUntilFocused() {
                 if attempt > 0 { print("OCQA_STATE:type_focus_recovered attempt=\(attempt + 1)") }
                 return true
             }
             let f = element.frame
-            print("OCQA_STATE:type_focus_miss attempt=\(attempt + 1) frame=\(Int(f.minX)),\(Int(f.minY)),\(Int(f.width))x\(Int(f.height)) keyboard=\(app.keyboards.count) focusedElsewhere=\(focusedField().map { fieldDesc($0) } ?? "none")")
+            print("OCQA_STATE:type_focus_miss attempt=\(attempt + 1) frame=\(Int(f.minX)),\(Int(f.minY)),\(Int(f.width))x\(Int(f.height)) keyboard=\(app.keyboards.count) covered=\(keyboardCovers(element)) focusedElsewhere=\(focusedField().map { fieldDesc($0) } ?? "none")")
         }
         return false
     }
@@ -4821,7 +4884,7 @@ class ExplorerTests: XCTestCase {
         lastTypeFailure = ""
         guard focusForTyping(element) else {
             let f = element.frame
-            lastTypeFailure = "‘\(fieldDesc(element))’ was found (frame \(Int(f.minX)),\(Int(f.minY)) \(Int(f.width))×\(Int(f.height))) but never took keyboard focus after 3 taps"
+            lastTypeFailure = "‘\(fieldDesc(element))’ was found (frame \(Int(f.minX)),\(Int(f.minY)) \(Int(f.width))×\(Int(f.height))) but never took keyboard focus, including after dismissing the keyboard and scrolling it into view"
                 + (app.keyboards.count == 0 ? " — no keyboard appeared" : "")
                 + (focusedField().map { " — focus is on ‘\(fieldDesc($0))’" } ?? "")
             print("OCQA_STATE:type_focus_failed detail=\(escapeJSON(lastTypeFailure))")

package/mcp-server/src/index.js

@@ -471,10 +471,26 @@ export async function prepareAndroidInteractiveTarget({ projectDir = process.cwd
   return { ...built, appId, selectedTarget:selected };
 }
 
-export async function installAppOnBootedSim(appPath, { cleanInstall = true } = {}) {
+// Said before a build overwrites whatever is on the simulator. The clean install
+// below wipes the old app's data with it, so a build someone deliberately
+// configured — pointed at a local server, a staging key, a test account —
+// disappears without being mentioned. Naming it is the difference between "my run
+// is slow" and "my run is now testing something else entirely". Passing a bundle
+// id instead of a project path uses what is installed and never builds.
+export function replacingInstalledBuildNotice(bundleId) {
+  const id = String(bundleId || "").trim();
+  if (!id) return "";
+  return `Replacing the installed build of ${id} (its data is wiped too). To use what is already installed instead of building, pass the bundle id: ${id}`;
+}
+
+export async function installAppOnBootedSim(appPath, { cleanInstall = true, onStatus = () => {} } = {}) {
   const bid = await runCommand("/usr/libexec/PlistBuddy", ["-c", "Print CFBundleIdentifier", path.join(appPath, "Info.plist")], { timeoutMs: 30_000 });
   const bundleId = (bid.stdout || "").trim();
   if (!bundleId) return { error: `Could not read CFBundleIdentifier from ${appPath}/Info.plist — is this a simulator .app build?` };
+  if (cleanInstall) {
+    const existing = await runCommand("xcrun", ["simctl", "get_app_container", "booted", bundleId, "app"], { timeoutMs: 15_000 });
+    if (existing.code === 0 && (existing.stdout || "").trim()) onStatus(replacingInstalledBuildNotice(bundleId));
+  }
   if (cleanInstall) {
     // Clean install: stale keychain items from a previous install leave apps half-signed-in
     // (Firebase Auth's "error accessing the keychain") — uninstall first for a fresh state.
@@ -496,7 +512,7 @@ export async function resolveAppTarget(input, { cwd = process.cwd(), onStatus =
     const sim = await ensureBootedSim({ autoBoot: true });
     if (sim.error) return { error: sim.error };
     onStatus(`Installing ${path.basename(appPath)}…`);
-    const inst = await installAppOnBootedSim(appPath);
+    const inst = await installAppOnBootedSim(appPath, { onStatus });
     if (inst.error) return inst;
     return {
       bundleId: inst.bundleId,
@@ -522,7 +538,7 @@ export async function resolveAppTarget(input, { cwd = process.cwd(), onStatus =
     const built = await buildAppForSim({ container, scheme, configuration });
     if (built.error) return built;
     onStatus(`Built ${path.basename(built.appPath)} (scheme ${built.scheme}) — installing…`);
-    const inst = await installAppOnBootedSim(built.appPath);
+    const inst = await installAppOnBootedSim(built.appPath, { onStatus });
     if (inst.error) return inst;
     return {
       bundleId: inst.bundleId,

package/mcp-server/src/web-explorer.js

@@ -139,6 +139,11 @@ function cssAttrEscape(value) {
 async function installWebListenerTracking(context) {
   await context.addInitScript(() => {
     const key = Symbol.for("tapp.clickListeners");
+    // Delegated handlers live on document/window, not on the control, so an
+    // element-only record says "nothing is listening" for a page where every
+    // button works. Keep their source text: it is the only way to tell which
+    // controls such a handler actually claims.
+    const delegatedKey = Symbol.for("tapp.delegatedClickHandlers");
     const add = EventTarget.prototype.addEventListener;
     const remove = EventTarget.prototype.removeEventListener;
     EventTarget.prototype.addEventListener = function tappTrackedAdd(type, listener, options) {
@@ -146,6 +151,11 @@ async function installWebListenerTracking(context) {
         if (!this[key]) Object.defineProperty(this, key, { value: new Set(), configurable: true });
         this[key].add(listener);
       }
+      if (type === "click" && listener && (this === document || this === window)) {
+        const target = this === window ? window : document;
+        if (!target[delegatedKey]) Object.defineProperty(target, delegatedKey, { value: new Set(), configurable: true });
+        try { target[delegatedKey].add(String(listener).slice(0, 4000)); } catch { /* exotic handler */ }
+      }
       return add.call(this, type, listener, options);
     };
     EventTarget.prototype.removeEventListener = function tappTrackedRemove(type, listener, options) {
@@ -1227,6 +1237,56 @@ export async function auditWebPage({ url, timeoutMs = NAV_TIMEOUT_MS, device = "
       };
       const name = (el) => (el.getAttribute("aria-label") || el.textContent || el.getAttribute("value") || "").replace(/\s+/g, " ").trim().slice(0, 80);
       const selectorFor = (el) => el.id ? `#${el.id}` : el.getAttribute("data-testid") ? `[data-testid="${el.getAttribute("data-testid")}"]` : el.tagName.toLowerCase();
+      // Some controls are wired in CSS, not JavaScript: a menu that opens while
+      // its trigger is hovered or focused has no listener to find, and calling
+      // it dead is wrong. Collect the selectors that some rule reacts to — the
+      // trigger side of any `X:hover Y` / `X:focus-within Y` rule whose
+      // declarations change whether Y can be seen. A rule that only restyles
+      // the trigger itself (`button:hover { background: … }`) is not behaviour
+      // and is ignored, which is why the descendant part must be present.
+      const REVEALS = /(^|;)\s*(display|visibility|opacity|height|max-height|transform|pointer-events|clip-path)\s*:/i;
+      const revealTriggers = [];
+      const collectTriggers = (rules) => {
+        for (const rule of rules || []) {
+          // A plain style rule also exposes .cssRules now that CSS nesting is
+          // supported — an empty list, which is truthy. Recursing on that and
+          // skipping the rule would walk straight past every selector there is.
+          if (rule.cssRules && rule.cssRules.length) collectTriggers(rule.cssRules);
+          const selector = rule.selectorText;
+          if (!selector || !REVEALS.test(rule.style?.cssText || "")) continue;
+          for (const part of selector.split(",")) {
+            const match = part.match(/^(.*?):(?:hover|focus-within|focus-visible|focus)\b(.+)$/);
+            if (!match) continue;
+            const trigger = match[1].trim();
+            if (trigger && match[2].trim()) revealTriggers.push(trigger);
+          }
+        }
+      };
+      for (const sheet of document.styleSheets) {
+        try { collectTriggers(sheet.cssRules); } catch { /* cross-origin sheet */ }
+      }
+      const opensSomethingOnHoverOrFocus = (el) => revealTriggers.some((trigger) => {
+        try { return el.matches(trigger) || Boolean(el.closest(trigger)); } catch { return false; }
+      });
+
+      // What a delegated handler on document/window claims. The dominant idiom is
+      // `e.target.closest(SELECTOR)` / `.matches(SELECTOR)`, so pull those
+      // selectors out and test controls against them. A handler we cannot read
+      // this way (an outside-click closer, say) claims nothing and is ignored,
+      // rather than excusing every unwired control on the page.
+      const delegatedSelectors = [];
+      for (const source of [
+        ...(document[Symbol.for("tapp.delegatedClickHandlers")] || []),
+        ...(window[Symbol.for("tapp.delegatedClickHandlers")] || []),
+      ]) {
+        for (const m of String(source).matchAll(/\.(?:closest|matches)\(\s*["'`]([^"'`]+)["'`]/g)) {
+          delegatedSelectors.push(m[1]);
+        }
+      }
+      const claimedByDelegate = (el) => delegatedSelectors.some((selector) => {
+        try { return el.matches(selector) || Boolean(el.closest(selector)); } catch { return false; }
+      });
+
       const dead = [];
       for (const el of document.querySelectorAll("a[href], button, [role=button], [aria-controls]")) {
         if (!visible(el)) continue;
@@ -1255,6 +1315,8 @@ export async function auditWebPage({ url, timeoutMs = NAV_TIMEOUT_MS, device = "
         }
         if (!wired && el.matches("button[type=submit], input[type=submit]") && el.closest("form")) wired = true;
         if (!wired && el.closest("label")) wired = true; // a label drives its own control
+        if (!wired && opensSomethingOnHoverOrFocus(el)) wired = true;
+        if (!wired && claimedByDelegate(el)) wired = true;
         if (!wired) dead.push({ kind: "unwired_control", label, selector: selectorFor(el) });
       }
       return { dead, controlCount: document.querySelectorAll("a[href], button, [role=button]").length, title: document.title };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aarwitz/tapp",
-  "version": "0.17.14",
+  "version": "0.17.16",
   "mcpName": "io.github.aarwitz/tapp",
   "description": "Let coding agents verify UI changes on real iOS, Android, and web surfaces, then enforce reviewed proof in deterministic CI.",
   "license": "MIT",