@aarwitz/tapp 0.17.13 → 0.17.14

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

package/AGENTS.md

@@ -133,6 +133,11 @@ advisory). Report the finding counts and coverage; do not invent a scalar or a s
   (e.g. `["--uitesting"]` if the app has a test bypass), and/or `appLaunchEnv` (e.g. a staging
   backend URL). If the result shows `inputFieldsEncountered` and you have no credentials, **ask
   the user** for them rather than re-running blind.
+- `tapp audit <url>` is the read-only pass: it renders the page and reads the tree but never
+  clicks, so it is the one analysis safe to point at production. It finds controls that were
+  never alive — dead in-page anchors, `aria-controls` naming nothing, placeholder links, buttons
+  with no handler/form/link — which Flows structurally cannot find, because nobody writes a test
+  for a button they believe does nothing. Exit 1 when it finds any.
 - Credential surfaces are catalogue-only without credentials, on every platform: with no
   `testEmail`/`testPassword` supplied, exploration records a login/signup form's fields but does
   not type into them, submit them, or open recovery/third-party-auth flows — a bare-app run may

package/Harness/OCQAHarnessUITests/ExplorerTests.swift

@@ -1389,6 +1389,10 @@ class ExplorerTests: XCTestCase {
         // say "navigation-trap" or "frontier-drained" instead of blessing a 15/20 run "completed".
         var explorationStopCause = "action-budget"
         var leftAppObservations = 0
+        // A loop the EXPLORER created by going back is its own traversal strategy, not an app
+        // defect (field issue #9: "Personal Info ↔ back" filed as a finding). Remember when we
+        // last navigated backwards so the loop detector can tell the two apart.
+        var lastExplorerBackStep = -99
         while actionCount < maxActions {
             // Subtract time spent paused for interactive input so human typing never eats the budget.
             if Date().timeIntervalSince(startTime) - totalWaitSeconds > timeoutSeconds {
@@ -1889,10 +1893,11 @@ class ExplorerTests: XCTestCase {
                     recent[recent.count - 3] == recent[recent.count - 6] &&
                     Set(recent.suffix(3)).count == 3 &&
                     Set(recentScreenTitles.suffix(3)).count == 3
-                if (hasLoop2 || hasLoop3) && !(authSucceeded && detectedInputs.contains { $0.secure }) {
+                let period = hasLoop2 ? 2 : 3
+                let explorerDroveTheLoop = actionCount - lastExplorerBackStep <= period * 2
+                if (hasLoop2 || hasLoop3) && !explorerDroveTheLoop && !(authSucceeded && detectedInputs.contains { $0.secure }) {
                     let loopKey = "nav_loop:\(titleStr)"
                     if actionCounts[loopKey] == nil {
-                        let period = hasLoop2 ? 2 : 3
                         issues.append((type: "navigation_loop", severity: "low", title: "Navigation loop detected (period \(period))", desc: "Exploration is cycling between the same \(period) screens"))
                         print("OCQA_ISSUE:{\"type\":\"navigation_loop\",\"severity\":\"low\",\"title\":\"Navigation loop\",\"screen\":\"\(escapedTitle)\",\"period\":\(period),\"step\":\(actionCount)}")
                         actionCounts[loopKey] = 1
@@ -1947,6 +1952,7 @@ class ExplorerTests: XCTestCase {
                 // tryGoBack does swipe-down as its last resort (sheet dismiss)
                 let preBackTitle = titleStr
                 let backWorked = tryGoBack()
+                lastExplorerBackStep = actionCount
                 actionCount += 1
                 Thread.sleep(forTimeInterval: 0.3)
                 let postElements = readUITree(app)
@@ -2214,6 +2220,7 @@ class ExplorerTests: XCTestCase {
                 // Scrolling done — try to go back and verify the screen actually changed
                 let preBackTitle = titleStr
                 let backResult = tryGoBack()
+                lastExplorerBackStep = actionCount
                 actionCount += 1
                 Thread.sleep(forTimeInterval: 0.3)
                 let postBackElements = readUITree(app)
@@ -2270,6 +2277,7 @@ class ExplorerTests: XCTestCase {
                     let swipeStart = app.coordinate(withNormalizedOffset: CGVector(dx: 0.5, dy: 0.3))
                     let swipeEnd = app.coordinate(withNormalizedOffset: CGVector(dx: 0.5, dy: 0.9))
                     swipeStart.press(forDuration: 0.1, thenDragTo: swipeEnd)
+                    lastExplorerBackStep = actionCount
                     actionCount += 1
                     print("OCQA_ACTION:{\"type\":\"swipe_dismiss\",\"reason\":\"escape_stuck\",\"step\":\(actionCount),\"screen\":\"\(escapedTitle)\",\"narrative\":\"\(escapeJSON(recoveryNarrative("swipe_dismiss", screen: titleStr)))\"}")
                     Thread.sleep(forTimeInterval: 0.5)

package/bin/tapp.js

@@ -283,6 +283,7 @@ function safeCommandUsage(verb) {
     app: "tapp app [repo] [--no-open] [--port PORT]",
     report: "tapp report [captureId|latest]",
     feedback: "tapp feedback \"short title\" [--body TEXT|--body-file FILE] [--type bug|idea|question] [--capture ID|latest|none] [--as human] [--submit] [--json]\n  Drafts a public GitHub issue on aarwitz/tapp about tapp itself; --submit files it with the authenticated gh CLI.\n  Exit codes: 0 drafted or filed · 1 gh submission failed · 2 usage error",
+    audit: "tapp audit <url> [--json] [--device NAME] [--viewport WxH]\n  Read-only: renders the page and reads the tree, never clicks — safe to point at production.\n  Exit codes: 0 no dead controls · 1 dead controls found · 2 usage/infrastructure",
     doctor: "tapp doctor [--json]\n  Exit codes: 0 environment healthy · 1 blocked (fix ❌ items)",
     install: "tapp install",
     mcp: "tapp mcp",
@@ -302,7 +303,7 @@ if (["--help", "-h"].includes(command)) {
 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", "feedback",
+  "pr", "plan", "baseline", "ci", "actor", "app", "studio", "report", "doctor", "install", "feedback", "audit",
 ]);
 if (!knownCommands.has(command)) {
   console.error(`❌ Unknown command: ${command}`);
@@ -1150,9 +1151,48 @@ switch (command) {
       break;
     }
     if (!["run", "validate"].includes(verb) || !flowPath) {
-      console.error("usage: tapp flow example\n       tapp flow steps [--json]\n       tapp flow run <flow.yml> [--platform ios|android|web] [--actor NAME] [--email VALUE] [--password VALUE] [--url URL] [--app-id ID] [--apk FILE] [--serial ID]\n       tapp flow validate <flow.yml>");
+      console.error("usage: tapp flow example\n       tapp flow steps [--json]\n       tapp flow run <flow.yml|glob> [...more] [--platform ios|android|web] [--actor NAME] [--email VALUE] [--password VALUE] [--url URL] [--app-id ID] [--apk FILE] [--serial ID]\n       tapp flow validate <flow.yml|glob> [...more]\n       Several Flows (or a glob) run in sequence and print one line per Flow; exit 1 if any failed.");
       process.exit(2);
     }
+    // Several Flows in one command (field issue #9): the shell usually expands the glob, but a
+    // quoted pattern arrives whole. Everyone writes this loop by hand otherwise.
+    const expandFlowPattern = (pattern) => {
+      if (!/[*?]/.test(pattern)) return [pattern];
+      const dir = path.dirname(pattern);
+      const rx = new RegExp(`^${path.basename(pattern).replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*").replace(/\?/g, ".")}$`);
+      try {
+        return fs.readdirSync(dir).filter((name) => rx.test(name)).sort().map((name) => path.join(dir, name));
+      } catch { return []; }
+    };
+    const flowPaths = positionals.slice(1).flatMap(expandFlowPattern);
+    if (flowPaths.length > 1) {
+      const passThrough = Object.entries(flags).flatMap(([key, value]) =>
+        value === true ? [`--${key}`] : typeof value === "string" ? [`--${key}`, value] : []);
+      const rows = [];
+      for (const candidate of flowPaths) {
+        const name = path.basename(candidate).replace(/\.(ya?ml|json)$/i, "");
+        process.stderr.write(`▶️  ${name}\n`);
+        const child = spawnSync(process.execPath, [path.join(packageRoot, "bin", "tapp.js"), "flow", verb, candidate, ...passThrough], { encoding: "utf8", env: process.env });
+        const output = `${child.stdout || ""}\n${child.stderr || ""}`;
+        // Prefer the cause tapp already distilled; never the last line of a boxed error (#23).
+        const lines = output.split("\n");
+        const errorAt = lines.findIndex((line) => line.trim().startsWith("❌"));
+        // A validation error puts its reasons on the bullet lines under the ❌ headline; a
+        // headline alone ("Invalid web Flow — b-bad:") names no cause.
+        const headline = errorAt >= 0
+          ? [lines[errorAt], ...(/[:：]\s*$/.test(lines[errorAt]) ? [lines[errorAt + 1] || ""] : [])].map((line) => line.trim()).filter(Boolean).join(" ")
+          : "";
+        const cause = (output.match(/^\s*(?:\*\*)?First failure:.*$/m)?.[0] || headline || "")
+          .replace(/\*\*/g, "").replace(/\s+/g, " ").trim().slice(0, 160);
+        rows.push({ name, ok: (child.status ?? 1) === 0, cause });
+      }
+      const width = Math.max(...rows.map((row) => row.name.length));
+      console.log("");
+      for (const row of rows) console.log(`${row.name.padEnd(width)}  ${row.ok ? "PASS" : "FAIL"}${row.ok || !row.cause ? "" : `  ${row.cause}`}`);
+      const failed = rows.filter((row) => !row.ok).length;
+      console.log(`\n${rows.length - failed}/${rows.length} ${verb === "validate" ? "valid" : "passed"}`);
+      process.exit(failed ? 1 : 0);
+    }
     const absolute = path.resolve(flowPath);
     if (!fs.existsSync(absolute)) {
       console.error(`❌ Flow not found: ${absolute}`);
@@ -1463,6 +1503,38 @@ switch (command) {
     process.exit(2);
   }
 
+  case "audit": {
+    const { flags, positionals } = parseVerbArgs(rest);
+    const url = positionals[0] || "";
+    if (!/^https?:\/\//i.test(url)) {
+      console.error("usage: tapp audit <http(s) url> [--json] [--device NAME] [--viewport WxH]\n       Read-only structural audit: never clicks, safe against production.");
+      process.exit(2);
+    }
+    try {
+      const { auditWebPage } = await import(path.join(packageRoot, "mcp-server", "src", "web-explorer.js"));
+      const result = await auditWebPage({
+        url,
+        device: typeof flags.device === "string" ? flags.device : "",
+        viewport: typeof flags.viewport === "string" ? flags.viewport : "",
+      });
+      if (flags.json === true) {
+        console.log(JSON.stringify({ kind: "tapp-structural-audit", readOnly: true, ...result }, null, 2));
+      } else {
+        console.log(`🔎 Structural audit — ${result.url}\n   ${result.controlsExamined} control(s) examined · nothing was clicked`);
+        if (!result.findings.length) console.log("\n✅ No structurally dead controls found.");
+        else {
+          console.log("");
+          for (const finding of result.findings) console.log(`  ⚠️  ${finding.title}`);
+          console.log(`\n${result.findings.length} dead control(s). These are controls no Flow would cover — nobody writes a test for a button they believe does nothing.`);
+        }
+      }
+      process.exit(result.findings.length ? 1 : 0);
+    } catch (error) {
+      console.error(`❌ ${error.message || String(error)}`);
+      process.exit(2);
+    }
+  }
+
   case "doctor": {
     const { flags: doctorFlags } = parseVerbArgs(rest);
     const jsonMode = doctorFlags.json === true;
@@ -1541,14 +1613,29 @@ switch (command) {
 
     try {
       const { chromium } = await import("playwright");
+      // Launch for real rather than stat the path executablePath() reports.
+      // They are not the same question: web Flows launch headless, Playwright
+      // may serve that from a separate binary, and executablePath() answers
+      // for the full browser either way — so a stat can say Web is ready while
+      // every launch fails on a binary nobody was asked to install. Whatever a
+      // future Playwright resolves headless to, opening and closing one is the
+      // only answer that stays true.
       let executable = "";
-      try { executable = chromium.executablePath(); } catch { /* report the missing browser below */ }
-      if (executable && fs.existsSync(executable)) {
+      try { executable = chromium.executablePath(); } catch { /* the launch below is the real check */ }
+      let launchError = "";
+      try {
+        const probe = await chromium.launch({ headless: true });
+        await probe.close();
+      } catch (error) {
+        launchError = String(error?.message || error).split("\n").find((line) => line.trim()) || "";
+      }
+      if (!launchError) {
         report.platforms.web = { available: true, chromium: executable };
-        sayOk("Web", `Playwright + Chromium (${executable})`);
+        sayOk("Web", `Playwright + Chromium${executable ? ` (${executable})` : ""}`);
       } else {
-        report.platforms.web = { available: false, reason: "Chromium browser missing (run: npx playwright install chromium)" };
+        report.platforms.web = { available: false, reason: "Chromium browser missing (run: npx playwright install chromium)", detail: launchError };
         say("  ⬜ Web — Playwright installed; Chromium browser missing (run: npx playwright install chromium)");
+        say(`     ${launchError}`);
       }
     } catch {
       report.platforms.web = { available: false, reason: "Playwright not installed" };
@@ -1951,6 +2038,9 @@ Primitives — an agent's eyes and hands:
                            (web: --tap TEXT · --wait-for TEXT · --out FILE)
   tapp tree [target]       Accessibility tree of the current screen (--json for every element)
                            (web: --tap TEXT · --wait-for TEXT)
+  tapp audit <url>         Read-only structural audit — dead anchors, placeholder links, buttons
+                           with nothing behind them. Never clicks, so it is safe against
+                           production (exit 1 when dead controls are found)
 
 Repository & release:
   tapp init [repo]         Detect targets and write the application model + reviewable release plan

package/mcp-server/src/index.js

@@ -917,7 +917,7 @@ const SESSION_ACT_ARGS = Object.freeze({
   login: "{email?, password?} (defaults to the session's credentials)",
   swipe: "{direction: up|down|left|right}",
   back: "{}",
-  tree: "{verbose?: true}",
+  tree: "{verbose?: true} — verbose returns every element and the complete control list",
   screenshot: "{label?}",
 });
 export function sessionActUsageError(cmd = {}) {
@@ -1769,13 +1769,15 @@ function elementBreakdown(elements) {
 }
 
 /** Scannable "Read screen X — N elements (...)" readout, plus the tappable/typeable controls. */
-export function formatScreen(screenTitle, elements) {
+export function formatScreen(screenTitle, elements, { full = false } = {}) {
   const els = elements || [];
   const interactable = els.filter((e) => e.isEnabled !== false && (String(e.type).includes("Button") || String(e.type).includes("Link") || String(e.type).includes("rawValue: 9") || String(e.type).includes("TextField") || String(e.type).includes("rawValue: 49") || String(e.type).includes("rawValue: 50") || String(e.type).includes("Cell") || String(e.type).includes("rawValue: 75")));
   const allLabels = interactable
     .map((e) => (e.label || e.identifier || "").trim())
     .filter((s) => s && s.length <= 40 && !s.includes("."));
-  const labels = allLabels.slice(0, 8);
+  // A verbose/full readout must actually be full: the 8-item cap hid the fifth tab's label
+  // and left tapping by coordinate as the only way to reach it (field issue #9).
+  const labels = full ? allLabels : allLabels.slice(0, 8);
   const L = [`🌳 Read screen **${screenTitle || "Unknown"}** — ${els.length} elements (${elementBreakdown(els)})`];
   // A silently cut list reads as complete; say when it isn't.
   if (labels.length) L.push("", "**Controls:** " + labels.map((l) => `\`${l}\``).join(" · ")
@@ -4523,8 +4525,11 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const detailNote = !ok && r.detail ? ` — ${r.detail}` : "";
     const head = `${did} — ${ok ? "ok" : `⚠️ ${r.status}${detailNote}`} → now on **${r.screenTitle || "Unknown"}**`;
     const rec = typeof r.recordedSteps === "number" ? `\n\n🔴 Recording — ${r.recordedSteps} step(s). \`tapp_flow_save\` to keep it as a test.` : "";
-    const screen = agentScreenProjection(r, { full: action === "tree" && args.full === true });
-    const result = richResult(head + "\n\n" + formatScreen(screen.screenTitle, screen.elements) + rec, { ...r, ...screen });
+    // `verbose` is the documented spelling (SESSION_ACT_ARGS.tree); `full` is the original.
+    // Accepting only `full` meant the documented flag silently did nothing (field issue #9).
+    const fullTree = action === "tree" && (args.full === true || args.verbose === true || cmd.verbose === true || cmd.full === true);
+    const screen = agentScreenProjection(r, { full: fullTree });
+    const result = richResult(head + "\n\n" + formatScreen(screen.screenTitle, screen.elements, { full: fullTree }) + rec, { ...r, ...screen });
     if (!ok) result.isError = true;
     return result;
   }

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

@@ -1175,3 +1175,97 @@ export async function exploreWeb({ url, maxActions = 40, timeoutSec = 300, outDi
   }
   return { markersPath, outDir, actions, screens: screenCount, seedRoutes: normalizedSeeds, seedTargets: normalizedTargets };
 }
+
+// ---- Read-only structural audit (field issue #24) -------------------------------------
+// Flows hold known-good behaviour fixed; they cannot find a control that was NEVER alive,
+// because nobody writes a flow for a button they believe does nothing. This pass renders the
+// page and reads the tree — it never clicks — so it is the one analysis that can be pointed
+// at production, which is where dead controls actually live.
+export function auditFindingsFromControls(controls = []) {
+  const findings = [];
+  for (const control of controls) {
+    const where = control.label || control.identifier || control.selector || "(unlabelled)";
+    if (control.kind === "dead_anchor") {
+      findings.push({ type: "anchor_missing", severity: "medium",
+        title: `In-page link “${where}” points at #${control.fragment}, which is not on the page`, target: control.href });
+    } else if (control.kind === "placeholder_link") {
+      findings.push({ type: "placeholder_link", severity: "medium",
+        title: `Link “${where}” has no destination (href="${control.href}")`, target: control.href });
+    } else if (control.kind === "dangling_aria_controls") {
+      findings.push({ type: "dangling_aria_controls", severity: "medium",
+        title: `“${where}” declares aria-controls="${control.controls}", but no such element exists`, target: control.controls });
+    } else if (control.kind === "unwired_control") {
+      findings.push({ type: "unwired_control", severity: "medium",
+        title: `Button “${where}” has no click handler, form, or link behind it`, target: control.selector });
+    }
+  }
+  return findings;
+}
+
+// Collected inside the page: every structurally dead control, WITHOUT interacting with any.
+export async function auditWebPage({ url, timeoutMs = NAV_TIMEOUT_MS, device = "", viewport = "" }) {
+  let target;
+  try { target = new URL(url); }
+  catch { throw new Error("Audit needs a valid http(s) URL"); }
+  if (!/^https?:$/.test(target.protocol)) throw new Error("Audit needs a valid http(s) URL");
+  const { chromium, devices } = await loadPlaywright();
+  const browser = await chromium.launch(webBrowserLaunchOptions(process.env, {}));
+  try {
+    const context = await browser.newContext(webContextOptions({ device, viewport, devices }));
+    await installWebListenerTracking(context);
+    const page = await context.newPage();
+    const bounded = Math.max(1000, Math.min(60_000, Number(timeoutMs) || NAV_TIMEOUT_MS));
+    page.setDefaultTimeout(bounded);
+    const response = await page.goto(target.href, { waitUntil: "domcontentloaded", timeout: bounded });
+    if (response && response.status() >= 400) throw new Error(`Could not open ${target.href}: HTTP ${response.status()}`);
+    await waitForWebStability(page, { timeoutMs: Math.min(5_000, bounded) });
+    const controls = await page.evaluate(() => {
+      const key = Symbol.for("tapp.clickListeners");
+      const visible = (el) => {
+        const style = window.getComputedStyle(el);
+        return style.visibility !== "hidden" && style.display !== "none" && el.getClientRects().length > 0;
+      };
+      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();
+      const dead = [];
+      for (const el of document.querySelectorAll("a[href], button, [role=button], [aria-controls]")) {
+        if (!visible(el)) continue;
+        const label = name(el);
+        const href = el.getAttribute("href");
+        const ariaControls = el.getAttribute("aria-controls");
+        if (ariaControls && !document.getElementById(ariaControls)) {
+          dead.push({ kind: "dangling_aria_controls", label, selector: selectorFor(el), controls: ariaControls });
+          continue;
+        }
+        if (href != null) {
+          if (href === "#" || href.trim() === "" || /^javascript:\s*(void\(0\))?;?$/i.test(href)) {
+            dead.push({ kind: "placeholder_link", label, selector: selectorFor(el), href });
+          } else if (href.startsWith("#")) {
+            const fragment = decodeURIComponent(href.slice(1));
+            const found = fragment && (document.getElementById(fragment) || document.getElementsByName(fragment).length > 0);
+            if (!found) dead.push({ kind: "dead_anchor", label, selector: selectorFor(el), href, fragment });
+          }
+          continue;
+        }
+        // A button with nothing behind it: no listener on itself or an ancestor, no inline
+        // handler, and not a submit inside a form.
+        let wired = false;
+        for (let node = el; node && node !== document.body; node = node.parentElement) {
+          if ((node[key] && node[key].size > 0) || typeof node.onclick === "function" || node.hasAttribute("onclick")) { wired = true; break; }
+        }
+        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) dead.push({ kind: "unwired_control", label, selector: selectorFor(el) });
+      }
+      return { dead, controlCount: document.querySelectorAll("a[href], button, [role=button]").length, title: document.title };
+    });
+    return {
+      url: page.url(),
+      title: controls.title,
+      controlsExamined: controls.controlCount,
+      findings: auditFindingsFromControls(controls.dead),
+    };
+  } finally {
+    await browser.close().catch(() => {});
+  }
+}

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

@@ -10,9 +10,13 @@ const DEFAULT_TIMEOUT = 6000;
 // What WAS visible when a wait missed — points a failure report at the fix (renamed label,
 // error state, wrong page) without a separate `tapp tree` run (field issue #20).
 async function visibleLabelsHint(page, limit = 8) {
+  const collect = async (scope) => {
+    try { return String(await scope.locator("body").innerText({ timeout: 1000 })); } catch { return ""; }
+  };
   try {
-    const text = await page.locator("body").innerText({ timeout: 1000 });
-    const labels = [...new Set(String(text).split(/\n+/).map((l) => l.trim()).filter((l) => l.length >= 2 && l.length <= 60))].slice(0, limit);
+    // Include same-origin frames: the text a reader can see may live inside an embedded modal.
+    const texts = [await collect(page), ...(await Promise.all(sameOriginFrames(page).map(collect)))];
+    const labels = [...new Set(texts.join("\n").split(/\n+/).map((l) => l.trim()).filter((l) => l.length >= 2 && l.length <= 60))].slice(0, limit);
     return labels.length ? ` — visible: ${labels.join(" · ")}` : "";
   } catch { return ""; }
 }
@@ -31,19 +35,49 @@ function cssId(value) {
   return "#" + String(value).replace(/([^a-zA-Z0-9_-])/g, "\\$1");
 }
 
-export async function locateWebElement(page, target) {
+// A frame whose content the page's own origin may script. An `about:blank`/`srcdoc` frame
+// inherits its parent's origin. Cross-origin frames (third-party widgets) stay out of scope:
+// a Flow should not assert on content the page itself cannot read.
+function sameOriginFrames(page) {
+  if (typeof page.frames !== "function") return []; // non-Playwright page (tests, fakes)
+  let origin;
+  try { origin = new URL(page.url()).origin; } catch { return []; }
+  const main = typeof page.mainFrame === "function" ? page.mainFrame() : null;
+  return page.frames().filter((frame) => {
+    if (frame === main) return false;
+    const url = frame.url() || "";
+    if (!url || url === "about:blank" || url.startsWith("about:srcdoc")) return true;
+    try { return new URL(url).origin === origin; } catch { return false; }
+  });
+}
+
+function targetCandidates(scope, target) {
   const exact = { exact: true };
-  const candidates = [
-    page.getByTestId(target),
-    page.locator(cssId(target)),
-    page.getByLabel(target, exact),
-    page.getByRole("button", { name: target, exact: true }),
-    page.getByRole("link", { name: target, exact: true }),
-    page.getByText(target, exact),
-    page.getByLabel(target),
-    page.getByText(target),
+  return [
+    scope.getByTestId(target),
+    scope.locator(cssId(target)),
+    scope.getByLabel(target, exact),
+    scope.getByRole("button", { name: target, exact: true }),
+    scope.getByRole("link", { name: target, exact: true }),
+    scope.getByText(target, exact),
+    scope.getByLabel(target),
+    scope.getByText(target),
   ];
-  return firstVisible(candidates);
+}
+
+export async function locateWebElement(page, target) {
+  const top = await firstVisible(targetCandidates(page, target));
+  if (top) return top;
+  // A modal rendered into a same-origin <iframe> is visibly on screen but invisible to a
+  // top-document-only search, so `wait_for` timed out on text the screenshot plainly showed
+  // (field issue #14). Top document first, then each same-origin frame in document order.
+  for (const frame of sameOriginFrames(page)) {
+    try {
+      const inFrame = await firstVisible(targetCandidates(frame, target));
+      if (inFrame) return inFrame;
+    } catch { /* a frame can detach mid-search — keep looking */ }
+  }
+  return null;
 }
 
 async function screenCandidates(page) {
@@ -125,6 +159,21 @@ export async function runWebRequestStep({ step, startUrl, vars = {}, timeout = D
   return { action: "request", target: `${method} ${targetUrl.pathname}`, status: "pass", detail: "" };
 }
 
+// Playwright (and its install prompt) wrap guidance in box-drawing art spanning many lines.
+// Consumers that keep ONE line of an error — a scoreboard row, a CI table — kept the box's
+// bottom border `╚═══╝` and threw the cause away (field issue #23). Put the cause first and
+// carry any actionable instruction with it, so the first AND last line are both useful.
+export function distillErrorMessage(message) {
+  const lines = String(message || "").split("\n")
+    .map((line) => line.replace(/[╔╗╚╝═║│┌┐└┘─]/g, " ").trim())
+    .filter(Boolean);
+  if (!lines.length) return String(message || "").trim();
+  const headline = lines[0];
+  // A boxed Playwright prompt carries the fix as a bare command line inside the art.
+  const fix = lines.slice(1).find((line) => /^(npx|npm|pip3?|python3|yarn|pnpm) /.test(line));
+  return fix && !headline.includes(fix) ? `${headline} — fix: ${fix}` : headline;
+}
+
 // Playwright's timeout errors bury the actual cause ("<div id=…> intercepts pointer events",
 // "element is not visible") in a multi-line retry log; single-line consumers kept only
 // "Timeout 6000ms exceeded" and the report read like the element did not exist (field issue

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aarwitz/tapp",
-  "version": "0.17.13",
+  "version": "0.17.14",
   "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",

package/scripts/run-web-flow.js

@@ -3,8 +3,9 @@ import os from "node:os";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
-import { loadFlowFile } from "../mcp-server/src/flow-runtime.js";
-import { runWebFlow } from "../mcp-server/src/web-flow.js";
+import fs from "node:fs";
+import { FlowLog, loadFlowFile } from "../mcp-server/src/flow-runtime.js";
+import { distillErrorMessage, runWebFlow } from "../mcp-server/src/web-flow.js";
 
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const flowPath = process.argv[2];
@@ -30,6 +31,16 @@ try {
   process.stdout.write((report.stdout || "").trim() + "\n");
   process.exit(result.passed ? 0 : 1);
 } catch (error) {
-  console.error(`❌ ${error.message || error}`);
+  // A run that dies before step 1 (no browser installed, bad url) still owes a structured
+  // report: without one the scoreboard shows an empty row and consumers keep whatever text
+  // line they can reach — for a boxed Playwright prompt, its bottom border (field issue #23).
+  const cause = distillErrorMessage(error?.message || String(error));
+  console.error(`❌ ${cause}`);
+  try {
+    fs.rmSync(logPath, { force: true });
+    const log = new FlowLog({ logPath, flow });
+    log.step({ index: 1, action: "harness", target: flow.name || "flow", status: "fail", detail: cause });
+    log.finish({ abortReason: cause });
+  } catch { /* the console line above is still the answer */ }
   process.exit(2);
 }

package/skills/tapp/references/commands.md

@@ -11,6 +11,7 @@ npx -y @aarwitz/tapp@latest explore [target]
 npx -y @aarwitz/tapp@latest focus "Save storefront settings visible above keyboard" [target]
 npx -y @aarwitz/tapp@latest open [target]
 npx -y @aarwitz/tapp@latest tree [target] --json
+npx -y @aarwitz/tapp@latest audit https://example.com --json   # read-only: never clicks, safe against production
 npx -y @aarwitz/tapp@latest shot
 npx -y @aarwitz/tapp@latest report latest
 npx -y @aarwitz/tapp@latest doctor