@aarwitz/tapp 0.16.2 → 0.16.4

package/AGENTS.md

@@ -11,7 +11,7 @@ the app already on the simulator); it also accepts a repo dir, a `path/to/App.ap
 bundle id, or (qa only) an http(s) URL. You never need to know a bundle id up front.
 
 ```bash
-npx -y @aarwitz/tapp qa [target]     # autonomous QA → ship/no-ship verdict + findings (≈ tapp_run_qa)
+npx -y @aarwitz/tapp qa [target]     # autonomous QA → scoped release verdict + findings (≈ tapp_run_qa)
 npx -y @aarwitz/tapp open [target]   # launch + screen summary + screenshot saved to a file (≈ tapp_open_app)
 npx -y @aarwitz/tapp tree [target]   # accessibility tree, --json for every element (≈ tapp_ui_tree)
 npx -y @aarwitz/tapp shot            # screenshot the booted sim → file path (≈ tapp_screenshot)
@@ -21,6 +21,11 @@ npx -y @aarwitz/tapp qa app.apk --platform android --app-id com.acme.app
 npx -y @aarwitz/tapp flow run .tapp/flows/smoke.yml  # committed, keyless E2E replay
 ```
 
+For focused web evidence, `open` and `tree` accept one semantic interaction plus an async content
+wait: `tapp open https://example.com --tap "Not now" --wait-for "Dashboard"`. Tapp waits for the
+page to stabilize before capturing it and warns honestly if the bounded wait ends while it is still
+loading or changing.
+
 **Seeing the screen, per client:** if you can read image files into your context (Claude
 Code's Read tool, Codex's view-image), open the saved screenshot path the CLI prints —
 that IS the screen. If you cannot (Cursor, VS Code Copilot), connect the MCP server
@@ -39,7 +44,7 @@ installs, returns the bundle id) → `tapp_run_qa {appBundleId}`.
 |---|---|---|
 | "Show me / screenshot a screen" | `tapp_open_app` (launch + screenshot + tree, ~15s) | `tapp_run_qa` (a full multi-minute QA exploration) |
 | "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? Is it ship-ready? Find bugs" | `tapp_run_qa` — `appBundleId` for iOS, `androidAppId` for Android, `url` for owned web apps | a manual session (QA exploration is autonomous) |
+| "Is my app broken? Is it ship-ready? Find bugs" | `tapp_run_qa` — `appBundleId` for iOS, `androidAppId` for Android, `url` for owned web apps; web `ready` means the disclosed automated checks passed, not that copy/privacy/brand claims were reviewed | a manual session (QA 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 |
 | "What's on screen right now?" | `tapp_screenshot` / `tapp_ui_tree` | relaunching the app |
 
@@ -89,6 +94,10 @@ Returns `{verdict, confidence, headline, screensExplored, actionsPerformed, find
   the user** for them rather than re-running blind.
 - Diff two runs: pass the previous run's `findings` as `baselineFindings` → you get a
   `regression` block (`new` / `persisting` / `resolved`, plus a CI `gate` signal).
+- On web, report the exact verdict but preserve its scope: Tapp deterministically checks technical
+  behavior such as failed requests, missing assets, placeholder links, and inert controls. It does
+  not validate marketing claims against APIs, API field privacy, brand consistency, or subjective
+  marketplace credibility unless an explicit reviewed test/contract covers them.
 
 ## Flows (deterministic E2E tests)
 

package/README.md

@@ -26,7 +26,7 @@ Three platforms, one judgment layer:
   does not link a Tapp SDK.
 - **Web (beta)** — built *on* Playwright. Your agent already has browser hands; tapp adds the
   autonomous exploration, the deterministic detectors (uncaught exceptions, failed requests,
-  dead buttons, broken links, error pages), and the same verdict.
+  dead buttons, broken links, placeholder `href="#"` links, error pages), and the same verdict.
 
 ```
 you:    "Add a logout button to the settings screen"
@@ -99,6 +99,14 @@ npx -y @aarwitz/tapp build [dir]     # just build + install (scheme auto-detecte
 Web (beta): `npx -y @aarwitz/tapp qa http://localhost:3000` *(one-time setup:
 `npm i -g playwright && npx playwright install chromium`)*
 
+Focused web inspection waits briefly for loading states to settle. If a consent or location modal
+blocks the screen, dismiss it and wait for the content you care about in the same package-only call:
+
+```bash
+npx -y @aarwitz/tapp open https://example.com --tap "Not now" --wait-for "Dashboard"
+npx -y @aarwitz/tapp tree https://example.com --tap "Not now" --wait-for "Dashboard" --json
+```
+
 Android:
 
 ```bash
@@ -201,14 +209,21 @@ ranks runs, it doesn't promise odds.
 `tapp_run_qa` explores like a user — accessibility surfaces on iOS/Android and a real browser on web —
 and detects crashes, failed sign-ins, dead buttons, stuck loading screens, error surfaces,
 navigation loops, and dead ends (plus, on web: uncaught JS exceptions, failed/5xx requests,
-broken links and assets). The verdict is **deterministic** (no LLM in the run loop) and **honest**:
+broken links and assets, and visible placeholder links with no destination). The verdict is
+**deterministic** (no LLM in the run loop) and **honest**:
 
 - `blocked` — a release-blocking issue was found.
 - `caution` — issues to review, or the run couldn't see enough.
-- `ready` — genuinely explored with no blockers. **A shallow run is never `ready`** — if the
+- `ready` — genuinely explored with no detected blockers in the checks that ran. **A shallow run
+  is never `ready`** — if the
   app crashed on launch or a login wall blocked exploration, you get `inconclusive: true`,
   not a false pass. Absence of findings is not a pass.
 
+Web beta presents a `ready` result as **AUTOMATED CHECKS PASSED**, not “ship-ready.” Its report
+explicitly excludes content/claim accuracy, privacy and API data minimization, brand/SEO
+consistency, and subjective visual credibility. Those require reviewed contracts, privacy review,
+or human/vision judgment; a green technical crawl must not imply they were validated.
+
 Apps behind a login? Pass `testEmail`/`testPassword` (typed into the login form automatically),
 `appLaunchArgs` (e.g. `["--uitesting"]` if your app supports a bypass), or explicit `loginSteps`
 for custom login UIs.

package/bin/tapp.js

@@ -424,6 +424,7 @@ switch (command) {
           testEmail: flags.email,
           testPassword: flags.password,
           baselineFindings,
+          surface: "cli",
           onProgress,
         })
       : platform === "android"
@@ -435,6 +436,7 @@ switch (command) {
           testPassword: flags.password,
           baselineFindings,
           clearData: flags["keep-data"] !== true,
+          surface: "cli",
           onProgress,
         })
       : await engine.runQaIos({
@@ -442,6 +444,7 @@ switch (command) {
           maxActions: flags.actions,
           timeout: flags.timeout,
           args: { testEmail: flags.email, testPassword: flags.password, baselineFindings },
+          surface: "cli",
           onProgress,
         });
     process.stderr.write("\n");
@@ -469,13 +472,21 @@ switch (command) {
       }
       try {
         const { inspectWebPage } = await import(path.join(packageRoot, "mcp-server", "src", "web-explorer.js"));
-        const snap = await inspectWebPage({ url, timeoutMs: Number(flags.timeout) * 1000 || 15_000 });
+        const snap = await inspectWebPage({
+          url,
+          timeoutMs: Number(flags.timeout) * 1000 || 15_000,
+          tapText: typeof flags.tap === "string" ? flags.tap : "",
+          waitForText: typeof flags["wait-for"] === "string" ? flags["wait-for"] : "",
+        });
         const out = typeof flags.out === "string" ? path.resolve(flags.out) : path.join(tappHome, "shots", `web-${Date.now()}.png`);
         fs.mkdirSync(path.dirname(out), { recursive: true });
         fs.writeFileSync(out, snap.image);
         console.log(`🌐 Opened \`${snap.url}\`\n`);
+        if (typeof flags.tap === "string") console.log(`👆 Tapped \`${flags.tap}\`\n`);
+        if (typeof flags["wait-for"] === "string") console.log(`⏳ Found \`${flags["wait-for"]}\`\n`);
         console.log(engine.formatScreen(snap.screenTitle, snap.elements));
         console.log(`\n📸 Screenshot: ${out}`);
+        if (!snap.settled) console.error("⚠️ Page still showed a loading or changing state when the bounded wait ended.");
       } catch (error) {
         console.error(`❌ ${error.message || String(error)}`);
         process.exit(1);
@@ -533,9 +544,16 @@ switch (command) {
       }
       try {
         const { inspectWebPage } = await import(path.join(packageRoot, "mcp-server", "src", "web-explorer.js"));
-        const snap = await inspectWebPage({ url, timeoutMs: Number(flags.timeout) * 1000 || 15_000, screenshot: false });
-        if (flags.json) console.log(JSON.stringify({ platform: "web", url: snap.url, screenTitle: snap.screenTitle, elements: snap.elements }, null, 2));
+        const snap = await inspectWebPage({
+          url,
+          timeoutMs: Number(flags.timeout) * 1000 || 15_000,
+          screenshot: false,
+          tapText: typeof flags.tap === "string" ? flags.tap : "",
+          waitForText: typeof flags["wait-for"] === "string" ? flags["wait-for"] : "",
+        });
+        if (flags.json) console.log(JSON.stringify({ platform: "web", url: snap.url, screenTitle: snap.screenTitle, settled: snap.settled, elements: snap.elements }, null, 2));
         else console.log(engine.formatScreen(snap.screenTitle, snap.elements));
+        if (!snap.settled) console.error("⚠️ Page still showed a loading or changing state when the bounded wait ended.");
       } catch (error) {
         console.error(`❌ ${error.message || String(error)}`);
         process.exit(1);
@@ -1358,9 +1376,11 @@ switch (command) {
 
 Zero-config verbs (agents and humans can just run these — no server, no setup):
   tapp open [target]       Launch the app → screen summary + screenshot saved to a file
+                           (web: --tap TEXT · --wait-for TEXT · --out FILE)
   tapp qa [target]         Autonomous QA → verdict + findings + evidence
                            (--platform ios|android|web · --app-id ID · --apk FILE · --actions N)
   tapp tree [target]       Accessibility tree of the current screen (--json for every element)
+                           (web: --tap TEXT · --wait-for TEXT)
   tapp flow run FILE       Replay a committed deterministic Flow (no AI/API key)
   tapp flow validate FILE  Validate a Flow without launching a target
   tapp task validate FILE  Validate a reusable deterministic Task (+ optional UI Map grounding)

package/mcp-server/src/ci-report.js

@@ -26,7 +26,7 @@
 //   any      fail on any finding at all, or any flow failure. Strictest.
 import fs from "fs";
 import path from "node:path";
-import { buildQaReport, computeRegression, computeContentCollapse, computeReachabilityLoss } from "./report.js";
+import { buildQaReport, computeRegression, computeContentCollapse, computeReachabilityLoss, verdictBadge } from "./report.js";
 import { writeHtmlReport } from "./html-report.js";
 import { buildUiMapFromMarkers, writeUiMap } from "./ui-map.js";
 import { proposeSelectorMaintenance, validateWebMaintenanceProposal } from "./maintenance-proposal.js";
@@ -337,12 +337,11 @@ function enrichPrPlan(plan, contracts, currentUiMap = null, markersPath = "", pr
   return { ...plan, selected, explorationTargets, maintenanceCandidates, execution: counts };
 }
 
-const VERDICT_BADGE = { ready: "🟢 SHIP-READY", caution: "🟡 CAUTION", blocked: "🔴 BLOCKED" };
 const SEV_ICON = { critical: "🟥", high: "🟧", medium: "🟨", low: "🟩" };
 
 function renderMarkdown(report, regression, flows, scenarios, contracts, prPlan, gate) {
   const lines = [];
-  lines.push(`## tapp release check — ${VERDICT_BADGE[report.verdict] || report.verdict}`);
+  lines.push(`## tapp release check — ${verdictBadge(report)}`);
   lines.push("");
   lines.push(report.headline);
   lines.push("");

package/mcp-server/src/html-report.js

@@ -8,9 +8,8 @@
 
 import fs from "fs";
 import path from "path";
-import { buildQaReport } from "./report.js";
+import { buildQaReport, verdictBadge } from "./report.js";
 
-const BADGE = { ready: "🟢 SHIP-READY", caution: "🟡 CAUTION", blocked: "🔴 BLOCKED" };
 const SEV_COLOR = { critical: "#cf222e", high: "#bc4c00", medium: "#9a6700", low: "#57606a" };
 
 const esc = (s) => String(s ?? "").replace(/[&<>"]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" }[c]));
@@ -102,7 +101,7 @@ export function writeHtmlReport(captureDir, { report, label = "" } = {}) {
 </style>
 </head>
 <body>
-<h1>${BADGE[r.verdict] || esc(r.verdict)} <span class="dim">· release score ${r.releaseScore ?? r.confidence}/100</span></h1>
+<h1>${esc(verdictBadge(r))} <span class="dim">· release score ${r.releaseScore ?? r.confidence}/100</span></h1>
 <div class="meta">${esc(label)} · ${r.screensExplored} screens · ${r.actionsPerformed} actions · ${r.findingCounts.total} finding(s)</div>
 <div class="headline">${esc(r.headline)}</div>
 <h2>Findings</h2>
@@ -114,7 +113,7 @@ ${findingsHtml}
 ${shotsHtml || "<p class='dim'>No screenshots captured.</p>"}
 </div>
 ${videoHtml}
-<footer>Generated by <a href="https://github.com/aarwitz/tapp">Tapp</a> — autonomous QA with a deterministic ship/no-ship verdict. Ship with proof.</footer>
+<footer>Generated by <a href="https://github.com/aarwitz/tapp">Tapp</a> — deterministic automated checks with explicit coverage limits. Review unchecked product risks before release.</footer>
 </body>
 </html>
 `;

package/mcp-server/src/index.js

@@ -12,7 +12,7 @@ import {
   ListToolsRequestSchema,
 } from "@modelcontextprotocol/sdk/types.js";
 
-import { parseOcqaMarkers, buildQaReport, computeRegression } from "./report.js";
+import { parseOcqaMarkers, buildQaReport, computeRegression, verdictBadge } from "./report.js";
 import { existingProjectArtifactPath, projectArtifactDirectory } from "./project-paths.js";
 
 const __filename = fileURLToPath(import.meta.url);
@@ -1289,7 +1289,6 @@ function errorResult(message, details = {}) {
 // programmatic use. This is what makes Tapp feel like a modern dev harness
 // ("Explored 14 screens · 3 issues · ship: caution") rather than a wall of JSON.
 const SEV = { critical: "🔴", high: "🟠", medium: "🟡", low: "⚪️" };
-const VERDICT_BADGE = { ready: "🟢 SHIP-READY", caution: "🟡 CAUTION", blocked: "🔴 BLOCKED" };
 
 /** Result with a human-readable text block first and structured data attached for the agent. */
 function richResult(text, structured) {
@@ -1304,9 +1303,24 @@ function fmtDuration(ms) {
 }
 
 /** Format a QA report as a scannable release readout with next-step suggestions. */
-function formatQaReport(report, { regression, inputHint, timedOut, bundleId, aiConfigured, reportHtml, recording, uiMap } = {}) {
+export function qaNextSteps(report, surface = "mcp") {
+  if (surface === "cli") {
+    const next = [];
+    if (report?.findings?.length) next.push("inspect the evidence with `tapp report latest`");
+    next.push("re-run with `--baseline <report.json>` to gate a fix");
+    next.push("replay a committed journey with `tapp flow run <file>`");
+    return next;
+  }
+  const next = [];
+  if (report?.findings?.length) next.push("open a flagged screen with `tapp_open_app`");
+  next.push("re-run with `baselineFindings` to gate a fix");
+  next.push("drive it step-by-step via `tapp_session_start`");
+  return next;
+}
+
+function formatQaReport(report, { regression, inputHint, timedOut, bundleId, aiConfigured, reportHtml, recording, uiMap, surface = "mcp" } = {}) {
   const c = report.findingCounts || {};
-  const badge = VERDICT_BADGE[report.verdict] || report.verdict;
+  const badge = verdictBadge(report);
   const sevBits = ["critical", "high", "medium", "low"]
     .map((k) => (c[k] ? `${SEV[k]} ${c[k]} ${k}` : null))
     .filter(Boolean)
@@ -1359,10 +1373,7 @@ function formatQaReport(report, { regression, inputHint, timedOut, bundleId, aiC
       }
     }
   }
-  const next = [];
-  if (report.findings && report.findings.length) next.push("open a flagged screen with `tapp_open_app`");
-  next.push("re-run with `baselineFindings` to gate a fix");
-  next.push("drive it step-by-step via `tapp_session_start`");
+  const next = qaNextSteps(report, surface);
   L.push("");
   L.push(`**Next** — ${next.join(" · ")}`);
   // The gate hook belongs at the moment the user thinks "I want this on every PR" —
@@ -1428,7 +1439,7 @@ export function formatScreen(screenTitle, elements) {
 // `tapp` CLI verbs in bin/tapp.js — same pattern as report.js. Keep orchestration HERE so
 // the surfaces can't drift.)
 
-export async function runQaWeb({ url, maxActions, timeout, testEmail, testPassword, baselineFindings, seedRoutes = [], seedTargets = [], onProgress = () => {} }) {
+export async function runQaWeb({ url, maxActions, timeout, testEmail, testPassword, baselineFindings, seedRoutes = [], seedTargets = [], surface = "mcp", onProgress = () => {} }) {
   const actions = Math.max(1, Math.min(1000, asInteger(maxActions, 60)));
   const timeoutSec = Math.max(30, Math.min(3600, asInteger(timeout, 600)));
   const id = "web-" + new Date().toISOString().replace(/[-:T]/g, "").slice(0, 14).replace(/^(\d{8})/, "$1-");
@@ -1465,11 +1476,11 @@ export async function runQaWeb({ url, maxActions, timeout, testEmail, testPasswo
     reportHtml = writeHtmlReport(outDir, { report, label: url.trim() });
   } catch { /* evidence page is best-effort */ }
   const structured = { ...report, regression, platform: "web", uiMap, reportHtml, exploration: { seedRoutes: webResult.seedRoutes || [], targets: webResult.seedTargets || [] }, capture: { id, path: outDir, relativePath: path.relative(repoRoot, outDir) } };
-  const text = formatQaReport(report, { regression, bundleId: url.trim(), aiConfigured: !!backend, reportHtml, uiMap: uiMap.error ? null : uiMap });
+  const text = formatQaReport(report, { regression, bundleId: url.trim(), aiConfigured: !!backend, reportHtml, uiMap: uiMap.error ? null : uiMap, surface });
   return { structured, text };
 }
 
-export async function runQaAndroid({ appId, apkPath, serial, maxActions, timeout, testEmail, testPassword, baselineFindings, clearData = true, seedTargets = [], onProgress = () => {} }) {
+export async function runQaAndroid({ appId, apkPath, serial, maxActions, timeout, testEmail, testPassword, baselineFindings, clearData = true, seedTargets = [], surface = "mcp", onProgress = () => {} }) {
   const actions = Math.max(1, Math.min(1000, asInteger(maxActions, 60)));
   const timeoutSec = Math.max(30, Math.min(3600, asInteger(timeout, 600)));
   const id = "android-" + new Date().toISOString().replace(/[-:T]/g, "").slice(0, 14).replace(/^(\d{8})/, "$1-");
@@ -1508,11 +1519,11 @@ export async function runQaAndroid({ appId, apkPath, serial, maxActions, timeout
     reportHtml = writeHtmlReport(outDir, { report, label: appId.trim() });
   } catch {}
   const structured = { ...report, regression, platform: "android", uiMap, reportHtml, exploration: { targets: androidResult.seedTargets || [] }, capture: { id, path: outDir, relativePath: path.relative(repoRoot, outDir) } };
-  const text = formatQaReport(report, { regression, bundleId: appId.trim(), aiConfigured: !!backend, reportHtml, uiMap: uiMap.error ? null : uiMap });
+  const text = formatQaReport(report, { regression, bundleId: appId.trim(), aiConfigured: !!backend, reportHtml, uiMap: uiMap.error ? null : uiMap, surface });
   return { structured, text };
 }
 
-export async function runQaIos({ bundleId, maxActions, timeout, args = {}, onProgress = () => {} }) {
+export async function runQaIos({ bundleId, maxActions, timeout, args = {}, surface = "mcp", onProgress = () => {} }) {
   const captureScript = path.join(scriptsDir, "quick-capture.sh");
   if (!fs.existsSync(captureScript)) return { error: "Capture script not found", details: { captureScript } };
 
@@ -1576,7 +1587,7 @@ export async function runQaIos({ bundleId, maxActions, timeout, args = {}, onPro
     timedOut,
     autoBooted: sim.autoBooted || false,
   };
-  const text = formatQaReport(report, { regression, inputHint, timedOut, bundleId, aiConfigured: !!backend, reportHtml, recording, uiMap: uiMap.error ? null : uiMap });
+  const text = formatQaReport(report, { regression, inputHint, timedOut, bundleId, aiConfigured: !!backend, reportHtml, recording, uiMap: uiMap.error ? null : uiMap, surface });
   return { structured, text };
 }
 

package/mcp-server/src/report.js

@@ -86,6 +86,7 @@ export const ISSUE_CATEGORY = {
   submit_failed: "unresponsive_element",
   error_surface: "network_error_surface",
   unresponsive_element: "unresponsive_element",
+  placeholder_link: "broken_link",
   dead_end: "navigation_dead_end",
   navigation_loop: "repeated_loop",
   navigation_trap: "navigation_dead_end",
@@ -100,6 +101,11 @@ export function severityRank(s) {
   return { critical: 0, high: 1, medium: 2, low: 3 }[s] ?? 4;
 }
 
+export function verdictBadge(report) {
+  if (report?.platform === "web" && report?.verdict === "ready") return "🟢 AUTOMATED CHECKS PASSED";
+  return { ready: "🟢 SHIP-READY", caution: "🟡 CAUTION", blocked: "🔴 BLOCKED" }[report?.verdict] || report?.verdict;
+}
+
 // Turn a capture's OCQA markers into the same ship/no-ship report Tapp produces:
 // deduped findings + a trustworthy verdict with a coverage floor (mirrors OrchestratorService).
 export function buildQaReport(markersFilePath, { platform = "ios" } = {}) {
@@ -152,11 +158,31 @@ export function buildQaReport(markersFilePath, { platform = "ios" } = {}) {
 
   const inputFieldsEncountered = Array.from(inputsByScreen.entries()).map(([screen, fields]) => ({ screen, fields }));
 
+  // Web resource failures belong to the resource, not every route that referenced it.
+  // Chromium can also surface one 404 through both response and requestfailed listeners;
+  // keep the concrete missing-asset finding and discard that transport-level duplicate.
+  const normalizedIssues = rawIssues.map((issue) => {
+    if (platform !== "web") return issue;
+    if (issue.type === "placeholder_link" && issue.target) return { ...issue, screen: null };
+    if (!["missing_asset", "network_error"].includes(issue.type)) return issue;
+    const title = String(issue.title || "");
+    const match = issue.type === "missing_asset"
+      ? title.match(/^404 asset:\s+(\S+)/i)
+      : title.match(/^Request failed:\s+(\S+)/i);
+    const resource = String(issue.target || match?.[1] || "").replace(/[?#].*$/, "");
+    return resource ? { ...issue, screen: null, target: resource } : issue;
+  });
+  const missingResources = new Set(normalizedIssues
+    .filter((issue) => issue.type === "missing_asset" && issue.target)
+    .map((issue) => issue.target));
+  const reportIssues = normalizedIssues.filter((issue) =>
+    !(issue.type === "network_error" && issue.target && missingResources.has(issue.target) && /^Request failed:/i.test(String(issue.title || ""))));
+
   // Dedup by stable signature (type|screen|target) so repeated detections count once —
   // but DIFFERENT controls failing on the same screen each count.
   const seen = new Set();
   const findings = [];
-  for (const i of rawIssues) {
+  for (const i of reportIssues) {
     const key = `${i.type}|${i.screen}|${i.target ?? ""}`;
     if (seen.has(key)) continue;
     seen.add(key);
@@ -187,7 +213,9 @@ export function buildQaReport(markersFilePath, { platform = "ios" } = {}) {
   const headline = inconclusive
     ? `Inconclusive — only ${screensExplored} screen(s) / ${actionsPerformed} action(s) explored. The app may have crashed on launch, be stuck behind a sign-in wall, or otherwise prevent exploration. Absence of issues is NOT a pass.`
     : verdict === "ready"
-    ? "Ship-ready — no release-blocking issues found."
+    ? platform === "web"
+      ? "Automated web checks passed — no release-blocking technical issues found in the exercised surfaces. This is not a content, privacy, brand, or business-claim review."
+      : "Ship-ready — no release-blocking issues found."
     : verdict === "caution"
     ? `Proceed with caution — ${findings.length} issue(s) to review.`
     : `Not ready — ${findings.length} issue(s): ${crit} critical, ${high} high, ${med} medium, ${low} low.`;
@@ -202,11 +230,14 @@ export function buildQaReport(markersFilePath, { platform = "ios" } = {}) {
   if (platform === "web") {
     checkedFor = [
       "page errors (uncaught exceptions)", "failed/5xx requests", "broken links (404)",
-      "dead buttons", "error text on pages", "load timeouts",
+      "placeholder links with no destination", "dead buttons", "error text on pages", "load timeouts",
     ];
     notChecked = [
       "app-specific business logic (cover with Flows: record or generate, then assert)",
-      "visual correctness — layout/images/clipping (vision review; needs an API key)",
+      "content and claim accuracy (including copy versus API data)",
+      "privacy or API data minimization",
+      "brand and SEO consistency",
+      "visual credibility or asset quality (vision review; needs an API key)",
       "only the first few visible buttons per page are probed (web beta)",
       "content & reachability regressions require a baseline",
     ];

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

@@ -20,11 +20,210 @@ import path from "path";
 import { createRequire } from "module";
 import { execFileSync } from "child_process";
 
-const SETTLE_MS = 500;
 const CLICK_SETTLE_MS = 700;
 const NAV_TIMEOUT_MS = 15_000;
 const BUTTONS_PER_PAGE = 4;
 const ERROR_TEXT_RE = /\b(something went wrong|internal server error|an error occurred|failed to load|unhandled exception)\b/i;
+const STANDALONE_ERROR_TEXT_RE = /^(something went wrong|internal server error|an error occurred|failed to load|unhandled exception)(?:[.!:]|\s|$)/i;
+
+export function webErrorSurfaceText({ alertText = "", candidateTexts = [] } = {}) {
+  const alert = String(alertText || "").trim();
+  if (alert && ERROR_TEXT_RE.test(alert)) return alert;
+  return (candidateTexts || [])
+    .map((text) => String(text || "").trim())
+    .find((text) => STANDALONE_ERROR_TEXT_RE.test(text)) || "";
+}
+
+export function webControlLabel({ text = "", value = "", ariaLabel = "", title = "", id = "" } = {}) {
+  return [text, value, ariaLabel, title, id]
+    .map((part) => String(part || "").trim())
+    .find(Boolean) || "button";
+}
+
+export function webPlaceholderLinkFindings(links = []) {
+  const findings = [];
+  const seen = new Set();
+  for (const link of links || []) {
+    const rawHref = String(link?.rawHref || "").trim().toLowerCase();
+    const placeholder = rawHref === "#" || /^javascript:(?:void\(0\);?|;?)$/.test(rawHref);
+    if (!placeholder || link?.handlerHint) continue;
+    const label = String(link?.label || "").replace(/\s+/g, " ").trim().slice(0, 100);
+    const fingerprint = String(link?.fingerprint || "link").replace(/\s+/g, " ").trim().slice(0, 100) || "link";
+    const target = label || `unlabeled:${fingerprint}`;
+    if (seen.has(target)) continue;
+    seen.add(target);
+    findings.push({
+      type: "placeholder_link",
+      severity: label ? "medium" : "low",
+      title: label
+        ? `Link "${label}" has no destination (${rawHref === "#" ? 'href="#"' : `href="${rawHref}"`})`
+        : `Unlabeled link has no destination (${rawHref === "#" ? 'href="#"' : `href="${rawHref}"`})`,
+      target,
+    });
+  }
+  return findings;
+}
+
+export function webControlHadEffect({ wired = false, before = {}, after = {} } = {}) {
+  if (wired) return true;
+  return ["url", "title", "heading", "dialogs", "local"]
+    .some((key) => String(before?.[key] ?? "") !== String(after?.[key] ?? ""));
+}
+
+export function shouldReportWebRequestFailure(errorText = "") {
+  // Chromium emits ERR_ABORTED when Tapp deliberately leaves a page while images/video are
+  // still loading. That is navigation lifecycle noise, not evidence that the resource is broken.
+  return !/\bnet::ERR_ABORTED\b/i.test(String(errorText));
+}
+
+export function webPageAppearsBlank({ textLen = 0, controlCount = 0, visualContentCount = 0 } = {}) {
+  return Number(textLen) === 0 && Number(controlCount) === 0 && Number(visualContentCount) === 0;
+}
+
+async function installWebListenerTracking(context) {
+  await context.addInitScript(() => {
+    const key = Symbol.for("tapp.clickListeners");
+    const add = EventTarget.prototype.addEventListener;
+    const remove = EventTarget.prototype.removeEventListener;
+    EventTarget.prototype.addEventListener = function tappTrackedAdd(type, listener, options) {
+      if (type === "click" && this instanceof Element && listener) {
+        if (!this[key]) Object.defineProperty(this, key, { value: new Set(), configurable: true });
+        this[key].add(listener);
+      }
+      return add.call(this, type, listener, options);
+    };
+    EventTarget.prototype.removeEventListener = function tappTrackedRemove(type, listener, options) {
+      if (type === "click" && this instanceof Element && this[key]) this[key].delete(listener);
+      return remove.call(this, type, listener, options);
+    };
+  });
+}
+
+async function captureWebControlState(page, locator) {
+  const global = await page.evaluate(() => {
+    const visible = (element) => {
+      const style = window.getComputedStyle(element);
+      return style.visibility !== "hidden" && style.display !== "none" && element.getClientRects().length > 0;
+    };
+    const dialogs = [...document.querySelectorAll("dialog[open], [role=dialog], [aria-modal=true]")]
+      .filter(visible)
+      .map((element) => (element.getAttribute("aria-label") || element.textContent || "dialog").replace(/\s+/g, " ").trim().slice(0, 160))
+      .sort();
+    return {
+      title: document.title,
+      heading: document.querySelector("h1")?.textContent?.replace(/\s+/g, " ").trim() || "",
+      dialogs: JSON.stringify(dialogs),
+    };
+  }).catch(() => ({ title: "", heading: "", dialogs: "" }));
+
+  const local = await locator.evaluate((element) => {
+    const key = Symbol.for("tapp.clickListeners");
+    const visible = (candidate) => {
+      const style = window.getComputedStyle(candidate);
+      return style.visibility !== "hidden" && style.display !== "none" && candidate.getClientRects().length > 0;
+    };
+    let wired = false;
+    for (let candidate = element; candidate && candidate !== document.body; candidate = candidate.parentElement) {
+      if ((candidate[key] && candidate[key].size > 0) || typeof candidate.onclick === "function" || candidate.hasAttribute("onclick")) {
+        wired = true;
+        break;
+      }
+    }
+    if (!wired && element.matches("button[type=submit], input[type=submit]") && element.closest("form")) wired = true;
+    const describe = (root) => ({
+      tag: root.tagName,
+      className: typeof root.className === "string" ? root.className : "",
+      hidden: root.hidden,
+      open: root.hasAttribute("open"),
+      ariaExpanded: root.getAttribute("aria-expanded"),
+      ariaPressed: root.getAttribute("aria-pressed"),
+      ariaSelected: root.getAttribute("aria-selected"),
+      text: (root.textContent || "").replace(/\s+/g, " ").trim().slice(0, 300),
+      controls: [...root.querySelectorAll("button, a[href], input, textarea, select, [role=button]")]
+        .slice(0, 40)
+        .map((control) => ({
+          tag: control.tagName,
+          visible: visible(control),
+          disabled: !!control.disabled || control.getAttribute("aria-disabled") === "true",
+          checked: "checked" in control ? !!control.checked : null,
+          expanded: control.getAttribute("aria-expanded"),
+          pressed: control.getAttribute("aria-pressed"),
+          selected: control.getAttribute("aria-selected"),
+          label: (control.getAttribute("aria-label") || control.textContent || control.getAttribute("value") || "").replace(/\s+/g, " ").trim().slice(0, 80),
+        })),
+    });
+    const region = element.parentElement || element;
+    const controlledId = element.getAttribute("aria-controls");
+    const controlled = controlledId ? document.getElementById(controlledId) : null;
+    return { wired, signature: JSON.stringify([describe(region), controlled ? describe(controlled) : null]) };
+  }).catch(() => ({ wired: false, signature: "detached" }));
+
+  return { url: page.url(), ...global, local: local.signature, wired: local.wired };
+}
+
+// Wait for a page to stop presenting an explicit loading state and for its semantic
+// surface to remain unchanged across a couple of samples. This is intentionally bounded:
+// live counters and animation-heavy pages still return evidence, marked unsettled.
+export async function waitForWebStability(page, { timeoutMs = 5_000, intervalMs = 250, stableSamples = 3 } = {}) {
+  const boundedTimeout = Math.max(250, Math.min(15_000, Number(timeoutMs) || 5_000));
+  const boundedInterval = Math.max(100, Math.min(1_000, Number(intervalMs) || 250));
+  const requiredSamples = Math.max(1, Math.min(5, Number(stableSamples) || 2));
+  const started = Date.now();
+  let previousSignature = "";
+  let matchingSamples = 0;
+  let latest = { busy: false, signature: "" };
+
+  while (Date.now() - started < boundedTimeout) {
+    latest = await page.evaluate(() => {
+      const visible = (element) => {
+        const style = window.getComputedStyle(element);
+        return style.visibility !== "hidden" && style.display !== "none" && element.getClientRects().length > 0;
+      };
+      const busySelector = "[aria-busy=true], [role=progressbar], .loading, .spinner, [class*=loading i], [class*=spinner i]";
+      const busyElement = [...document.querySelectorAll(busySelector)].some(visible);
+      const busyText = [...document.querySelectorAll("h1, h2, h3, p, [role=status]")]
+        .filter(visible)
+        .map((element) => (element.textContent || "").trim())
+        .some((text) => /^(loading|fetching|please wait|preparing|connecting)(?:[.…!]*|\s.*)$/i.test(text));
+      const bodyText = (document.body?.innerText || "").replace(/\s+/g, " ").trim().slice(0, 2_000);
+      const signature = JSON.stringify([
+        location.href,
+        document.querySelector("h1")?.textContent?.trim() || "",
+        document.title,
+        document.querySelectorAll("button, a[href], input, textarea, select, [role=button]").length,
+        bodyText,
+      ]);
+      return { busy: busyElement || busyText, signature };
+    }).catch(() => latest);
+
+    if (!latest.busy && latest.signature === previousSignature) matchingSamples += 1;
+    else matchingSamples = !latest.busy ? 1 : 0;
+    previousSignature = latest.signature;
+    if (!latest.busy && matchingSamples >= requiredSamples) {
+      return { settled: true, busy: false, elapsedMs: Date.now() - started };
+    }
+    await page.waitForTimeout(boundedInterval);
+  }
+  return { settled: false, busy: !!latest.busy, elapsedMs: Date.now() - started };
+}
+
+async function tapWebText(page, text, timeoutMs) {
+  const requested = String(text || "").trim();
+  if (!requested) return false;
+  const candidates = [
+    page.getByRole("button", { name: requested, exact: true }).first(),
+    page.getByRole("link", { name: requested, exact: true }).first(),
+    page.getByText(requested, { exact: true }).first(),
+  ];
+  for (const candidate of candidates) {
+    if (!(await candidate.isVisible().catch(() => false))) continue;
+    try {
+      await candidate.click({ timeout: Math.min(timeoutMs, 5_000) });
+      return true;
+    } catch {}
+  }
+  throw new Error(`Could not tap visible text “${requested}”`);
+}
 
 // npx installs Tapp into its own cache, so a plain import("playwright") only resolves
 // for repo-dev checkouts. Probe, in order: our own node_modules; the user's project
@@ -100,7 +299,7 @@ export function webBrowserLaunchOptions(environment = process.env) {
 // Focused one-screen inspection for the agent-facing `tapp open <url>` and `tapp tree <url>`
 // commands. This deliberately does no exploration or judgment; it opens exactly one page,
 // captures the visible semantic controls, and optionally takes one screenshot.
-export async function inspectWebPage({ url, timeoutMs = NAV_TIMEOUT_MS, screenshot = true }) {
+export async function inspectWebPage({ url, timeoutMs = NAV_TIMEOUT_MS, screenshot = true, tapText = "", waitForText = "" }) {
   let target;
   try { target = new URL(url); }
   catch { throw new Error("Web inspection needs a valid http(s) URL"); }
@@ -115,7 +314,20 @@ export async function inspectWebPage({ url, timeoutMs = NAV_TIMEOUT_MS, screensh
     page.setDefaultTimeout(boundedTimeout);
     const response = await page.goto(target.href, { waitUntil: "domcontentloaded", timeout: boundedTimeout });
     if (response && response.status() >= 400) throw new Error(`Could not open ${target.href}: HTTP ${response.status()}`);
-    await page.waitForTimeout(SETTLE_MS);
+    let stability = await waitForWebStability(page, { timeoutMs: Math.min(5_000, boundedTimeout) });
+    if (tapText) {
+      await tapWebText(page, tapText, boundedTimeout);
+      stability = await waitForWebStability(page, { timeoutMs: Math.min(5_000, boundedTimeout) });
+    }
+    if (waitForText) {
+      const requested = String(waitForText).trim();
+      try {
+        await page.getByText(requested, { exact: false }).first().waitFor({ state: "visible", timeout: boundedTimeout });
+      } catch {
+        throw new Error(`Timed out waiting for visible text “${requested}”`);
+      }
+      stability = await waitForWebStability(page, { timeoutMs: Math.min(5_000, boundedTimeout) });
+    }
     const observed = await page.evaluate(() => {
       const visible = (element) => element.offsetParent !== null;
       const controls = [...document.querySelectorAll("button, a[href], input, textarea, select, [role=button], [role=tab], [role=checkbox], [role=switch]")]
@@ -150,6 +362,8 @@ export async function inspectWebPage({ url, timeoutMs = NAV_TIMEOUT_MS, screensh
       screenTitle: webScreenTitle(observed, target.pathname || target.href),
       elements: observed.controls,
       image,
+      settled: stability.settled,
+      busy: stability.busy,
     };
   } finally {
     await browser.close().catch(() => {});
@@ -221,7 +435,9 @@ export async function exploreWeb({ url, maxActions = 40, timeoutSec = 300, outDi
 
   const { chromium } = await loadPlaywright();
   const browser = await chromium.launch(webBrowserLaunchOptions());
-  const page = await (await browser.newContext({ viewport: { width: 1280, height: 900 } })).newPage();
+  const context = await browser.newContext({ viewport: { width: 1280, height: 900 } });
+  await installWebListenerTracking(context);
+  const page = await context.newPage();
   page.setDefaultTimeout(NAV_TIMEOUT_MS);
 
   const deadline = Date.now() + timeoutSec * 1000;
@@ -231,14 +447,9 @@ export async function exploreWeb({ url, maxActions = 40, timeoutSec = 300, outDi
     emit("ISSUE", { type, severity, title, screen, ...(target ? { target } : {}) });
   };
 
-  // Request counter: cheap "did that click cause network activity" signal for the
-  // dead-button check (a button that fires a request is not dead).
-  let requestCount = 0;
-
   // Async defect listeners: attribute to whatever screen is current when they fire.
   let currentScreen = start.pathname;
   let lastActionTarget = "";
-  page.on("request", () => { requestCount += 1; });
   page.on("pageerror", (err) => issue("js_exception", "high", `Uncaught JS exception: ${String(err.message || err).slice(0, 120)}`, currentScreen));
   page.on("response", (res) => {
     try {
@@ -246,7 +457,7 @@ export async function exploreWeb({ url, maxActions = 40, timeoutSec = 300, outDi
       if (u.origin !== start.origin) return;
       if (res.status() >= 500) issue("network_error", "high", `${res.status()} from ${u.pathname.slice(0, 80)}`, currentScreen);
       else if (res.status() === 404 && res.request().resourceType() !== "document") {
-        issue("missing_asset", "medium", `404 asset: ${u.pathname.slice(0, 80)}`, currentScreen);
+        issue("missing_asset", "medium", `404 asset: ${u.pathname.slice(0, 80)}`, currentScreen, u.pathname);
       }
     } catch {}
   });
@@ -254,7 +465,9 @@ export async function exploreWeb({ url, maxActions = 40, timeoutSec = 300, outDi
     try {
       const u = new URL(req.url());
       if (u.origin !== start.origin) return;
-      issue("network_error", "medium", `Request failed: ${u.pathname.slice(0, 80)} (${req.failure()?.errorText || "?"})`, currentScreen);
+      const errorText = req.failure()?.errorText || "?";
+      if (!shouldReportWebRequestFailure(errorText)) return;
+      issue("network_error", "medium", `Request failed: ${u.pathname.slice(0, 80)} (${errorText})`, currentScreen, u.pathname);
     } catch {}
   });
 
@@ -269,7 +482,8 @@ export async function exploreWeb({ url, maxActions = 40, timeoutSec = 300, outDi
       : { target: start.pathname + start.search, visitKey: `pr-path:${target.id}`, action: `PR target ${target.node.name}`, fromScreen: null, prTarget: true, targetId: target.id, pathTarget: target }),
     ...normalizedSeeds.filter((target) => !targetRoutes.has(target)).map((target) => ({ target, action: `PR target ${target}`, fromScreen: null, prTarget: true })),
   ];
-  const screenshotFor = new Set();
+  const screenshotFor = new Map();
+  const placeholderLinksSeen = new Set();
   let actions = 0;
   let screenCount = 0;
   let lastScreen = null;
@@ -320,8 +534,45 @@ export async function exploreWeb({ url, maxActions = 40, timeoutSec = 300, outDi
         title: document.title.trim(),
         controlCount: document.querySelectorAll("a[href], button, [role=button], input, select, textarea").length,
         textLen: (document.body?.innerText || "").trim().length,
-        alertText: [...document.querySelectorAll("[role=alert], [class*=error i]")]
+        visualContentCount: [...document.querySelectorAll("img, picture, video, canvas, svg, iframe, object, embed")]
+          .filter((el) => {
+            const style = window.getComputedStyle(el);
+            return style.visibility !== "hidden" && style.display !== "none" && el.getClientRects().length > 0;
+          }).length,
+        alertText: [...document.querySelectorAll("[role=alert], [aria-live=assertive]")]
           .map((el) => el.textContent.trim()).filter(Boolean).join(" ").slice(0, 120),
+        errorCandidateTexts: [...document.querySelectorAll("h1, h2, h3, p, [data-error], [data-testid*=error i]")]
+          .filter((el) => el.offsetParent !== null)
+          .map((el) => (el.textContent || "").trim().slice(0, 240))
+          .filter(Boolean)
+          .slice(0, 40),
+        busy: [...document.querySelectorAll("[aria-busy=true], [role=progressbar], .loading, .spinner, [class*=loading i], [class*=spinner i]")]
+          .some((el) => {
+            const style = window.getComputedStyle(el);
+            return style.visibility !== "hidden" && style.display !== "none" && el.getClientRects().length > 0;
+          }) || [...document.querySelectorAll("h1, h2, h3, p, [role=status]")]
+          .filter((el) => el.offsetParent !== null)
+          .map((el) => (el.textContent || "").trim())
+          .some((text) => /^(loading|fetching|please wait|preparing|connecting)(?:[.…!]*|\s.*)$/i.test(text)),
+        placeholderLinks: [...document.querySelectorAll("a[href]")]
+          .filter((el) => el.offsetParent !== null)
+          .map((el, index) => {
+            const listenerKey = Symbol.for("tapp.clickListeners");
+            const dataHandler = [...el.attributes]
+              .some((attribute) => /^data-(action|toggle|target|modal|waitlist)(?:-|$)/i.test(attribute.name));
+            const svgPath = el.querySelector("svg path")?.getAttribute("d") || "";
+            return {
+              rawHref: el.getAttribute("href") || "",
+              label: (el.getAttribute("aria-label") || el.getAttribute("title") || el.innerText || el.textContent || "").replace(/\s+/g, " ").trim().slice(0, 100),
+              handlerHint: el.getAttribute("role") === "button"
+                || el.hasAttribute("onclick")
+                || typeof el.onclick === "function"
+                || !!el[listenerKey]?.size
+                || el.hasAttribute("aria-controls")
+                || dataHandler,
+              fingerprint: el.id || el.getAttribute("data-testid") || svgPath.slice(0, 80) || `link-${index + 1}`,
+            };
+          }),
         inputs,
         controls,
       };
@@ -332,7 +583,7 @@ export async function exploreWeb({ url, maxActions = 40, timeoutSec = 300, outDi
     const screen = webScreenTitle(info, key);
     const evidenceKey = `${key}::${screen}`;
     currentScreen = screen;
-    emit("STATE", { screen, url: key, elements: info.controlCount, role: webScreenRole(screen, info.inputs), controls: info.controls, inputs: info.inputs, settled: true });
+    emit("STATE", { screen, url: key, elements: info.controlCount, role: webScreenRole(screen, info.inputs), controls: info.controls, inputs: info.inputs, settled: !info.busy });
     const completedNavigation = pendingNavigation;
     const transitionFrom = webTransitionOrigin(completedNavigation, lastScreen);
     const transitionAction = completedNavigation?.action || lastActionTarget;
@@ -342,15 +593,28 @@ export async function exploreWeb({ url, maxActions = 40, timeoutSec = 300, outDi
     lastScreen = screen;
     if (completedNavigation?.prTarget) emit("PR_TARGET", { ...(completedNavigation.targetId ? { targetId: completedNavigation.targetId } : {}), route: completedNavigation.target, status: "observed", screen });
 
-    if (!screenshotFor.has(evidenceKey)) {
-      screenshotFor.add(evidenceKey);
+    const busyRouteEntry = !info.busy
+      ? [...screenshotFor.entries()].find(([, value]) => value.route === key && value.busy)
+      : null;
+    const existingKey = screenshotFor.has(evidenceKey) ? evidenceKey : busyRouteEntry?.[0];
+    const existingScreenshot = existingKey ? screenshotFor.get(existingKey) : null;
+    const shouldCapture = !existingScreenshot || (existingScreenshot.busy && !info.busy);
+    if (shouldCapture) {
+      const screenshotPath = existingScreenshot?.path || path.join(outDir, `state_${screenshotFor.size + 1}_${slug(screen)}.png`);
+      if (existingKey && existingKey !== evidenceKey) screenshotFor.delete(existingKey);
+      screenshotFor.set(evidenceKey, { path: screenshotPath, busy: info.busy, route: key });
       screenCount = screenshotFor.size;
-      await page.screenshot({ path: path.join(outDir, `state_${screenCount}_${slug(screen)}.png`) }).catch(() => {});
+      await page.screenshot({ path: screenshotPath }).catch(() => {});
       // Deterministic per-page detectors run once per distinct screen.
-      if (info.textLen < 10) issue("blank_screen", "high", "Page rendered no visible text", screen);
-      else if (info.alertText && ERROR_TEXT_RE.test(info.alertText)) issue("error_surface", "high", `Error shown: ${info.alertText.slice(0, 80)}`, screen);
-      else if (ERROR_TEXT_RE.test(await page.evaluate(() => (document.body?.innerText || "").slice(0, 4000)).catch(() => ""))) {
-        issue("error_surface", "high", "Error text visible on page", screen);
+      if (webPageAppearsBlank(info)) issue("blank_screen", "high", "Page rendered no visible content", screen);
+      else {
+        const errorText = webErrorSurfaceText({ alertText: info.alertText, candidateTexts: info.errorCandidateTexts });
+        if (errorText) issue("error_surface", "high", `Error shown: ${errorText.slice(0, 80)}`, screen);
+      }
+      for (const finding of webPlaceholderLinkFindings(info.placeholderLinks)) {
+        if (placeholderLinksSeen.has(finding.target)) continue;
+        placeholderLinksSeen.add(finding.target);
+        issue(finding.type, finding.severity, finding.title, screen, finding.target);
       }
     }
     return { key, screen, info };
@@ -370,7 +634,7 @@ export async function exploreWeb({ url, maxActions = 40, timeoutSec = 300, outDi
     emit("ACTION", { type: "login", target: "Sign in", screen, narrative: "Filled and submitted the sign-in form with the provided test credentials" });
     actions += 1;
     await submitWebLogin(page).catch(() => false);
-    await page.waitForTimeout(CLICK_SETTLE_MS * 2);
+    await waitForWebStability(page, { timeoutMs: Math.min(5_000, CLICK_SETTLE_MS * 6) });
     // Still on the login form after a submit = the sign-in failed — full stop. (A quiet
     // credential rejection often shows NO other symptom, so this must not be coupled to
     // whether some other detector happened to fire during the attempt.)
@@ -417,7 +681,6 @@ export async function exploreWeb({ url, maxActions = 40, timeoutSec = 300, outDi
       // we just left; observe() refines this to the page title once it settles.
       currentScreen = target;
       const nav = await page.goto(start.origin + target, { waitUntil: "domcontentloaded" }).catch((err) => ({ navError: String(err.message || err) }));
-      await page.waitForTimeout(SETTLE_MS);
       if (nav && nav.navError) {
         if (entry.prTarget) emit("PR_TARGET", { ...(entry.targetId ? { targetId: entry.targetId } : {}), ...(entry.pathTarget ? {} : { route: target }), status: "failed", error: nav.navError.slice(0, 160) });
         pendingNavigation = null;
@@ -425,6 +688,7 @@ export async function exploreWeb({ url, maxActions = 40, timeoutSec = 300, outDi
         progress();
         continue;
       }
+      await waitForWebStability(page);
       if (nav && typeof nav.status === "function" && nav.status() === 404) {
         issue("broken_link", "medium", `Broken link: ${target} → 404`, target);
       }
@@ -456,15 +720,17 @@ export async function exploreWeb({ url, maxActions = 40, timeoutSec = 300, outDi
               else if (selector.kind === "label") locator = page.getByText(selector.value, { exact: true }).first();
               else continue;
               if (await locator.isVisible().catch(() => false)) {
-                await locator.click({ timeout: Math.min(step.wait?.timeoutMs || NAV_TIMEOUT_MS, NAV_TIMEOUT_MS) }).catch(() => {});
-                acted = true;
-                break;
+                try {
+                  await locator.click({ timeout: Math.min(step.wait?.timeoutMs || NAV_TIMEOUT_MS, NAV_TIMEOUT_MS) });
+                  acted = true;
+                  break;
+                } catch {}
               }
             }
           }
           if (!acted) { pathError = `Observed control was not found: ${action.target}`; break; }
           pendingNavigation = { action: action.target, fromScreen: beforeScreen };
-          await page.waitForTimeout(CLICK_SETTLE_MS);
+          await waitForWebStability(page);
           ob = await observe() || ob;
           progress();
         }
@@ -502,37 +768,40 @@ export async function exploreWeb({ url, maxActions = 40, timeoutSec = 300, outDi
       const n = Math.min(await buttons.count().catch(() => 0), BUTTONS_PER_PAGE);
       for (let i = 0; i < n && actions < maxActions && Date.now() < deadline; i++) {
         const b = buttons.nth(i);
-        const label = ((await b.textContent().catch(() => "")) || (await b.getAttribute("value").catch(() => "")) || "button").trim().slice(0, 40) || "button";
+        const label = webControlLabel({
+          text: await b.textContent().catch(() => ""),
+          value: await b.getAttribute("value").catch(() => ""),
+          ariaLabel: await b.getAttribute("aria-label").catch(() => ""),
+          title: await b.getAttribute("title").catch(() => ""),
+          id: await b.getAttribute("id").catch(() => ""),
+        }).slice(0, 40);
         if (/log ?out|sign ?out|delete|remove/i.test(label)) continue; // don't destroy test state
-        const beforeUrl = page.url();
-        // Dead-button detection watches four real effect channels — DOM mutations, dialogs,
-        // network activity, and navigation — instead of the fragile innerHTML-length proxy
-        // (same length ≠ same page; unrelated tickers ≠ this button worked).
-        await page
-          .evaluate(() => {
-            window.__tappMut = 0;
-            if (window.__tappMo) window.__tappMo.disconnect();
-            window.__tappMo = new MutationObserver((muts) => { window.__tappMut += muts.length; });
-            window.__tappMo.observe(document.body, { childList: true, subtree: true, attributes: true, characterData: true });
-          })
-          .catch(() => {});
-        const dialogsBefore = await page.locator("dialog[open], [role=dialog], [aria-modal=true]").count().catch(() => 0);
-        const reqBefore = requestCount;
+        // Capture only durable, user-visible semantics around this control. A global
+        // MutationObserver is intentionally avoided: carousels, chat launchers, and live
+        // counters can mutate while an unrelated dead button is clicked, creating verdict jitter.
+        const beforeState = await captureWebControlState(page, b);
         actions += 1;
         lastActionTarget = label;
         emit("ACTION", { type: "tap", target: label, screen: webActionScreen(ob), narrative: `Tapped "${label}"` });
-        await b.click({ timeout: 3000 }).catch(() => {});
-        await page.waitForTimeout(CLICK_SETTLE_MS);
-        if (page.url() !== beforeUrl) {
+        let clickSucceeded = false;
+        try {
+          await b.click({ timeout: 3000 });
+          clickSucceeded = true;
+        } catch {}
+        if (!clickSucceeded) {
+          progress();
+          continue;
+        }
+        await waitForWebStability(page);
+        if (page.url() !== beforeState.url) {
           await observe();
           await page.goBack({ waitUntil: "domcontentloaded" }).catch(() => {});
-          await page.waitForTimeout(SETTLE_MS);
+          await waitForWebStability(page);
         } else {
-          const mutations = await page.evaluate(() => window.__tappMut || 0).catch(() => 0);
-          const dialogsAfter = await page.locator("dialog[open], [role=dialog], [aria-modal=true]").count().catch(() => 0);
-          const hadEffect = mutations > 0 || dialogsAfter !== dialogsBefore || requestCount > reqBefore;
+          const afterState = await captureWebControlState(page, b);
+          const hadEffect = webControlHadEffect({ wired: beforeState.wired, before: beforeState, after: afterState });
           if (!hadEffect) {
-            issue("unresponsive_element", "medium", `Button "${label}" does nothing`, ob.screen, label);
+            issue("unresponsive_element", "medium", `Button "${label}" has no wiring or observable effect`, ob.screen, label);
           } else {
             // Same-URL SPA transitions are real screens too; URL-only observation
             // under-counted coverage and made healthy applications inconclusive.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aarwitz/tapp",
-  "version": "0.16.2",
+  "version": "0.16.4",
   "mcpName": "io.github.aarwitz/tapp",
   "description": "Release contracts, autonomous QA, and evidence-backed CI gates for iOS, Android, and web.",
   "license": "MIT",