@aarwitz/tapp 0.17.7 → 0.17.8

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

package/AGENTS.md

@@ -133,6 +133,10 @@ 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.
+- 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
+  be pointed at production. Supplying credentials is the explicit opt-in that enables sign-in.
 - Diff two runs: pass the previous run's `findings` as `baselineFindings` → you get a
   `regression` **comparison** (`new` / `persisting` / `resolved`) — an observation, not a gate. To gate
   a merge on regressions, run the CI gate (`tapp ci` / the GitHub Action).

package/Harness/OCQAHarnessUITests/ExplorerTests.swift

@@ -1327,10 +1327,16 @@ class ExplorerTests: XCTestCase {
             beelineToTarget(target: targetScreen, route: route, actionCount: &actionCount, maxActions: maxActions)
         }
 
+        // Honest stop accounting: "action-budget" only survives when the while-condition itself
+        // ends the loop; every break records what actually stopped exploration so the report can
+        // say "navigation-trap" or "frontier-drained" instead of blessing a 15/20 run "completed".
+        var explorationStopCause = "action-budget"
+        var leftAppObservations = 0
         while actionCount < maxActions {
             // Subtract time spent paused for interactive input so human typing never eats the budget.
             if Date().timeIntervalSince(startTime) - totalWaitSeconds > timeoutSeconds {
                 print("OCQA_STATE:timeout_reached")
+                explorationStopCause = "time-budget"
                 break
             }
 
@@ -1374,6 +1380,32 @@ class ExplorerTests: XCTestCase {
                 }
             }
 
+            // ---- Left-app handoff: an observation, not a defect ----
+            // A tapped control can legitimately hand the user to a system surface or another
+            // app (mail composer, Settings, App Store, share sheet). Without this check the
+            // next tree read sees a backgrounded app, titles the screen "Unknown", and the
+            // hang/blank detectors file false HIGH findings (field report № 6 #26). Record
+            // the handoff against the action that caused it, come back, and keep exploring.
+            if app.state != .runningForeground {
+                leftAppObservations += 1
+                let causeAction = pendingTransitionFrom?.actionKey ?? "previous action"
+                let causeScreen = pendingTransitionFrom?.title ?? "Unknown"
+                print("OCQA_ACTION:{\"type\":\"left_app\",\"target\":\"\(escapeJSON(causeAction))\",\"screen\":\"\(escapeJSON(causeScreen))\",\"step\":\(actionCount),\"narrative\":\"\(escapeJSON("'\(causeAction)' handed off to a system surface or another app — returning to the app under test."))\"}")
+                pendingTransitionFrom = nil
+                app.activate()
+                _ = app.wait(for: .runningForeground, timeout: 5)
+                Thread.sleep(forTimeInterval: 1.0)
+                if app.state == .runningForeground {
+                    emitProgress(action: actionCount, maxActions: maxActions, states: visitedStates.count)
+                    continue
+                }
+                if leftAppObservations >= 3 {
+                    explorationStopCause = "left-app-unrecovered"
+                    break
+                }
+                continue
+            }
+
             var elements = readUITree(app)
             if elements.isEmpty {
                 // App may have gone to background, crashed, or be unresponsive.
@@ -1399,6 +1431,7 @@ class ExplorerTests: XCTestCase {
                             print("OCQA_ISSUE:{\"type\":\"crash\",\"severity\":\"critical\",\"title\":\"\(escapeJSON("App crashed during \(where_)"))\",\"screen\":\"\(escapeJSON(where_))\",\"step\":\(actionCount)}")
                         }
                     }
+                    explorationStopCause = "app-crashed"
                     break
                 }
             }
@@ -1528,6 +1561,7 @@ class ExplorerTests: XCTestCase {
                     emitProgress(action: actionCount, maxActions: maxActions, states: visitedStates.count)
                     continue
                 }
+                explorationStopCause = "stuck-no-progress"
                 break
             }
 
@@ -1554,6 +1588,7 @@ class ExplorerTests: XCTestCase {
             // for an impossible back path or expecting credentials to persist after logout.
             if authSucceeded && detectedInputs.contains(where: { $0.secure }) {
                 print("OCQA_STATE:auth_cycle_complete screen=\(escapedTitle) step=\(actionCount)")
+                explorationStopCause = "auth-cycle-complete"
                 break
             }
 
@@ -1844,6 +1879,7 @@ class ExplorerTests: XCTestCase {
                     // All tab positions tried — truly stuck
                     print("OCQA_STATE:truly_stuck_dead_end screen=\(escapedTitle) step=\(actionCount)")
                     emitNavigationTrap(titleStr: titleStr, escapedTitle: escapedTitle, step: actionCount, reported: &reportedIssueKeys, issues: &issues)
+                    explorationStopCause = "navigation-trap"
                     break
                 }
 
@@ -2190,6 +2226,7 @@ class ExplorerTests: XCTestCase {
                     // Truly stuck — break
                     print("OCQA_STATE:truly_stuck screen=\(escapedTitle) step=\(actionCount)")
                     emitNavigationTrap(titleStr: titleStr, escapedTitle: escapedTitle, step: actionCount, reported: &reportedIssueKeys, issues: &issues)
+                    explorationStopCause = "navigation-trap"
                     break
                 }
             }
@@ -2201,6 +2238,23 @@ class ExplorerTests: XCTestCase {
                                             persistentThreshold: persistentThreshold,
                                             screenBounds: screenBounds)
 
+            // ---- Credential-surface policy: catalogue, don't exercise (parity with web). ----
+            // Without explicitly supplied credentials — or interactive overrides for this screen —
+            // a login/signup surface is evidence, not a playground: typing sample values and
+            // tapping Sign In / Forgot Password fires real requests against whatever backend the
+            // build points at (production, for a bare-app run). Fields are still catalogued into
+            // STATE, the report says sign-in was not checked, and navigation away stays allowed.
+            let credentialFlowLocked = (screenRole == "login" || screenRole == "signup" || detectedInputs.contains { $0.secure })
+                && (testEmail.isEmpty || testPassword.isEmpty)
+                && !detectedInputs.contains(where: { !hasNoOverride(key: $0.key, screen: titleStr, in: inputOverrides) })
+            if credentialFlowLocked {
+                if !reportedIssueKeys.contains("credlock:\(titleStr)") {
+                    reportedIssueKeys.insert("credlock:\(titleStr)")
+                    print("OCQA_STATE:credential_form_catalogued screen=\(escapedTitle) fields=\(detectedInputs.count)")
+                }
+                sorted = sorted.filter { !isTextField($0.type) && !isCredentialFlowControl($0) }
+            }
+
             // ---- Form-completion steering ----
             // A half-filled form is one tap from progress (submit) or oblivion (Close/Cancel
             // discards everything typed). While the screen has unfilled text fields, fill the
@@ -2214,8 +2268,8 @@ class ExplorerTests: XCTestCase {
             // screen or it abandons a form whose remaining field the pool has dropped (observed:
             // signup's Confirm Password missing from the pool while hittable in the tree).
             // Termination is per-field via typedFieldKeys, so this can never loop.
-            let treeHasFields = elements.contains(where: { isTextField($0.type) })
-            let unfilledFields = elements.filter {
+            let treeHasFields = !credentialFlowLocked && elements.contains(where: { isTextField($0.type) })
+            let unfilledFields = credentialFlowLocked ? [SimpleElement]() : elements.filter {
                 isTextField($0.type) && $0.isEnabled && $0.isHittable
                     && fieldLooksUnfilled($0, screen: titleStr, typedKeys: typedFieldKeys)
             }
@@ -2287,7 +2341,7 @@ class ExplorerTests: XCTestCase {
                 if !numericCells.isEmpty { sorted = others + numericCells }
             }
 
-            guard let target = sorted.first else { break }
+            guard let target = sorted.first else { explorationStopCause = "frontier-drained"; break }
 
             if !isTextField(target.type) {
                 dismissKeyboardIfNeeded()
@@ -2360,6 +2414,7 @@ class ExplorerTests: XCTestCase {
                                        desc: "The app terminated after \(actionType) '\(targetName)' on '\(titleStr)' and did not recover on relaunch."))
                         print("OCQA_ISSUE:{\"type\":\"crash\",\"severity\":\"critical\",\"title\":\"\(escapeJSON("App crashed after \(actionType) on \(titleStr)"))\",\"screen\":\"\(escapedTitle)\",\"control\":\"\(escapedTarget)\",\"step\":\(actionCount)}")
                     }
+                    explorationStopCause = "app-crashed"
                     break
                 }
                 print("OCQA_STATE:app_reactivated step=\(actionCount)")
@@ -2479,6 +2534,7 @@ class ExplorerTests: XCTestCase {
                                        desc: "App left foreground after: \(actionDesc)"))
                         print("OCQA_ISSUE:{\"type\":\"crash\",\"severity\":\"critical\",\"title\":\"App not recoverable\",\"action\":\"\(escapedTarget)\",\"step\":\(actionCount)}")
                     }
+                    explorationStopCause = "app-crashed"
                     break
                 }
                 print("OCQA_STATE:app_reactivated step=\(actionCount)")
@@ -2529,7 +2585,7 @@ class ExplorerTests: XCTestCase {
         let uniqueScreens = screenTitles.values
         let screenList = Array(Set(uniqueScreens)).sorted().joined(separator: ",")
         didEmitComplete = true
-        print("OCQA_COMPLETE:{\"actions\":\(actionCount),\"states\":\(visitedStates.count),\"issues\":\(issues.count),\"screens\":\"\(screenList)\"}")
+        print("OCQA_COMPLETE:{\"actions\":\(actionCount),\"states\":\(visitedStates.count),\"issues\":\(issues.count),\"screens\":\"\(screenList)\",\"stop\":\"\(explorationStopCause)\",\"timedOut\":\(explorationStopCause == "time-budget" ? "true" : "false")}")
 
         let finalScreenshot = app.screenshot()
         let finalAttachment = XCTAttachment(screenshot: finalScreenshot)
@@ -3380,6 +3436,19 @@ class ExplorerTests: XCTestCase {
 
     /// Dismiss-style controls (Close/Cancel/X) that discard a form in progress. Deprioritized —
     /// never excluded — while unfilled fields remain, so they stay available as an escape hatch.
+    /// Any control that advances a credential flow: submitting, account recovery, account
+    /// creation, or third-party auth. Used by the credential-surface lock — none of these may
+    /// fire when no credentials were supplied, because each one sends real traffic to the
+    /// app's live backend. Navigation controls (tabs, Skip, Continue as guest) do not match.
+    private func isCredentialFlowControl(_ element: SimpleElement) -> Bool {
+        if isLikelySubmitControl(element) { return true }
+        let text = (element.label + " " + element.identifier).lowercased()
+        let flowTokens = ["forgot", "reset password", "recover", "with apple", "with google",
+                          "with facebook", "create account", "sign up", "verification code",
+                          "magic link", "resend"]
+        return flowTokens.contains(where: { text.contains($0) })
+    }
+
     private func isDismissControl(_ element: SimpleElement) -> Bool {
         let label = element.label.trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
         let id = element.identifier.trimmingCharacters(in: .whitespacesAndNewlines).lowercased()

package/README.md

@@ -29,10 +29,11 @@ Supported targets:
 |---|---|
 | iOS | Simulator on macOS with Xcode; driven through XCUITest and accessibility |
 | Android | Connected emulator or device with `adb`; driven through UIAutomator |
-| Web (beta) | Owned browser app in Playwright Chromium |
+| Web | Owned browser app in Playwright Chromium |
+| Windows desktop | WPF, WinForms, and WinUI apps through Windows UI Automation — early runs are set up through the pilot |
 
-Windows can host Android and web testing when their prerequisites are installed. Windows desktop
-UI applications such as WinForms, WPF, and WinUI are not currently Tapp targets.
+Windows hosts Android and web testing when their prerequisites are installed, and is the home of
+the Windows desktop target.
 
 ## Give Tapp to your coding agent
 
@@ -173,7 +174,7 @@ npx -y @aarwitz/tapp@latest apps            # what's installed on the simulator
 npx -y @aarwitz/tapp@latest build [dir]     # just build + install (scheme auto-detected)
 ```
 
-Web (beta): `npx -y @aarwitz/tapp@latest explore http://localhost:3000` *(one-time setup:
+Web: `npx -y @aarwitz/tapp@latest explore http://localhost:3000` *(one-time setup:
 `npm i -g playwright && npx playwright install chromium`)*. Add `--watch` to open Tapp's controlled,
 isolated Chromium window and follow its clicks with an on-page pointer/action label. Tapp hides that
 watch UI from saved evidence screenshots and does not automate your personal/default browser profile.
@@ -348,7 +349,7 @@ jobs:
     timeout-minutes: 45
     steps:
       - uses: actions/checkout@v4
-      - uses: aarwitz/tapp@v0.17.7 # or pin the reviewed release commit SHA
+      - uses: aarwitz/tapp@v0.17.8 # or pin the reviewed release commit SHA
         with:
           project: MyApp.xcodeproj # or MyApp.xcworkspace
           scheme: MyApp
@@ -398,7 +399,7 @@ Android CI runs on Linux with an emulator/device already connected. The Action c
 or accept a prebuilt one:
 
 ```yaml
-- uses: aarwitz/tapp@v0.17.7 # or pin the reviewed release commit SHA
+- uses: aarwitz/tapp@v0.17.8 # or pin the reviewed release commit SHA
   with:
     platform: android
     android-app-id: com.acme.app
@@ -437,7 +438,7 @@ Every driver speaks one protocol: structured `OCQA_*` markers (state, actions, i
 transitions) that the engine parses into trees, screenshots, findings, coverage, and the gate outcome.
 On **iOS**, a generic **XCUITest harness** attaches to any app by bundle id — no SDK or app code
 changes — and acts through the accessibility tree. On **Android**, ADB + UIAutomator provide the
-same black-box driver contract. On **web** (beta), a deterministic **Playwright crawler** does the
+same black-box driver contract. On **web**, a deterministic **Playwright crawler** does the
 same in a real browser. Same detectors' spirit,
 same dedup, same regression gate, same honest `pass`/`fail`/`inconclusive` outcome. Core exploration,
 evidence collection, and gate evaluation run entirely locally — no telemetry, nothing phones home. Optional AI

package/docs/scenarios.md

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

package/mcp-server/src/application-model.js

@@ -913,7 +913,7 @@ function invalidatedGeneration(generation) {
   };
 }
 
-function mergePlanDecisions(next, prior, { invalidateValidation = false } = {}) {
+export function mergePlanDecisions(next, prior, { invalidateValidation = false } = {}) {
   if (!prior || prior.schemaVersion !== 1 || prior.kind !== "tapp-release-plan") return next;
   const priorItems = new Map((prior.items || []).map((item) => [item.id, item]));
   const priorByNameScope = new Map();

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

@@ -178,7 +178,9 @@ function loadBaseline(baselinePath) {
     actionsPerformed: parsed.actionsPerformed || 0,
     platform: parsed.baselineIdentity?.platform || parsed.platform || null,
     targetKey: parsed.baselineIdentity?.targetId || parsed.targetKey || null,
-    capture: parsed.capture || null,
+    // 0.17.7 gate JSONs briefly published the stamp as `capture`; explore JSONs use that key
+    // for the evidence-folder record. Accept the old key only when it is actually a stamp.
+    captureContext: parsed.captureContext || (parsed.capture?.viewport ? parsed.capture : null),
   };
 }
 
@@ -496,8 +498,8 @@ function renderMarkdown(report, regression, flows, scenarios, contracts, prPlan,
   lines.push(`**Gate (${gate.policy}): ${badge}**${gate.reasons.length ? " — " + gate.reasons.join("; ") : ""}${ignoredNote}`);
   // The gate is only authoritative about what it actually ran — record the scope explicitly.
   const rev = gate.revision?.sha ? `${String(gate.revision.sha).slice(0, 12)}${gate.revision.dirty ? "-dirty" : ""}` : "unknown";
-  const captured = report.capture
-    ? ` · capture: ${[report.capture.device, report.capture.viewport ? `${report.capture.viewport.width}x${report.capture.viewport.height}` : null, report.capture.deviceScaleFactor ? `@${report.capture.deviceScaleFactor}x` : null].filter(Boolean).join(" ")}`
+  const captured = report.captureContext
+    ? ` · capture: ${[report.captureContext.device, report.captureContext.viewport ? `${report.captureContext.viewport.width}x${report.captureContext.viewport.height}` : null, report.captureContext.deviceScaleFactor ? `@${report.captureContext.deviceScaleFactor}x` : null].filter(Boolean).join(" ")}`
     : "";
   const stableId = report.targetKey && report.targetKey !== gate.target ? ` (${report.targetKey})` : "";
   lines.push(`_target: ${gate.target || "—"}${stableId} · revision: ${rev} · policy: ${gate.policy} v${gate.policyVersion || "?"}${captured}_`);
@@ -562,8 +564,8 @@ const regression = computeRegression(report.findings, baseline?.findings ?? null
 // A baseline captured at a different device/viewport is a layout comparison, not a regression
 // signal: a phone run legitimately hides desktop nav links, so its "resolved" list lies. Keep
 // the diff (new findings still gate) but stamp the mismatch so every consumer can see it.
-if (regression && baseline?.capture && report.capture && JSON.stringify(baseline.capture) !== JSON.stringify(report.capture)) {
-  regression.captureMismatch = { baseline: baseline.capture, current: report.capture };
+if (regression && baseline?.captureContext && report.captureContext && JSON.stringify(baseline.captureContext) !== JSON.stringify(report.captureContext)) {
+  regression.captureMismatch = { baseline: baseline.captureContext, current: report.captureContext };
 }
 const runs = args.flowLogs.map(parseFlowLog);
 const contracts = runs.filter((run) => run.kind === "release-contract");

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

@@ -140,7 +140,7 @@ ${r.conditionsNotReached?.length ? `<div><h2>Conditions not reached</h2><ul>${sc
 <h1>${esc(observationBadge(r))} <span class="dim">· ${esc(observationSummary(r))}</span></h1>
 <div class="meta">${esc(label)} · evidence page (observation, not a release decision)</div>
 ${r.platform === "web" ? `<div class="meta">Deterministic basis: ${r.deterministicFindingCounts?.total || 0} deterministic finding(s); ${r.sampledFindingCounts?.total || 0} sampled probe finding(s) are advisory.</div>` : ""}
-${r.capture ? `<div class="meta">Captured at ${esc([r.capture.device, r.capture.viewport ? `${r.capture.viewport.width}×${r.capture.viewport.height}` : null, r.capture.deviceScaleFactor ? `@${r.capture.deviceScaleFactor}x` : null].filter(Boolean).join(" "))} — every screenshot on this page shares these conditions.</div>` : ""}
+${r.captureContext ? `<div class="meta">Captured at ${esc([r.captureContext.device, r.captureContext.viewport ? `${r.captureContext.viewport.width}×${r.captureContext.viewport.height}` : null, r.captureContext.deviceScaleFactor ? `@${r.captureContext.deviceScaleFactor}x` : null].filter(Boolean).join(" "))} — every screenshot on this page shares these conditions.</div>` : ""}
 <div class="headline">${esc(r.headline)}</div>
 ${r.credentialWarning ? `<div class="warning">${esc(r.credentialWarning)}</div>` : ""}
 ${scopeHtml}

package/mcp-server/src/product-operations.js

@@ -10,6 +10,7 @@ import {
   buildInitArtifacts,
   generateApprovedContractProposals,
   mergeGeneratedTaskProposalValidation,
+  mergePlanDecisions,
   promoteValidatedProposals,
   recordContractProposalValidation,
   recordGeneratedTaskProposalValidation,
@@ -411,6 +412,13 @@ export async function initializeProductProject({
     maxContracts: Number(maxContracts),
   });
   let written = null;
+  // Dry-run must preview the SAME plan a real refresh would produce: merge reviewed
+  // decisions from the existing plan (pure, no writes). Returning the raw regenerated
+  // plan told users their approvals would be lost on refresh (field report № 6 #25).
+  let previewPlan = built.plan;
+  if (mode === "inspect" && fs.existsSync(paths.plan)) {
+    previewPlan = mergePlanDecisions(built.plan, readJson(paths.plan));
+  }
   if (mode !== "inspect") {
     const existing = fs.existsSync(paths.model) || fs.existsSync(paths.plan);
     written = writeInitArtifacts({
@@ -422,7 +430,7 @@ export async function initializeProductProject({
     });
   }
   const requirementScope = scopeProductRequirements(built.model, { selectedTargetId: selectedTarget?.id || "" });
-  return { operation: "initialize", mode, model: built.model, plan: written?.plan || built.plan, exploration, selectedTarget, requirementScope, written, project: readProductProject({ projectDir: root, outDir }) };
+  return { operation: "initialize", mode, model: built.model, plan: written?.plan || previewPlan, exploration, selectedTarget, requirementScope, written, project: readProductProject({ projectDir: root, outDir }) };
 }
 
 function resolvePlan(root, outDir, planPath = "") {

package/mcp-server/src/report.js

@@ -303,6 +303,9 @@ export function buildQaReport(markersFilePath, { platform = "ios", target = null
     : !coverageFloorMet ? "coverage-floor-not-met"
     : driverStop === "frontier-drained" ? "no-unexplored-in-scope-controls"
     : driverStop === "probe-cap" ? "probe-cap-reached"
+    // Any other driver-signalled cause (navigation-trap, app-crashed, stuck-no-progress …)
+    // passes through verbatim: "completed" is ONLY the exhausted action budget.
+    : driverStop && driverStop !== "action-budget" && driverStop !== "time-budget" ? String(driverStop)
     : "completed";
 
   const headline = timeBudgetExhausted
@@ -410,8 +413,10 @@ export function buildQaReport(markersFilePath, { platform = "ios", target = null
     evidence: { markers: base.relativeMarkersFilePath },
     // Capture conditions shared by every screenshot/marker in this run (web: from the driver's
     // CONTEXT marker). A baseline diff across different captures is a layout comparison, not a
-    // regression signal — consumers must be able to see that.
-    capture: base.context && typeof base.context === "object"
+    // regression signal — consumers must be able to see that. Named captureContext because
+    // exploration consumers already publish `capture` as the evidence-folder record (field
+    // report № 7): the stamp must survive in the file people pass as --baseline.
+    captureContext: base.context && typeof base.context === "object"
       ? { device: base.context.device || null, viewport: base.context.viewport || null, deviceScaleFactor: base.context.deviceScaleFactor ?? null }
       : null,
     uiMap: null,

package/package.json

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

package/scripts/ci-gate.sh

@@ -34,7 +34,9 @@
 #                                                 # blocks; see ci-report.js)
 #                      [--json-out <file.json>]   # write the full report (use as the next baseline)
 #                      [--md-out <file.md>]       # write the rendered markdown report (for a PR comment)
-#                      [--device <name>]          # simulator device to boot if none is (default "iPhone 16 Pro")
+#                      [--device <name>]          # ios: simulator to boot (default "iPhone 16 Pro")
+#                                                 # web: Playwright device profile, same as `tapp explore`
+#                      [--viewport WxH]           # web only: explicit viewport, e.g. 390x844
 #                      [--serial <adb-serial>]    # Android emulator/device (default: first connected device)
 #
 # The app must be a SIMULATOR build (xcodebuild ... -destination 'generic/platform=iOS Simulator').
@@ -47,7 +49,7 @@ usage() {
 
 PLATFORM="ios" APP_PATH="" BUNDLE_ID="" APK_PATH="" APP_ID="" URL="" WEB_TARGET="" TARGET_KEY="" SERIAL="" ACTIONS=40 TIMEOUT=600 FLOWS="" SCENARIOS="" CONTRACTS="" PROJECT_DIR="" BASELINE="" FAIL_ON="gate" JSON_OUT="" MD_OUT="" DEVICE="iPhone 16 Pro" PR_BASE="" PR_HEAD="HEAD" CHANGED_FILES_FILE="" PR_PLAN_OUT=""
 IOS_PR_TARGET_JSON=""
-FLOWS_EXPLICIT=false SCENARIOS_EXPLICIT=false CONTRACTS_EXPLICIT=false PLATFORM_EXPLICIT=false FAIL_ON_EXPLICIT=false
+FLOWS_EXPLICIT=false SCENARIOS_EXPLICIT=false CONTRACTS_EXPLICIT=false PLATFORM_EXPLICIT=false FAIL_ON_EXPLICIT=false DEVICE_EXPLICIT=false VIEWPORT=""
 while [[ $# -gt 0 ]]; do
   case "$1" in
     --platform) PLATFORM="$2"; PLATFORM_EXPLICIT=true; shift 2 ;;
@@ -73,12 +75,14 @@ while [[ $# -gt 0 ]]; do
     --fail-on) FAIL_ON="$2"; FAIL_ON_EXPLICIT=true; shift 2 ;;
     --json-out) JSON_OUT="$2"; shift 2 ;;
     --md-out) MD_OUT="$2"; shift 2 ;;
-    --device) DEVICE="$2"; shift 2 ;;
+    --device) DEVICE="$2"; DEVICE_EXPLICIT=true; shift 2 ;;
+    --viewport) VIEWPORT="$2"; shift 2 ;;
     --help|-h) usage; exit 0 ;;
     *) echo "Unknown argument: $1" >&2; exit 2 ;;
   esac
 done
 [[ "$PLATFORM" == "ios" || "$PLATFORM" == "android" || "$PLATFORM" == "web" ]] || { echo "❌ --platform must be ios|android|web" >&2; exit 2; }
+[[ "$PLATFORM" == "ios" && -n "$VIEWPORT" ]] && { echo "❌ --viewport applies to web gates only; on ios --device selects the simulator" >&2; exit 2; }
 [[ "$ACTIONS" =~ ^[1-9][0-9]*$ ]] || { echo "❌ --actions must be a positive integer" >&2; exit 2; }
 [[ "$TIMEOUT" =~ ^[1-9][0-9]*$ ]] || { echo "❌ --timeout must be a positive integer" >&2; exit 2; }
 [[ "$FAIL_ON" == "gate" || "$FAIL_ON" == "absolute" || "$FAIL_ON" == "any" || "$FAIL_ON" == "high" || "$FAIL_ON" == "medium" ]] || { echo "❌ --fail-on must be gate|absolute|any|high|medium" >&2; exit 2; }
@@ -283,6 +287,16 @@ if [[ "$PLATFORM" != "ios" ]]; then
   [[ -n "$URL" ]] && PLATFORM_ARGS+=(--url "$URL")
   [[ -n "$PROJECT_DIR" ]] && PLATFORM_ARGS+=(--project-dir "$PROJECT_DIR")
   [[ -n "$WEB_TARGET" ]] && PLATFORM_ARGS+=(--web-target "$WEB_TARGET")
+  # On a web gate --device/--viewport carry the SAME meaning as `tapp explore` (a Playwright
+  # rendering profile) — one flag must not silently mean "simulator" here and get dropped.
+  if [[ "$PLATFORM" == "web" ]]; then
+    [[ "$DEVICE_EXPLICIT" == "true" ]] && PLATFORM_ARGS+=(--device "$DEVICE")
+    [[ -n "$VIEWPORT" ]] && PLATFORM_ARGS+=(--viewport "$VIEWPORT")
+  elif [[ "$PLATFORM" == "android" ]]; then
+    if [[ "$DEVICE_EXPLICIT" == "true" || -n "$VIEWPORT" ]]; then
+      echo "❌ --device/--viewport have no meaning on an android gate (use --serial to pick a device)" >&2; exit 2
+    fi
+  fi
   [[ -n "$TARGET_KEY" ]] && PLATFORM_ARGS+=(--target-key "$TARGET_KEY")
   [[ -n "$APP_ID" ]] && PLATFORM_ARGS+=(--app-id "$APP_ID")
   [[ -n "$APK_PATH" ]] && PLATFORM_ARGS+=(--apk "$APK_PATH")

package/scripts/platform-gate.js

@@ -27,6 +27,8 @@ for (let i = 2; i < process.argv.length; i += 1) {
   else if (key === "--project-dir") args.projectDir = value;
   else if (key === "--web-target") args.webTarget = value;
   else if (key === "--target-key") args.targetKey = value;
+  else if (key === "--device") args.device = value;
+  else if (key === "--viewport") args.viewport = value;
   else if (key === "--app-id") args.appId = value;
   else if (key === "--apk") args.apk = value;
   else if (key === "--serial") args.serial = value;
@@ -126,7 +128,7 @@ try {
     exitCode = 2;
   } else {
     const qa = args.platform === "web"
-      ? await runQaWeb({ url: args.url, maxActions: args.actions, timeout: args.timeout, testEmail: process.env.OCQA_TEST_EMAIL, testPassword: process.env.OCQA_TEST_PASSWORD, seedTargets: prExplorationTargets })
+      ? await runQaWeb({ url: args.url, maxActions: args.actions, timeout: args.timeout, testEmail: process.env.OCQA_TEST_EMAIL, testPassword: process.env.OCQA_TEST_PASSWORD, seedTargets: prExplorationTargets, device: args.device || "", viewport: args.viewport || "" })
       : await runQaAndroid({ appId: args.appId, apkPath: args.apk, serial: args.serial, maxActions: args.actions, timeout: args.timeout,
           testEmail: process.env.OCQA_TEST_EMAIL, testPassword: process.env.OCQA_TEST_PASSWORD, seedTargets: prExplorationTargets });
     if (qa.error) {