@aarwitz/tapp 0.17.20 → 0.17.22

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

package/AGENTS.md

@@ -1,7 +1,7 @@
 # Tapp agent playbook
 
 You (the agent) have Tapp: hands and eyes on real app surfaces — iOS simulators, Android
-emulators/devices, plus (beta) web apps in a real browser. Release judgment belongs only to Tapp's
+emulators/devices, plus web apps in a real browser. Release judgment belongs only to Tapp's
 repository-connected deterministic gate.
 
 ## No MCP connected? Just run the CLI
@@ -138,11 +138,17 @@ 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.
+- `tapp audit <url>` / `tapp_audit` is the read-only pass: it renders the page and reads it but never
+  clicks, types, submits, or hovers, so it is the one analysis safe to point at production or at a
+  site you do not own. 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),
+  images that failed to load, same-origin assets answering 404, 5xx/failed requests and uncaught JS
+  exceptions during load, same-origin links answering 404/410/5xx, mixed content, and a page wider
+  than its viewport. `--pages N` crawls same-origin links (robots.txt honoured, `--delay` between
+  pages); several URLs or `--urls FILE` batch sites. It writes a capture in the explore layout
+  (screenshots, per-finding evidence, `report.html`). Exit 1 when it finds anything. No findings
+  means the page is served without structural defects — not that the product works.
 - 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

@@ -5172,12 +5172,23 @@ class ExplorerTests: XCTestCase {
             // deleting only the prefix, then prove it is empty before inserting new text.
             element.typeKey("a", modifierFlags: .command)
             element.typeText(XCUIKeyboardKey.delete.rawValue)
-            if hasContent(), let remaining = element.value as? String {
-                // Some simulator keyboard configurations ignore Command-A. Clear on both
-                // sides of the cursor in that case; backspace alone leaves the suffix intact.
-                let count = remaining.utf16.count
-                element.typeText(String(repeating: XCUIKeyboardKey.delete.rawValue, count: count)
-                    + String(repeating: XCUIKeyboardKey.forwardDelete.rawValue, count: count))
+            // Command-A and forward delete are hardware-keyboard keys, and the simulator's
+            // hardware keyboard is disconnected by default — which is how CI runs. XCUITest
+            // cannot press a key the software keyboard does not have: the selection never
+            // happens, and forwardDelete's raw value (U+F728, a private-use character) is
+            // INSERTED as literal text. Clearing a 54-character field therefore left it holding
+            // 54 unrenderable glyphs and reported "could not be cleared". Backspace IS on the
+            // software keyboard, so clear with backspace alone, re-anchoring the caret past the
+            // end of the visible text each pass to reach a suffix that was scrolled out of view.
+            var passes = 0
+            while hasContent(), passes < 4 {
+                passes += 1
+                guard let remaining = element.value as? String else { break }
+                element.coordinate(withNormalizedOffset: CGVector(dx: 0.97, dy: 0.5)).tap()
+                element.typeText(String(repeating: XCUIKeyboardKey.delete.rawValue,
+                                        count: remaining.utf16.count + 2))
+                // An empty field reports its placeholder, so this compares unequal once cleared.
+                if (element.value as? String) == remaining { break }
             }
             let deadline = Date().addingTimeInterval(1.0)
             while hasContent() && Date() < deadline { Thread.sleep(forTimeInterval: 0.1) }

package/bin/tapp.js

@@ -163,7 +163,7 @@ const engineImport = () => import(path.join(packageRoot, "mcp-server", "src", "i
 
 function requireMacFor(what) {
   if (process.platform === "darwin") return;
-  console.error(`❌ ${what} requires macOS (Xcode + iOS simulator). The web beta runs anywhere: npx -y @aarwitz/tapp@latest explore https://localhost:3000`);
+  console.error(`❌ ${what} requires macOS (Xcode + iOS simulator). Web runs anywhere: npx -y @aarwitz/tapp@latest explore https://localhost:3000`);
   process.exit(1);
 }
 
@@ -287,7 +287,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",
+    audit: "tapp audit <url> [<url>...] [--urls FILE] [--pages N] [--delay MS] [--links N] [--json [FILE]] [--no-capture] [--device NAME] [--viewport WxH]\n  Read-only: renders each page and reads it, never clicks — safe to point at production or a site you do not own.\n  Finds dead controls, broken images/assets/links, 5xx/failed requests, JS exceptions, mixed content, horizontal overflow.\n  --pages N crawls same-origin links (robots.txt honoured, --delay between pages). Writes a capture with screenshots, evidence and report.html.\n  Exit codes: 0 nothing broken · 1 defects found · 2 usage/infrastructure",
     doctor: "tapp doctor [--json]\n  Exit codes: 0 environment healthy · 1 blocked (fix ❌ items)",
     install: "tapp install",
     mcp: "tapp mcp",
@@ -1513,30 +1513,71 @@ switch (command) {
 
   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.");
+    const urls = [...positionals];
+    if (typeof flags.urls === "string") {
+      try {
+        for (const line of fs.readFileSync(flags.urls, "utf8").split(/\r?\n/)) {
+          const trimmed = line.trim();
+          if (trimmed && !trimmed.startsWith("#")) urls.push(trimmed);
+        }
+      } catch (error) {
+        console.error(`❌ Could not read --urls ${flags.urls}: ${error.message}`);
+        process.exit(2);
+      }
+    }
+    if (!urls.length || urls.some((u) => !/^https?:\/\//i.test(u))) {
+      console.error(`usage: ${USAGE.audit}`);
       process.exit(2);
     }
+    const jsonMode = flags.json === true || typeof flags.json === "string";
+    const say = (line) => { if (!jsonMode || typeof flags.json === "string") console.log(line); };
     try {
-      const { auditWebPage } = await import(path.join(packageRoot, "mcp-server", "src", "web-explorer.js"));
-      const result = await auditWebPage({
-        url,
+      const { auditWebSite } = await import(path.join(packageRoot, "mcp-server", "src", "web-explorer.js"));
+      const { auditCaptureId } = await import(path.join(packageRoot, "mcp-server", "src", "web-audit.js"));
+      const capturesDir = flags["no-capture"] === true ? "" : path.join(tappHome, "captures");
+      const common = {
+        pages: Math.max(1, Number(flags.pages) || 1),
+        delayMs: flags.delay !== undefined ? Math.max(0, Number(flags.delay) || 0) : undefined,
+        linkCheckLimit: flags.links !== undefined ? Math.max(0, Number(flags.links) || 0) : undefined,
         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.`);
+        capturesDir,
+      };
+      const sites = [];
+      for (const [index, url] of urls.entries()) {
+        say(`🔎 Read-only audit — ${url}${common.pages > 1 ? ` (up to ${common.pages} pages)` : ""}`);
+        let site;
+        try {
+          site = await auditWebSite({ ...common, url, captureId: capturesDir ? `${auditCaptureId()}${urls.length > 1 ? `-${index + 1}` : ""}` : "",
+            onPage: (page, n) => say(`   ${n}. ${page.url} — ${page.controlsExamined} control(s), ${page.linksChecked.checked} link(s) checked, ${page.findings.length} finding(s)`) });
+        } catch (error) {
+          if (urls.length === 1) throw error;
+          site = { kind: "tapp-structural-audit", readOnly: true, url, error: error.message || String(error), pagesAudited: 0, findingCounts: { critical: 0, high: 0, medium: 0, low: 0, total: 0 }, pages: [], capture: null };
+          say(`   ❌ ${site.error}`);
         }
+        sites.push(site);
+        if (!jsonMode) {
+          const findings = site.pages.flatMap((p) => p.findings);
+          if (!site.error && !findings.length) console.log("   ✅ Nothing broken observed. Nothing was clicked — this is not a pass on behaviour.");
+          for (const finding of findings) console.log(`   ${finding.severity === "high" || finding.severity === "critical" ? "🔴" : finding.severity === "medium" ? "🟠" : "🟡"} [${finding.type}] ${finding.title}`);
+          if (site.robotsBlocked?.length) console.log(`   robots.txt kept ${site.robotsBlocked.length} page(s) out of the crawl`);
+          if (site.capture) console.log(`   📁 ${site.capture.path}\n   📄 ${site.capture.report}`);
+        }
+      }
+      const totalFindings = sites.reduce((n, site) => n + site.findingCounts.total, 0);
+      const payload = urls.length === 1 ? sites[0] : {
+        kind: "tapp-structural-audit", readOnly: true, sites,
+        totals: { sites: sites.length, pagesAudited: sites.reduce((n, site) => n + site.pagesAudited, 0), findings: totalFindings, failed: sites.filter((site) => site.error).length },
+      };
+      if (typeof flags.json === "string") {
+        fs.writeFileSync(flags.json, JSON.stringify(payload, null, 2));
+        console.log(`\n📄 Audit JSON: ${flags.json}`);
+      } else if (flags.json === true) {
+        console.log(JSON.stringify(payload, null, 2));
+      } else if (urls.length > 1) {
+        console.log(`\n${totalFindings} finding(s) across ${sites.length} site(s).`);
       }
-      process.exit(result.findings.length ? 1 : 0);
+      process.exit(totalFindings ? 1 : sites.some((site) => site.error) ? 2 : 0);
     } catch (error) {
       console.error(`❌ ${error.message || String(error)}`);
       process.exit(2);
@@ -2046,9 +2087,10 @@ 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)
+  tapp audit <url>...      Read-only audit — dead controls, broken images/links/assets, failed
+                           requests, JS exceptions, mixed content, overflow. Never clicks, so it
+                           is safe against production or a prospect's site (exit 1 on defects)
+                           (--pages N crawls same-origin · --urls FILE batches · --json [FILE])
 
 Repository & release:
   tapp init [repo]         Detect targets and write the application model + reviewable release plan

package/browser/app.css

@@ -176,24 +176,35 @@ dialog { width:min(720px,calc(100vw - 40px)); max-height:min(760px,calc(100vh -
 }
 
 /* Desktop-parity dark product skin. The component structure remains shared by
-   local and hosted Tapp; this palette follows the native Command Center. */
+   local and hosted Tapp; the palette comes from tokens.css so the hosted Studio,
+   the local Studio, and the macOS Command Center read as one product. */
 :root {
   color-scheme:dark;
-  --ink:#edf2f8; --muted:#929ba8; --faint:#687280; --line:#303844; --paper:#171c24; --wash:#20262f;
-  --green:#58a6ff; --green-2:#4f9cf3; --green-3:#7bb8ff; --lime:#102d4d; --amber:#e2a826;
-  --amber-bg:#302817; --red:#ff5c57; --red-bg:#392125; --blue:#58a6ff; --sidebar:#0c1118;
-  --shadow:0 18px 55px rgba(0,0,0,.28); --small-shadow:0 8px 24px rgba(0,0,0,.18);
+  --ink:var(--tapp-text); --muted:var(--tapp-text-soft); --faint:var(--tapp-text-faint);
+  --line:var(--tapp-border); --paper:var(--tapp-panel); --wash:var(--tapp-panel-2);
+  --green:var(--tapp-blue); --green-2:var(--tapp-blue-hover); --green-3:#7bb8ff;
+  --lime:var(--tapp-selected); --amber:var(--tapp-amber); --amber-bg:var(--tapp-amber-bg);
+  --red:var(--tapp-red); --red-bg:var(--tapp-red-bg); --blue:var(--tapp-blue);
+  --sidebar:var(--tapp-sidebar); --shadow:var(--tapp-shadow); --small-shadow:var(--tapp-shadow-small);
 }
-body { background:#0d1117; }
-.topbar { background:rgba(13,17,23,.96); border-color:var(--line); }
+body { background:var(--tapp-bg); font-family:var(--tapp-font); }
+code { font-family:var(--tapp-font-mono); }
+.topbar { background:rgba(7,16,23,.96); border-color:var(--tapp-border-strong); }
 .brand-mark { width:auto; background:transparent; color:var(--green); font-family:inherit; font-size:24px; }
 .mode-pill,.status-chip,.repository-switcher,.source-card,.panel,.decision-card,.target-card,.field,
 .live-frame-shell,.live-controls,.coverage-summary,.transition-list,.plan-item,.pipeline article,
 .evidence-card,.search-input,.github-repositories,.github-repositories button,.manual-action input,
 .run-row,.finding-row,.live-control { background:var(--paper); color:var(--ink); border-color:var(--line); }
 .source-onboarding { min-height:calc(100vh - 64px); }
-.source-card:hover,.source-card.dragging { border-color:var(--green-2); box-shadow:0 20px 56px rgba(0,0,0,.36); }
-.source-card.dragging,.target-card.selected,.run-row.selected,.finding-row.selected { background:#132237; }
+.source-card:hover,.source-card.dragging { border-color:var(--green-2); box-shadow:0 20px 56px rgba(0,0,0,.46); }
+.source-card.dragging,.target-card.selected,.run-row.selected,.finding-row.selected { background:var(--tapp-selected); }
+/* Controls match the Command Center: compact, 8px radius, muted surface. */
+button { border-radius:var(--tapp-radius); }
+button.primary { background:var(--tapp-blue); color:#fff; }
+button.primary:hover { background:var(--tapp-blue-hover); }
+button.secondary { color:var(--tapp-text-control); background:var(--tapp-control); border-color:var(--tapp-border); }
+button.secondary:hover,button.quiet:hover { background:var(--tapp-panel-3); }
+button.quiet { border-color:var(--tapp-border); color:var(--muted); }
 .platform-row span,.button-link { background:#131a23; border-color:#385a7c; color:var(--green); }
 button.primary { background:var(--green); color:#07111d; }
 button.primary:hover { background:#79b8ff; }

package/browser/index.html

@@ -7,6 +7,7 @@
   <meta name="tapp-api-base" content="">
   <meta name="tapp-login-url" content="">
   <title>Tapp</title>
+  <link rel="stylesheet" href="./assets/tokens.css">
   <link rel="stylesheet" href="./assets/app.css">
 </head>
 <body>

package/browser/tokens.css

@@ -0,0 +1,50 @@
+/* Tapp design tokens — the single source of truth for what Tapp looks like.
+   Extracted from the Command Center shell (website/) so the hosted Studio
+   (app.runtapp.com), the local `tapp app` Studio, and the macOS app read as one
+   product. Surfaces consume these variables; none should hardcode a palette. */
+:root {
+  color-scheme: dark;
+
+  /* Ground and surfaces, darkest to lightest */
+  --tapp-bg: #071017;
+  --tapp-bg-deep: #040b11;
+  --tapp-sidebar: #0b1218;
+  --tapp-sidebar-solid: #0c1117;
+  --tapp-panel: #0f1a22;
+  --tapp-panel-2: #111d26;
+  --tapp-panel-3: #192730;
+  --tapp-panel-soft: rgba(17, 22, 28, 0.8);
+  --tapp-control: #1a222b;
+
+  /* Lines */
+  --tapp-border: rgba(168, 182, 196, 0.12);
+  --tapp-border-strong: #343b43;
+
+  /* Type */
+  --tapp-text: #edf3f7;
+  --tapp-text-soft: #b7c6d1;
+  --tapp-text-faint: #7e8d99;
+  --tapp-text-control: #dce3e9;
+
+  /* Accent and status */
+  --tapp-blue: #1f79ff;
+  --tapp-blue-hover: #2d87ff;
+  --tapp-amber: #e2a826;
+  --tapp-amber-bg: #302817;
+  --tapp-red: #ff5c57;
+  --tapp-red-bg: #392125;
+  --tapp-selected: #132b44;
+
+  /* Depth */
+  --tapp-shadow: 0 18px 55px rgba(0, 0, 0, 0.42);
+  --tapp-shadow-small: 0 8px 24px rgba(0, 0, 0, 0.3);
+
+  /* Type families — Inter for UI, SF Mono for evidence and identifiers */
+  --tapp-font: Inter, ui-sans-serif, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+  --tapp-font-mono: "SFMono-Regular", ui-monospace, Consolas, Menlo, monospace;
+
+  /* Shell metrics */
+  --tapp-sidebar-width: 220px;
+  --tapp-radius: 8px;
+  --tapp-radius-lg: 12px;
+}

package/mcp-server/src/index.js

@@ -2729,7 +2729,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
       title: "Explore (autonomous)",
       description:
         "Autonomously explore iOS (appBundleId), Android (androidAppId), OR a web app " +
-        "(url — beta, requires Playwright installed) and return a structured EXPLORATION OBSERVATION. " +
+        "(url — requires Playwright installed) and return a structured EXPLORATION OBSERVATION. " +
         "Exploration OBSERVES — it surfaces findings + coverage + evidence; it does NOT render a ship " +
         "verdict or score. To gate a merge, run the deterministic gate (contracts + baseline via CI). " +
         "Use when the user wants to find bugs / observe what breaks — this " +
@@ -2756,7 +2756,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
           apkPath: { type: "string", description: "Android: optional APK to install before testing." },
           androidSerial: { type: "string", description: "Android: optional adb device serial; defaults to the first authorized device." },
           clearData: { type: "boolean", default: true, description: "Android: clear app data before launch for a repeatable starting state." },
-          url: { type: "string", description: "Web (beta): URL of the app to explore in a real browser (same-origin only; your own app/staging). Provide exactly one of appBundleId | url." },
+          url: { type: "string", description: "Web: URL of the app to explore in a real browser (same-origin only; your own app/staging). Provide exactly one of appBundleId | url." },
           watch: { type: "boolean", default: false, description: "Web only: open Tapp's controlled Chromium window and show a cursor/HUD for each exploration action. Evidence screenshots exclude the overlay." },
           device: { type: "string", description: "Web only: render as a Playwright device profile (e.g. \"iPhone 13\") — viewport, user agent, touch" },
           viewport: { type: "string", description: "Web only: explicit viewport WIDTHxHEIGHT (e.g. \"390x844\"); overrides the device profile's viewport" },
@@ -2809,6 +2809,34 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         },
       },
     },
+    {
+      name: "tapp_audit",
+      title: "Audit (read-only)",
+      description:
+        "Read-only audit of a web page or site: renders it and reads it, NEVER clicks, types, submits or hovers — " +
+        "the one analysis safe to point at production or at a site you do not own. Finds controls that were never " +
+        "alive (dead in-page anchors, placeholder links, aria-controls naming nothing, buttons with no handler/form/link), " +
+        "images that failed to load, same-origin assets answering 404, 5xx/failed requests and uncaught JS exceptions " +
+        "during load, same-origin links answering 404/410/5xx, mixed content, and a page wider than its viewport. " +
+        "pages > 1 crawls same-origin links breadth-first with robots.txt honoured. Writes a capture (screenshots, " +
+        "per-finding evidence, report.html) like an explore run. Returns {kind:'tapp-structural-audit', readOnly:true, " +
+        "pagesAudited, findingCounts, pages:[{url,title,controlsExamined,linksChecked,findings}], checkedFor, notChecked, capture}. " +
+        "An observation, never a verdict; absence of findings says the page is served without structural defects, not that the product works.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          authToken: { type: "string", description: "Required when TAPP_MCP_TOKEN is set" },
+          url: { type: "string", description: "http(s) URL of the page to audit (the crawl start page when pages > 1)" },
+          pages: { type: "integer", default: 1, minimum: 1, maximum: 200, description: "How many same-origin pages to audit at most (1 = this page only)" },
+          delayMs: { type: "integer", default: 1000, minimum: 0, description: "Pause between pages when crawling — be polite to sites you do not own" },
+          linkCheckLimit: { type: "integer", default: 30, minimum: 0, description: "Same-origin links to HEAD-check per page" },
+          device: { type: "string", description: "Playwright device profile, e.g. 'iPhone 13' — audit the mobile rendering" },
+          viewport: { type: "string", description: "WIDTHxHEIGHT viewport override" },
+          capture: { type: "boolean", default: true, description: "Write a capture directory (screenshots, evidence, report.html)" },
+        },
+        required: ["url"],
+      },
+    },
     {
       name: "tapp_init",
       title: "Inspect or explore a repository and create the Tapp application model and release plan",
@@ -3609,6 +3637,40 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     return richResult(L.join("\n"), summary);
   }
 
+  if (name === "tapp_audit") {
+    const unauthorized = ensureAuthorized(args);
+    if (unauthorized) return unauthorized;
+    if (!isNonEmptyString(args.url)) return errorResult("url is required");
+    try {
+      const { auditWebSite } = await import("./web-audit.js");
+      const site = await auditWebSite({
+        url: args.url,
+        pages: asInteger(args.pages, 1),
+        delayMs: asInteger(args.delayMs, 1000),
+        linkCheckLimit: asInteger(args.linkCheckLimit, 30),
+        device: isNonEmptyString(args.device) ? args.device : "",
+        viewport: isNonEmptyString(args.viewport) ? args.viewport : "",
+        capturesDir: args.capture === false ? "" : capturesDir,
+      });
+      const findings = site.pages.flatMap((p) => p.findings);
+      const c = site.findingCounts;
+      const lines = [
+        `🔎 Read-only audit of ${site.url} — ${site.pagesAudited} page(s), nothing clicked`,
+        findings.length
+          ? `${findings.length} defect(s): ${c.critical} critical · ${c.high} high · ${c.medium} medium · ${c.low} low`
+          : "✅ Nothing broken observed. Not a pass on behaviour — nothing was exercised.",
+        ...findings.slice(0, 25).map((f) => `  ${SEV[f.severity] || "·"} [${f.type}] ${f.title}${f.screen ? ` — on ${f.screen}` : ""}`),
+        ...(findings.length > 25 ? [`  … ${findings.length - 25} more in structuredContent`] : []),
+        ...(site.robotsBlocked?.length ? [`robots.txt kept ${site.robotsBlocked.length} page(s) out of the crawl`] : []),
+        ...(site.capture ? [`📁 ${site.capture.path}`, `📄 ${site.capture.report}`] : []),
+        "Next: to exercise the controls (clicks, forms) run tapp_explore — only on an environment you own.",
+      ];
+      return richResult(lines.join("\n"), site);
+    } catch (error) {
+      return errorResult(error.message || String(error));
+    }
+  }
+
   if (name === "tapp_explore" || name === "tapp_run_qa") { // tapp_run_qa: deprecated alias
     const unauthorized = ensureAuthorized(args);
     if (unauthorized) return unauthorized;
@@ -3616,7 +3678,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const wantsAndroid = isNonEmptyString(args.androidAppId);
     const targets = [wantsWeb, wantsAndroid, isNonEmptyString(args.appBundleId)].filter(Boolean).length;
     if (targets !== 1) {
-      return errorResult("Provide exactly one of appBundleId (iOS), androidAppId (Android), or url (web beta)");
+      return errorResult("Provide exactly one of appBundleId (iOS), androidAppId (Android), or url (web)");
     }
     if (args.watch === true && !wantsWeb) return errorResult("watch is currently available for web exploration only");
 

package/mcp-server/src/report.js

@@ -362,7 +362,7 @@ export function buildQaReport(markersFilePath, { platform = "ios", target = null
       "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)",
+      "only the first few visible buttons per page are probed (web)",
       "content & reachability regressions require a baseline",
     ];
     if (outbound?.mailtoSkipped === "egress-policy") notChecked.push("mailto address domains (MX lookups are skipped by the public-egress policy)");

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

@@ -0,0 +1,423 @@
+// Read-only web audit: render a page, read it, never click it.
+//
+// This is the one analysis safe to point at a site you do not own, which is what makes it the
+// primitive behind the outreach motion (find a prospect's broken site, show them proof). Everything
+// here is an observation of a page as served: structurally dead controls, assets that failed to
+// load, links that answer 404, mixed content, a layout wider than its viewport. No form is
+// submitted, no button pressed, no navigation beyond the pages the caller asked for.
+//
+// The capture it writes uses the same layout as an explore run (state_*.png at the root,
+// ocqa-markers.txt, report.html) so every existing consumer of a capture — `tapp report`, the
+// Studio, Clien's evidence videos — reads an audit without a second code path.
+import fs from "fs";
+import path from "path";
+import { createRequire } from "module";
+import {
+  NAV_TIMEOUT_MS, loadPlaywright, webBrowserLaunchOptions, webContextOptions, installWebListenerTracking,
+  waitForWebStability, captureElementEvidence, shouldReportWebRequestFailure, auditStructuralControls,
+  auditFindingsFromControls, slug,
+} from "./web-explorer.js";
+import { buildQaReport } from "./report.js";
+import { writeHtmlReport } from "./html-report.js";
+import { buildUiMapFromMarkers, writeUiMap } from "./ui-map.js";
+
+const require = createRequire(import.meta.url);
+const VERSION = (() => { try { return require("../../package.json").version; } catch { return "0.0.0"; } })();
+
+export const AUDIT_LINK_CHECK_LIMIT = 30;
+export const AUDIT_CRAWL_DELAY_MS = 1000;
+const LINK_CHECK_CONCURRENCY = 4;
+const LINK_CHECK_TIMEOUT_MS = 10_000;
+
+// What an audit does and does not look at. Spelled out so a report never borrows the exploration
+// run's "checked for" list and claims clicks that never happened.
+export function auditScope({ linksChecked = { total: 0, checked: 0 }, pages = 1 } = {}) {
+  const checkedFor = [
+    "controls that were never alive: dead in-page anchors, placeholder links, aria-controls naming nothing, buttons with no handler/form/link",
+    "images that failed to load",
+    "same-origin assets answering 404 and requests answering 5xx or failing during page load",
+    "uncaught JavaScript exceptions during page load",
+    "mixed content (http:// resources on an https:// page)",
+    "page wider than its viewport (horizontal scrolling) and a missing viewport meta tag",
+  ];
+  if (linksChecked.total) {
+    checkedFor.push(linksChecked.total > linksChecked.checked
+      ? `same-origin links answering 404/410/5xx (first ${linksChecked.checked} of ${linksChecked.total}, HEAD then GET)`
+      : "same-origin links answering 404/410/5xx (HEAD then GET)");
+  }
+  const notChecked = [
+    "anything that needs a click: nothing was pressed, typed, submitted, or hovered (run `tapp explore` on an environment you own for that)",
+    "off-site links (only same-origin links are fetched; outbound reachability is an explore check)",
+    "app-specific business logic, content accuracy, privacy, brand, visual quality",
+    pages > 1 ? `pages beyond the ${pages} audited` : "pages other than the one audited (pass --pages N to crawl same-origin links)",
+  ];
+  return { checkedFor, notChecked };
+}
+
+// robots.txt, the polite minimum: honour Disallow for `*` and for our own agent, longest match wins,
+// Allow beats Disallow at equal length. Unparseable or unreachable → everything allowed.
+export function parseRobots(text = "") {
+  const groups = [];
+  let current = null;
+  for (const raw of String(text).split(/\r?\n/)) {
+    const line = raw.replace(/#.*$/, "").trim();
+    if (!line) continue;
+    const m = line.match(/^([a-z-]+)\s*:\s*(.*)$/i);
+    if (!m) continue;
+    const field = m[1].toLowerCase();
+    const value = m[2].trim();
+    if (field === "user-agent") {
+      if (!current || current.rules.length) { current = { agents: [], rules: [] }; groups.push(current); }
+      current.agents.push(value.toLowerCase());
+    } else if ((field === "disallow" || field === "allow") && current) {
+      current.rules.push({ allow: field === "allow", prefix: value });
+    }
+  }
+  return groups;
+}
+
+export function robotsAllows(groups, pathname, agent = "tapp") {
+  const mine = groups.filter((g) => g.agents.some((a) => a === agent || agent.startsWith(a)));
+  const applicable = mine.length ? mine : groups.filter((g) => g.agents.includes("*"));
+  let best = null;
+  for (const group of applicable) {
+    for (const rule of group.rules) {
+      if (!rule.prefix) { if (!rule.allow && !best) best = { allow: true, len: 0 }; continue; }
+      const re = new RegExp("^" + rule.prefix.split("*").map((s) => s.replace(/[.+?^${}()|[\]\\]/g, "\\$&")).join(".*").replace(/\\\$$/, "$"));
+      if (re.test(pathname) && (!best || rule.prefix.length > best.len || (rule.prefix.length === best.len && rule.allow))) {
+        best = { allow: rule.allow, len: rule.prefix.length };
+      }
+    }
+  }
+  return best ? best.allow : true;
+}
+
+// Page-level health, read from the DOM after load. Flagged elements are tagged like the structural
+// scan does so the evidence shot is of the element the finding names.
+async function auditPageHealth(page) {
+  return page.evaluate(() => {
+    const findings = [];
+    let n = 0;
+    const tag = (el) => { n += 1; el.setAttribute("data-tapp-audit-health", String(n)); return `[data-tapp-audit-health="${n}"]`; };
+    const visible = (el) => el.getClientRects().length > 0;
+    for (const img of document.images) {
+      const src = img.getAttribute("src") || "";
+      if (!src || src.startsWith("data:")) continue;
+      if (img.complete && img.naturalWidth === 0) {
+        findings.push({ kind: "broken_image", src: src.slice(0, 160), alt: (img.getAttribute("alt") || "").slice(0, 80), selector: visible(img) ? tag(img) : null });
+      }
+    }
+    if (location.protocol === "https:") {
+      for (const el of document.querySelectorAll("img[src], script[src], iframe[src], video[src], audio[src], source[src], link[rel~=stylesheet][href]")) {
+        const value = el.getAttribute("src") || el.getAttribute("href") || "";
+        if (/^http:\/\//i.test(value)) findings.push({ kind: "mixed_content", tagName: el.tagName.toLowerCase(), src: value.slice(0, 160), selector: visible(el) ? tag(el) : null });
+      }
+    }
+    const doc = document.documentElement;
+    const overflow = Math.max(doc.scrollWidth, document.body ? document.body.scrollWidth : 0) - window.innerWidth;
+    if (overflow > 2) findings.push({ kind: "horizontal_overflow", overflow, viewport: window.innerWidth });
+    if (!document.querySelector('meta[name="viewport"]')) findings.push({ kind: "no_viewport_meta" });
+    const links = [];
+    for (const a of document.querySelectorAll("a[href]")) {
+      const href = a.getAttribute("href") || "";
+      if (!href || href.startsWith("#") || /^(mailto|tel|javascript|sms):/i.test(href)) continue;
+      let abs;
+      try { abs = new URL(href, location.href); } catch { continue; }
+      if (!/^https?:$/.test(abs.protocol)) continue;
+      abs.hash = "";
+      links.push({ href: abs.href, label: (a.getAttribute("aria-label") || a.textContent || "").replace(/\s+/g, " ").trim().slice(0, 80), sameOrigin: abs.origin === location.origin });
+    }
+    return { findings, links };
+  });
+}
+
+function healthFindings(raw = []) {
+  const out = [];
+  for (const h of raw) {
+    if (h.kind === "broken_image") {
+      out.push({ type: "broken_image", severity: "medium", title: `Image failed to load: ${h.src}${h.alt ? ` (alt “${h.alt}”)` : ""}`, target: h.src, selector: h.selector });
+    } else if (h.kind === "mixed_content") {
+      out.push({ type: "mixed_content", severity: "medium", title: `Mixed content: <${h.tagName}> loads ${h.src} over plain http on an https page (browsers block or warn)`, target: h.src, selector: h.selector });
+    } else if (h.kind === "horizontal_overflow") {
+      out.push({ type: "horizontal_overflow", severity: "low", title: `Page is ${h.overflow}px wider than the ${h.viewport}px viewport — it scrolls sideways on this screen size`, target: `overflow:${h.overflow}` });
+    } else if (h.kind === "no_viewport_meta") {
+      out.push({ type: "no_viewport_meta", severity: "low", title: "No <meta name=\"viewport\"> — phones render the page zoomed out at desktop width", target: "meta[name=viewport]" });
+    }
+  }
+  return out;
+}
+
+// HEAD each same-origin link (GET when HEAD is refused). A link the server cannot answer is
+// reported low — a WAF or rate limit answers that way too — while 404/410 and 5xx are the server's
+// own word.
+async function checkLinks(context, links, { limit, pageUrl }) {
+  const unique = new Map();
+  for (const link of links) {
+    if (!link.sameOrigin || link.href === pageUrl) continue;
+    if (!unique.has(link.href)) unique.set(link.href, link.label);
+  }
+  const targets = [...unique.entries()].slice(0, Math.max(0, limit));
+  const findings = [];
+  let cursor = 0;
+  const worker = async () => {
+    while (cursor < targets.length) {
+      const [href, label] = targets[cursor++];
+      const where = label ? `“${label}”` : href;
+      const pathOf = (() => { try { return new URL(href).pathname; } catch { return href; } })();
+      try {
+        let res = await context.request.fetch(href, { method: "HEAD", maxRedirects: 5, timeout: LINK_CHECK_TIMEOUT_MS, failOnStatusCode: false });
+        if ([405, 501, 403].includes(res.status())) {
+          res = await context.request.fetch(href, { method: "GET", maxRedirects: 5, timeout: LINK_CHECK_TIMEOUT_MS, failOnStatusCode: false });
+        }
+        const status = res.status();
+        if (status === 404 || status === 410) findings.push({ type: "broken_link", severity: "medium", title: `Link ${where} → ${pathOf} answers ${status}`, target: href, url: href });
+        else if (status >= 500) findings.push({ type: "broken_link", severity: "high", title: `Link ${where} → ${pathOf} answers ${status}`, target: href, url: href });
+      } catch (error) {
+        findings.push({ type: "broken_link", severity: "low", title: `Link ${where} → ${pathOf} could not be fetched (${String(error?.message || error).split("\n")[0].slice(0, 80)})`, target: href, url: href });
+      }
+    }
+  };
+  await Promise.all(Array.from({ length: Math.min(LINK_CHECK_CONCURRENCY, targets.length) }, worker));
+  findings.sort((a, b) => String(a.target).localeCompare(String(b.target)));
+  return { findings, total: unique.size, checked: targets.length };
+}
+
+// One page, inside an already-open context. Collects everything, then (if a capture is open) shoots
+// the page and each named element and appends the markers.
+async function auditOnePage(context, target, { timeoutMs, linkCheckLimit, capture }) {
+  const page = await context.newPage();
+  const bounded = Math.max(1000, Math.min(60_000, Number(timeoutMs) || NAV_TIMEOUT_MS));
+  page.setDefaultTimeout(bounded);
+  const origin = target.origin;
+  const loadFindings = [];
+  const seenLoad = new Set();
+  const loadIssue = (type, severity, title, key) => {
+    if (seenLoad.has(key)) return;
+    seenLoad.add(key);
+    loadFindings.push({ type, severity, title, target: key });
+  };
+  page.on("pageerror", (err) => loadIssue("js_exception", "high", `Uncaught JS exception: ${String(err.message || err).slice(0, 120)}`, `js:${String(err.message || err).slice(0, 120)}`));
+  page.on("response", (res) => {
+    try {
+      const u = new URL(res.url());
+      if (u.origin !== origin) return;
+      if (res.status() >= 500) loadIssue("network_error", "high", `${res.status()} from ${u.pathname.slice(0, 80)}`, u.pathname);
+      else if (res.status() === 404 && res.request().resourceType() !== "document") loadIssue("missing_asset", "medium", `404 asset: ${u.pathname.slice(0, 80)}`, u.pathname);
+    } catch { /* unparseable url */ }
+  });
+  page.on("requestfailed", (req) => {
+    try {
+      const u = new URL(req.url());
+      if (u.origin !== origin) return;
+      const errorText = req.failure()?.errorText || "?";
+      if (!shouldReportWebRequestFailure(errorText)) return;
+      loadIssue("network_error", "medium", `Request failed: ${u.pathname.slice(0, 80)} (${errorText})`, u.pathname);
+    } catch { /* unparseable url */ }
+  });
+
+  try {
+    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 auditStructuralControls(page);
+    const health = await auditPageHealth(page);
+    const links = await checkLinks(context, health.links, { limit: linkCheckLimit, pageUrl: page.url() });
+
+    const structural = auditFindingsFromControls(controls.dead).map((f, i) => ({ ...f, selector: controls.dead[i].selector }));
+    const findings = [...structural, ...healthFindings(health.findings), ...loadFindings, ...links.findings];
+    const screen = target.pathname + target.search;
+    for (const f of findings) { f.screen = screen; if (!f.url) f.url = page.url(); }
+
+    if (capture) {
+      capture.states += 1;
+      const stateName = `state_${capture.states}_${slug(target.pathname === "/" ? (controls.title || "home") : target.pathname)}.png`;
+      await page.screenshot({ path: path.join(capture.dir, stateName), fullPage: true }).catch(() => page.screenshot({ path: path.join(capture.dir, stateName) }).catch(() => {}));
+      capture.emit("STATE", { screen, url: page.url(), elements: controls.controlCount, role: "page", controls: controls.dead.map((d) => d.label).filter(Boolean).slice(0, 40), inputs: [], settled: true, screenshot: stateName });
+      for (const f of findings) {
+        if (f.selector) {
+          capture.evidence += 1;
+          const name = `evidence_${capture.evidence}_${slug(f.type)}.png`;
+          const shot = await captureElementEvidence(page, page.locator(f.selector), capture.dir, name);
+          if (shot) f.evidence = shot;
+        }
+        capture.emit("ISSUE", { type: f.type, severity: f.severity, title: f.title, screen, ...(f.target ? { target: f.target } : {}), url: f.url, ...(f.evidence ? { evidence: f.evidence } : {}) });
+      }
+    }
+    for (const f of findings) delete f.selector;
+
+    return {
+      url: page.url(),
+      title: controls.title,
+      controlsExamined: controls.controlCount,
+      linksChecked: { total: links.total, checked: links.checked },
+      findings,
+      links: health.links,
+    };
+  } finally {
+    await page.close().catch(() => {});
+  }
+}
+
+function openCapture(capturesDir, id) {
+  const dir = path.join(capturesDir, id);
+  fs.mkdirSync(dir, { recursive: true });
+  const markersFd = fs.openSync(path.join(dir, "ocqa-markers.txt"), "w");
+  return {
+    id, dir, states: 0, evidence: 0, markersFd,
+    emit(kind, payload) { fs.writeSync(markersFd, `OCQA_${kind}:${JSON.stringify(payload)}\n`); },
+    close() { try { fs.closeSync(markersFd); } catch { /* already closed */ } },
+  };
+}
+
+export function auditCaptureId(now = new Date()) {
+  const p = (n) => String(n).padStart(2, "0");
+  return `web-audit-${now.getFullYear()}${p(now.getMonth() + 1)}${p(now.getDate())}-${p(now.getHours())}${p(now.getMinutes())}${p(now.getSeconds())}`;
+}
+
+function finalizeCapture(capture, { startUrl, pages, findings, robotsBlocked, linksChecked }) {
+  capture.emit("COMPLETE", { actions: 0, screens: pages.length, credentialsProvided: false, credentialsUsed: false, timedOut: false, stop: "audit-complete", readOnly: true, robotsBlocked });
+  capture.close();
+  const markers = path.join(capture.dir, "ocqa-markers.txt");
+  const report = buildQaReport(markers, { platform: "web", target: startUrl });
+  if (!report) return null;
+  // The exploration report's coverage floor and wording assume clicks; an audit has none by design.
+  const scope = auditScope({ linksChecked, pages: pages.length });
+  const counts = report.deterministicFindingCounts || report.findingCounts || { critical: 0, high: 0, medium: 0, low: 0 };
+  Object.assign(report, {
+    kind: "tapp-structural-audit",
+    readOnly: true,
+    inconclusive: false,
+    runStatus: "completed",
+    stopReason: "audit-complete",
+    headline: findings.length === 0
+      ? `Read-only audit of ${pages.length} page(s) — nothing broken was observed. Nothing was clicked; this says the page is served without structural defects, not that the product works.`
+      : `${findings.length} defect(s) observed on ${pages.length} page(s) without clicking anything (${counts.critical} critical, ${counts.high} high, ${counts.medium} medium, ${counts.low} low).`,
+    checkedFor: scope.checkedFor,
+    notChecked: scope.notChecked,
+    conditionsNotReached: [],
+  });
+  fs.writeFileSync(path.join(capture.dir, "report.json"), JSON.stringify(report, null, 2));
+  // The capture-local UI map is what ties a page screenshot to the findings on that page for
+  // every consumer that reads explore captures (the Studio, Clien's evidence slides).
+  try { writeUiMap(path.join(capture.dir, "ui-map.json"), buildUiMapFromMarkers({ markersPath: markers, platform: "web", target: startUrl, runId: capture.id })); }
+  catch { /* the map is a convenience; the report and markers are the evidence */ }
+  writeHtmlReport(capture.dir, { report, label: "Read-only audit" });
+  return report;
+}
+
+// Audit a site: the start page and, with pages > 1, same-origin links discovered on audited pages
+// (breadth-first, robots.txt honoured, one request at a time with a pause between pages).
+export async function auditWebSite({
+  url, pages = 1, timeoutMs = NAV_TIMEOUT_MS, device = "", viewport = "",
+  linkCheckLimit = AUDIT_LINK_CHECK_LIMIT, delayMs = AUDIT_CRAWL_DELAY_MS,
+  capturesDir = "", captureId = "", onPage = null,
+}) {
+  let start;
+  try { start = new URL(url); }
+  catch { throw new Error("Audit needs a valid http(s) URL"); }
+  if (!/^https?:$/.test(start.protocol)) throw new Error("Audit needs a valid http(s) URL");
+  const maxPages = Math.max(1, Math.min(200, Number(pages) || 1));
+
+  const { chromium, devices } = await loadPlaywright();
+  const browser = await chromium.launch(webBrowserLaunchOptions(process.env, {}));
+  const capture = capturesDir ? openCapture(capturesDir, captureId || auditCaptureId()) : null;
+  try {
+    const contextOptions = webContextOptions({ device, viewport, devices });
+    // Identify ourselves to sites we do not own; the default UA is kept so rendering is unchanged.
+    const probe = await browser.newContext(contextOptions);
+    const defaultUa = contextOptions.userAgent || await (await probe.newPage()).evaluate(() => navigator.userAgent).catch(() => "");
+    await probe.close();
+    const context = await browser.newContext({ ...contextOptions, userAgent: `${defaultUa} tapp-audit/${VERSION} (+https://runtapp.com)`.trim() });
+    await installWebListenerTracking(context);
+    if (capture) capture.emit("CONTEXT", { ...(String(device || "").trim() ? { device: String(device).trim() } : {}), viewport: contextOptions.viewport, deviceScaleFactor: contextOptions.deviceScaleFactor ?? 1, mode: "audit", readOnly: true });
+
+    let robots = [];
+    if (maxPages > 1) {
+      try {
+        const res = await context.request.get(new URL("/robots.txt", start).href, { timeout: 5_000, failOnStatusCode: false });
+        if (res.ok()) robots = parseRobots(await res.text());
+      } catch { /* unreachable robots.txt: everything allowed */ }
+    }
+
+    const results = [];
+    const robotsBlocked = [];
+    const queued = new Set([start.href]);
+    const queue = [start];
+    let linksTotal = 0;
+    let linksChecked = 0;
+    while (queue.length && results.length < maxPages) {
+      const target = queue.shift();
+      if (results.length > 0) {
+        if (!robotsAllows(robots, target.pathname)) { robotsBlocked.push(target.href); continue; }
+        if (delayMs > 0) await new Promise((r) => setTimeout(r, delayMs));
+      }
+      let result;
+      try {
+        result = await auditOnePage(context, target, { timeoutMs, linkCheckLimit, capture });
+      } catch (error) {
+        if (results.length === 0) throw error;
+        result = { url: target.href, title: "", controlsExamined: 0, linksChecked: { total: 0, checked: 0 }, links: [],
+          findings: [{ type: "broken_link", severity: "medium", title: `Page ${target.pathname} did not open: ${String(error?.message || error).slice(0, 120)}`, target: target.href, url: target.href, screen: target.pathname }] };
+      }
+      linksTotal += result.linksChecked.total;
+      linksChecked += result.linksChecked.checked;
+      const { links, ...pageResult } = result;
+      results.push(pageResult);
+      if (typeof onPage === "function") onPage(pageResult, results.length);
+      // A link the HEAD check already found broken is reported; opening it would only repeat the finding.
+      const broken = new Set(pageResult.findings.filter((f) => f.type === "broken_link").map((f) => f.target));
+      for (const link of links) {
+        if (!link.sameOrigin || queued.has(link.href) || broken.has(link.href) || queued.size >= maxPages * 4) continue;
+        let next;
+        try { next = new URL(link.href); } catch { continue; }
+        if (/\.(pdf|zip|png|jpe?g|gif|svg|webp|mp4|mp3|css|js|xml|ico)$/i.test(next.pathname)) continue;
+        queued.add(next.href);
+        queue.push(next);
+      }
+    }
+
+    const findings = results.flatMap((r) => r.findings);
+    const bySeverity = { critical: 0, high: 0, medium: 0, low: 0 };
+    for (const f of findings) if (f.severity in bySeverity) bySeverity[f.severity] += 1;
+    const scope = auditScope({ linksChecked: { total: linksTotal, checked: linksChecked }, pages: results.length });
+    const summary = {
+      kind: "tapp-structural-audit",
+      readOnly: true,
+      url: start.href,
+      pagesAudited: results.length,
+      pagesQueued: queue.length,
+      robotsBlocked,
+      findingCounts: { ...bySeverity, total: findings.length },
+      checkedFor: scope.checkedFor,
+      notChecked: scope.notChecked,
+      pages: results,
+      capture: null,
+    };
+    if (capture) {
+      finalizeCapture(capture, { startUrl: start.href, pages: results, findings, robotsBlocked, linksChecked: { total: linksTotal, checked: linksChecked } });
+      summary.capture = { id: capture.id, path: capture.dir, report: path.join(capture.dir, "report.html") };
+      fs.writeFileSync(path.join(capture.dir, "audit.json"), JSON.stringify(summary, null, 2));
+    }
+    return summary;
+  } finally {
+    if (capture) capture.close();
+    await browser.close().catch(() => {});
+  }
+}
+
+// One page. The shape existing callers and tests rely on, plus `capture` when a captures dir is given.
+export async function auditWebPage({ url, timeoutMs = NAV_TIMEOUT_MS, device = "", viewport = "", linkCheckLimit = AUDIT_LINK_CHECK_LIMIT, capturesDir = "", captureId = "" }) {
+  const site = await auditWebSite({ url, pages: 1, timeoutMs, device, viewport, linkCheckLimit, capturesDir, captureId });
+  const page = site.pages[0];
+  return {
+    url: page.url,
+    title: page.title,
+    controlsExamined: page.controlsExamined,
+    linksChecked: page.linksChecked,
+    findings: page.findings,
+    checkedFor: site.checkedFor,
+    notChecked: site.notChecked,
+    capture: site.capture,
+  };
+}

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

@@ -1,4 +1,4 @@
-// Web exploration driver (beta) — the second platform behind the OCQA marker protocol.
+// Web exploration driver — the second platform behind the OCQA marker protocol.
 //
 // Drives a real browser via Playwright and emits the SAME OCQA_* marker lines the iOS
 // XCUITest harness emits, into the same captures/<id>/ocqa-markers.txt layout — so the
@@ -21,7 +21,7 @@ import { createRequire } from "module";
 import { execFileSync } from "child_process";
 
 const CLICK_SETTLE_MS = 700;
-const NAV_TIMEOUT_MS = 15_000;
+export const NAV_TIMEOUT_MS = 15_000;
 const BUTTONS_PER_PAGE = 4;
 const OUTBOUND_LINK_LIMIT = 10;
 const WATCH_ACTION_DELAY_MS = 350;
@@ -136,7 +136,7 @@ function cssAttrEscape(value) {
   return String(value).replace(/["\\]/g, (c) => "\\" + c);
 }
 
-async function installWebListenerTracking(context) {
+export 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
@@ -626,7 +626,7 @@ export function webScreenRole(screen, inputs = []) {
   return "screen";
 }
 
-function slug(s) {
+export function slug(s) {
   return String(s).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 40) || "page";
 }
 
@@ -1212,122 +1212,106 @@ export function auditFindingsFromControls(controls = []) {
   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();
-      // 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);
-          }
+// The structural scan, run inside the page: every control that was never alive, WITHOUT
+// interacting with any. Each flagged element is tagged with data-tapp-audit="<n>" so evidence can be
+// shot of exactly that element (a bare tag-name selector would photograph the first match instead).
+export async function auditStructuralControls(page) {
+  return 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();
+    // 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; }
-      });
+    };
+    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]);
-        }
+    // 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 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;
-        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; }
+    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({ element: el, 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({ element: el, 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({ element: el, kind: "dead_anchor", label, selector: selectorFor(el), href, fragment });
         }
-        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) });
+        continue;
       }
-      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(() => {});
-  }
+      // 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 && opensSomethingOnHoverOrFocus(el)) wired = true;
+      if (!wired && claimedByDelegate(el)) wired = true;
+      if (!wired) dead.push({ element: el, kind: "unwired_control", label, selector: selectorFor(el) });
+    }
+
+    for (let i = 0; i < dead.length; i += 1) {
+      if (dead[i].element) { dead[i].element.setAttribute("data-tapp-audit", String(i + 1)); dead[i].selector = `[data-tapp-audit="${i + 1}"]`; delete dead[i].element; }
+    }
+    return { dead, controlCount: document.querySelectorAll("a[href], button, [role=button]").length, title: document.title };
+  });
 }
+
+export { auditWebPage, auditWebSite } from "./web-audit.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aarwitz/tapp",
-  "version": "0.17.20",
+  "version": "0.17.22",
   "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",
@@ -89,7 +89,7 @@
     "mobile"
   ],
   "scripts": {
-    "test": "node --test tests/report.test.js tests/regression.test.js tests/engine.test.js tests/project-config.test.js tests/application-model.test.js tests/ui-map.test.js tests/focused-navigation.test.js tests/task-runtime.test.js tests/release-contract.test.js tests/pr-selection.test.js tests/flow-runtime.test.js tests/web-explorer.test.js tests/web-session.test.js tests/web-link-audit.test.js tests/web-flow.test.js tests/scenario-runtime.test.js tests/android-driver.test.js tests/android-explorer.test.js tests/android-flow.test.js tests/android-primitives-protocol.test.js tests/managed-web.test.js tests/product-operations.test.js tests/browser-product.test.js tests/browser-onboarding.test.js tests/managed-operation.test.js tests/cloud-runner.test.js tests/ci-setup.test.js tests/ci-install.test.js tests/cli.test.js tests/mcp-workspace.test.js tests/action.test.js tests/package-surface.test.js tests/agent-surface.test.js tests/presentation-contract.test.js tests/landing-brand.test.js tests/ci-gate.test.js tests/ci-report.test.js tests/desktop-protocol.test.js tests/ios-flow-protocol.test.js tests/feedback-triage-0919.test.js vscode-extension/test/bridge.test.js",
+    "test": "node --test tests/report.test.js tests/regression.test.js tests/engine.test.js tests/project-config.test.js tests/application-model.test.js tests/ui-map.test.js tests/focused-navigation.test.js tests/task-runtime.test.js tests/release-contract.test.js tests/pr-selection.test.js tests/flow-runtime.test.js tests/web-explorer.test.js tests/web-session.test.js tests/web-link-audit.test.js tests/web-audit.test.js tests/web-flow.test.js tests/scenario-runtime.test.js tests/android-driver.test.js tests/android-explorer.test.js tests/android-flow.test.js tests/android-primitives-protocol.test.js tests/managed-web.test.js tests/product-operations.test.js tests/browser-product.test.js tests/browser-onboarding.test.js tests/managed-operation.test.js tests/cloud-runner.test.js tests/ci-setup.test.js tests/ci-install.test.js tests/cli.test.js tests/mcp-workspace.test.js tests/action.test.js tests/package-surface.test.js tests/agent-surface.test.js tests/presentation-contract.test.js tests/landing-brand.test.js tests/ci-gate.test.js tests/ci-report.test.js tests/desktop-protocol.test.js tests/ios-flow-protocol.test.js tests/feedback-triage-0919.test.js vscode-extension/test/bridge.test.js",
     "test:browser-journey": "node --test tests/browser-journey.test.js",
     "test:browser-native": "TAPP_RUN_NATIVE_BROWSER=1 node --test tests/browser-native-journey.test.js"
   }

package/skills/tapp/SKILL.md

@@ -43,7 +43,7 @@ than starting another broad exploration. If `.tapp/ui-map.json` does not exist y
 with `init . --explore`; source alone can locate a surface but cannot authorize unobserved taps.
 Targets may be a repository path, Xcode container, `.app`, iOS bundle id, APK plus Android app id,
 or owned HTTP(S) URL. Never explore a third-party web property without authorization: exploration
-clicks and types.
+clicks and types. For production or a site you do not own use `audit` / `tapp_audit` — read-only.
 
 ## Navigate like a source-connected expert