@validate.qa/runner 1.0.19 → 1.0.21

package/dist/cli.js

@@ -1527,7 +1527,7 @@ function buildMobileStep(action, order) {
   }
   return step;
 }
-function buildLaunchStep(target, medium) {
+function buildLaunchStep(target, medium, appResetOnLaunch = false) {
   const screenName = target.deeplink ? "DeepLinkEntry" : `${target.platform === "IOS" ? "IOS" : "Android"}Launch`;
   const description = target.launchMode === "DEEP_LINK" ? `Launch ${target.appId} via deep link` : `Launch ${target.appId} on ${medium === "IOS_NATIVE" ? "iOS" : "Android"}`;
   return {
@@ -1544,7 +1544,10 @@ function buildLaunchStep(target, medium) {
       platform: target.platform,
       deeplink: target.deeplink,
       deviceId: target.recordedDeviceId,
-      platformVersion: target.platformVersion
+      platformVersion: target.platformVersion,
+      // Recorded from a cleared app-data state: replay must clear before launch
+      // (policy-gated in the executor) to recreate the recording's entry state.
+      ...appResetOnLaunch ? { appReset: "cleared" } : {}
     }
   };
 }
@@ -1795,7 +1798,7 @@ function buildAppiumCode(testName, target, steps) {
 function generateMobileTestFromSession(input) {
   const steps = [];
   if (input.target) {
-    steps.push(buildLaunchStep(input.target, input.medium));
+    steps.push(buildLaunchStep(input.target, input.medium, input.appResetOnLaunch === true));
   }
   for (const action of input.actions) {
     const step = buildMobileStep(action, steps.length);
@@ -66065,6 +66068,8 @@ ${constraints.join("\n")}`);
     function buildMobileFallbackScenarios(input) {
       if (input.mode === "survey")
         return [];
+      if (input.featureName?.trim())
+        return [];
       const orderedScreens = targetAppScreens(input.graph, input.appId).filter((state2) => state2.screenType?.toLowerCase() !== "error").filter((state2) => state2.visited || state2.firstSeenIteration === 0).sort((a, b) => a.firstSeenIteration - b.firstSeenIteration);
       if (orderedScreens.length === 0)
         return [];
@@ -66212,6 +66217,15 @@ ${constraints.join("\n")}`);
             fallbackReason: result.fallbackReason ?? "Mobile planner produced no scenarios"
           };
         }
+        if (input.featureName?.trim()) {
+          return {
+            ...result,
+            featureGroups: mobileFeatureGroups,
+            warning: [result.warning, `Deep discovery could not plan any scenarios for "${input.featureName}" \u2014 the explorer did not reach that feature's screens this run. If the feature requires a signed-in session, verify TEST_USER_EMAIL / TEST_USER_PASSWORD are valid for this app, then re-run.`].filter(Boolean).join(" | "),
+            fallbackUsed: true,
+            fallbackReason: result.fallbackReason ?? `Planner produced no scenarios for feature "${input.featureName}"`
+          };
+        }
       }
       if (input.mode === "survey" && result.featureGroups.length === 0 && mobileFeatureGroups.length > 0) {
         return {
@@ -66492,7 +66506,8 @@ Max iterations: ${MAX_SCENARIO_ITERATIONS}. You will be warned near the end.`;
 This app has stored login credentials under these keys:
 ${keyList}
 
-When a scenario needs a signed-in session or fills a login/sign-up form, fill each credential field with \`mobile_fill_credential\`: pass the field ref and the KEY (e.g. \`{ ref: "e5", credentialKey: "TEST_USER_EMAIL" }\`). The runner types the real value on the device and the generated test stores a \`{{KEY}}\` placeholder that replay resolves \u2014 you never see, log, or echo the secret.
+When a scenario needs a signed-in session, complete the FULL login sequence \u2014 filling the fields alone does NOT log you in:
+1. Reach the email/password form. 2. Fill each credential field with \`mobile_fill_credential\` (pass the field ref and the KEY, e.g. \`{ ref: "e5", credentialKey: "TEST_USER_EMAIL" }\`) \u2014 the runner types the real value on the device and the generated test stores a \`{{KEY}}\` placeholder that replay resolves; you never see the secret. 3. TAP THE SUBMIT button (Sign In / Log In / Continue). 4. Re-snapshot and VERIFY an authenticated screen appeared. If login fails twice, do NOT keep retrying or wander: call finish_generate with verified:false and say the login could not be completed (the credentials may be invalid for this app).
 
 SECURITY RULES:
 - NEVER call \`mobile_type\` with a real email, password, or token value \u2014 the runner will REJECT the call and you lose an iteration. Use \`mobile_fill_credential\` for every credential field.
@@ -67160,7 +67175,7 @@ ${statePacket}` },
       return out;
     }
     function assembleTest(args) {
-      const { scenario, recording, ctx, platform: platform3, log: log2 } = args;
+      const { scenario, recording, ctx, platform: platform3, appDataCleared, log: log2 } = args;
       const actions = collapseRetryCycles(recording.actions);
       if (actions.length < recording.actions.length) {
         log2(`  collapsed ${recording.actions.length - actions.length} retry-cycle step(s) out of the recorded trace (${recording.actions.length} \u2192 ${actions.length}).`);
@@ -67177,7 +67192,8 @@ ${statePacket}` },
         sessionName: recording.finish?.name ?? scenario.name,
         medium,
         target,
-        actions
+        actions,
+        appResetOnLaunch: appDataCleared
       };
       let compiled;
       try {
@@ -67283,7 +67299,12 @@ ${statePacket}` },
         log2(`
 -- Generating scenario ${i + 1}/${scenarios.length}: "${scenario.name}" --`);
         try {
-          await driver.relaunch();
+          const appDataCleared = await driver.resetAppState?.().catch(() => false) ?? false;
+          if (appDataCleared) {
+            log2("  app data cleared \u2014 scenario records from a deterministic cold (logged-out) state.");
+          } else {
+            await driver.relaunch();
+          }
           const recording = await runScenarioLoop({
             scenario,
             driver,
@@ -67300,7 +67321,7 @@ ${statePacket}` },
             log: log2
           });
           consecutiveInfraFailures = 0;
-          const test = assembleTest({ scenario, recording, ctx, platform: platform3, log: log2 });
+          const test = assembleTest({ scenario, recording, ctx, platform: platform3, appDataCleared, log: log2 });
           if (!test) {
             log2(`  scenario "${scenario.name}" produced no compilable test \u2014 skipped.`);
             continue;
@@ -313771,6 +313792,8 @@ var require_mobile_discovery_agent = __commonJS({
           };
         }
         log2("\n\u2500\u2500 Phase 1: EXPLORE \u2500\u2500");
+        const exploreAppDataCleared = await driver.resetAppState?.().catch(() => false) ?? false;
+        log2(exploreAppDataCleared ? "App data cleared \u2014 exploring from a deterministic cold (logged-out) state." : "App data reset unavailable (platform/device policy) \u2014 exploring the app in its current state.");
         const state2 = new mobile_exploration_state_js_1.MobileExplorationState();
         const maxIterations = getMobileExploreBudget(mode, ctx.incremental);
         const existingScreens = compactExistingScreens(ctx.existingSiteMap);
@@ -328460,7 +328483,7 @@ var require_package4 = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "@validate.qa/runner",
-      version: "1.0.19",
+      version: "1.0.21",
       description: "validate local test runner - execute Playwright tests on your machine, connected to validate.qa cloud.",
       bin: {
         "validate-runner": "dist/cli.js"
@@ -328598,9 +328621,9 @@ function shouldUseAuthState(tags, playwrightCode) {
 
 // src/services/appium-executor.ts
 init_dist();
-var import_node_child_process2 = require("child_process");
-var import_node_util2 = require("util");
-var import_runner_core8 = __toESM(require_dist2());
+
+// src/services/mobile/appium-actions.ts
+init_dist();
 
 // src/services/appium-lifecycle.ts
 var import_child_process = require("child_process");
@@ -328885,6 +328908,234 @@ function resetServerState(port = APPIUM_PORT, restartCount = 0) {
   };
 }
 
+// src/services/mobile/appium-actions.ts
+var APPIUM_REQUEST_TIMEOUT_MS = 1e4;
+var ELEMENT_ID_PATTERN = /^[A-Za-z0-9._:-]{1,128}$/;
+async function appiumRequest(path, options) {
+  const url = `http://localhost:${getAppiumState().port}${path}`;
+  const res = await fetch(url, {
+    ...options,
+    signal: options?.signal ?? AbortSignal.timeout(APPIUM_REQUEST_TIMEOUT_MS),
+    headers: { "Content-Type": "application/json", ...options?.headers }
+  });
+  if (!res.ok) {
+    const body = await res.text().catch(() => "");
+    throw new Error(`Appium error ${res.status}: ${body.slice(0, 200)}`);
+  }
+  return res.json();
+}
+function readValue(result) {
+  if (result && typeof result === "object" && "value" in result) {
+    return result.value;
+  }
+  return void 0;
+}
+async function getScreenshot(sessionPath) {
+  try {
+    const value = readValue(await appiumRequest(`${sessionPath}/screenshot`));
+    return typeof value === "string" ? value : null;
+  } catch {
+    return null;
+  }
+}
+async function getPageSource(sessionPath) {
+  try {
+    const value = readValue(await appiumRequest(`${sessionPath}/source`));
+    return typeof value === "string" ? value : null;
+  } catch {
+    return null;
+  }
+}
+async function getWindowSize(sessionPath) {
+  const retries = 3;
+  for (let attempt = 0; attempt < retries; attempt++) {
+    try {
+      const value = readValue(await appiumRequest(`${sessionPath}/window/rect`));
+      if (value && typeof value === "object") {
+        const w = value.width;
+        const h = value.height;
+        if (typeof w === "number" && typeof h === "number" && w > 0 && h > 0) {
+          return { width: w, height: h };
+        }
+      }
+    } catch {
+    }
+    if (attempt < retries - 1) {
+      await new Promise((resolve) => setTimeout(resolve, Math.pow(2, attempt) * 100));
+    }
+  }
+  return null;
+}
+async function getActiveElementId(sessionPath) {
+  try {
+    const value = readValue(await appiumRequest(`${sessionPath}/element/active`));
+    if (!value || typeof value !== "object") return null;
+    const v = value;
+    const elementId = v.ELEMENT ?? v["element-6066-11e4-a52e-4f735466cecf"] ?? null;
+    if (typeof elementId !== "string" || !ELEMENT_ID_PATTERN.test(elementId)) {
+      return null;
+    }
+    return elementId;
+  } catch {
+    return null;
+  }
+}
+function normaliseBounds(bounds) {
+  if (!bounds || typeof bounds !== "object" || typeof bounds.x !== "number" || typeof bounds.y !== "number" || !Number.isFinite(bounds.x) || !Number.isFinite(bounds.y)) {
+    return null;
+  }
+  const b = bounds;
+  const width = typeof b.width === "number" && Number.isFinite(b.width) ? b.width : 0;
+  const height = typeof b.height === "number" && Number.isFinite(b.height) ? b.height : 0;
+  return { x: b.x, y: b.y, width, height };
+}
+async function tapBoundsCenter(sessionPath, bounds) {
+  const box = normaliseBounds(bounds);
+  if (!box) return false;
+  const tapX = Math.round(box.x + box.width / 2);
+  const tapY = Math.round(box.y + box.height / 2);
+  await appiumRequest(`${sessionPath}/actions`, {
+    method: "POST",
+    body: JSON.stringify({
+      actions: [{
+        type: "pointer",
+        id: "finger1",
+        parameters: { pointerType: "touch" },
+        actions: [
+          // Note: button: 0 is used because Appium's WebDriver protocol
+          // translates mouse button events to touch events. Standard approach
+          // for touch actions in Appium, despite the mouse button semantics.
+          { type: "pointerMove", duration: 0, x: tapX, y: tapY },
+          { type: "pointerDown", button: 0 },
+          { type: "pause", duration: 100 },
+          { type: "pointerUp", button: 0 }
+        ]
+      }]
+    })
+  });
+  return true;
+}
+async function tapAt(sessionPath, bounds) {
+  const ok = await tapBoundsCenter(sessionPath, bounds);
+  if (!ok) {
+    throw new Error("TAP requires usable bounds (finite x/y)");
+  }
+}
+function shouldResetMobileAppData(platform3, deviceId, env = process.env) {
+  if (platform3 !== "ANDROID") return false;
+  const policy = (env.VALIDATEQA_MOBILE_APP_RESET ?? "").trim().toLowerCase();
+  if (policy === "never") return false;
+  if (policy === "always") return true;
+  return !!deviceId && deviceId.startsWith("emulator-");
+}
+async function getElementRect(sessionPath, elementId) {
+  try {
+    const value = readValue(await appiumRequest(`${sessionPath}/element/${elementId}/rect`));
+    if (!value || typeof value !== "object") return null;
+    const r = value;
+    if (typeof r.x !== "number" || typeof r.y !== "number" || typeof r.width !== "number" || typeof r.height !== "number" || !Number.isFinite(r.x) || !Number.isFinite(r.y)) {
+      return null;
+    }
+    return { x: r.x, y: r.y, width: r.width, height: r.height };
+  } catch {
+    return null;
+  }
+}
+function rectMatchesIntendedBounds(rect, bounds) {
+  if (bounds.width <= 0 || bounds.height <= 0) return false;
+  const rectCenterX = rect.x + rect.width / 2;
+  const rectCenterY = rect.y + rect.height / 2;
+  const boundsCenterX = bounds.x + bounds.width / 2;
+  const boundsCenterY = bounds.y + bounds.height / 2;
+  const rectCenterInBounds = rectCenterX >= bounds.x && rectCenterX <= bounds.x + bounds.width && rectCenterY >= bounds.y && rectCenterY <= bounds.y + bounds.height;
+  const boundsCenterInRect = rect.width > 0 && rect.height > 0 && boundsCenterX >= rect.x && boundsCenterX <= rect.x + rect.width && boundsCenterY >= rect.y && boundsCenterY <= rect.y + rect.height;
+  return rectCenterInBounds || boundsCenterInRect;
+}
+async function resolveTypeTargetElementId(sessionPath, bounds) {
+  const box = bounds !== void 0 ? normaliseBounds(bounds) : null;
+  let elementId = await getActiveElementId(sessionPath);
+  if (elementId && box && box.width > 0 && box.height > 0) {
+    const rect = await getElementRect(sessionPath, elementId);
+    if (!rect || !rectMatchesIntendedBounds(rect, box)) {
+      elementId = null;
+    }
+  }
+  if (!elementId && bounds !== void 0 && await tapBoundsCenter(sessionPath, bounds)) {
+    await new Promise((resolve) => setTimeout(resolve, MOBILE_FOCUS_SETTLE_MS));
+    elementId = await getActiveElementId(sessionPath);
+  }
+  return elementId;
+}
+async function typeText(sessionPath, value, bounds) {
+  const elementId = await resolveTypeTargetElementId(sessionPath, bounds);
+  if (!elementId) {
+    throw new Error("No focused element available for TYPE. Tap an input field first.");
+  }
+  await appiumRequest(`${sessionPath}/element/${elementId}/value`, {
+    method: "POST",
+    body: JSON.stringify({ text: value })
+  });
+}
+async function clearField(sessionPath, bounds) {
+  const elementId = await resolveTypeTargetElementId(sessionPath, bounds);
+  if (!elementId) {
+    throw new Error("No focused element available for CLEAR. Tap an input field first.");
+  }
+  await appiumRequest(`${sessionPath}/element/${elementId}/clear`, {
+    method: "POST",
+    body: JSON.stringify({})
+  });
+}
+async function swipe(sessionPath, direction, distance, windowSize) {
+  const dist = clampMobileSwipeDistance(distance);
+  const { startX, startY, endX, endY } = computeMobileSwipePointers(
+    windowSize.width,
+    windowSize.height,
+    direction,
+    dist
+  );
+  await appiumRequest(`${sessionPath}/actions`, {
+    method: "POST",
+    body: JSON.stringify({
+      actions: [{
+        type: "pointer",
+        id: "finger1",
+        parameters: { pointerType: "touch" },
+        actions: [
+          { type: "pointerMove", duration: 0, x: startX, y: startY },
+          { type: "pointerDown", button: 0 },
+          { type: "pointerMove", duration: 300, x: endX, y: endY },
+          { type: "pointerUp", button: 0 }
+        ]
+      }]
+    })
+  });
+}
+async function pressBack(sessionPath) {
+  await appiumRequest(`${sessionPath}/back`, { method: "POST", body: "{}" });
+}
+async function pressHome(sessionPath, platform3) {
+  if (platform3 === "IOS") {
+    await appiumRequest(`${sessionPath}/execute/sync`, {
+      method: "POST",
+      body: JSON.stringify({
+        script: "mobile: pressButton",
+        args: [{ name: "home" }]
+      })
+    });
+    return;
+  }
+  await appiumRequest(`${sessionPath}/appium/device/press_keycode`, {
+    method: "POST",
+    body: JSON.stringify({ keycode: 3 })
+  });
+}
+
+// src/services/appium-executor.ts
+var import_node_child_process2 = require("child_process");
+var import_node_util2 = require("util");
+var import_runner_core8 = __toESM(require_dist2());
+
 // src/services/device-discovery.ts
 var import_child_process2 = require("child_process");
 var import_os2 = require("os");
@@ -330047,7 +330298,7 @@ async function wdRequest(path, options) {
   }
   return res.json();
 }
-async function getWindowSize(sessionId, retries = 3) {
+async function getWindowSize2(sessionId, retries = 3) {
   for (let attempt = 0; attempt < retries; attempt++) {
     try {
       const result = await wdRequest(`/session/${sessionId}/window/rect`);
@@ -330223,6 +330474,26 @@ async function freshLaunchTargetApp(sessionId, platform3, appId, log2) {
     log2(`  Fresh launch: activate failed (${err instanceof Error ? err.message : String(err)})`);
   }
 }
+async function waitForColdBootContent(sessionId, log2, timeoutMs = 2e4) {
+  const deadline = Date.now() + timeoutMs;
+  const MIN_ELEMENTS = 3;
+  let lastCount = 0;
+  while (Date.now() < deadline) {
+    try {
+      const res = await wdRequest(`/session/${sessionId}/source`);
+      const xml = typeof res?.value === "string" ? res.value : "";
+      const count = (xml.match(/<(android\.|XCUIElementType)/g) ?? []).length;
+      lastCount = count;
+      if (count >= MIN_ELEMENTS) {
+        log2(`  Cold-boot ready: UI tree has ${count} node(s).`);
+        return;
+      }
+    } catch {
+    }
+    await new Promise((r) => setTimeout(r, 750));
+  }
+  log2(`  Cold-boot wait timed out after ${timeoutMs}ms (last tree had ${lastCount} node(s)) \u2014 proceeding anyway.`);
+}
 async function restoreTargetAppIfExternal(sessionId, target, log2, source, failOnExternal) {
   let boundary = null;
   try {
@@ -330470,7 +330741,7 @@ async function tapCoordinates(sessionId, bounds) {
     })
   });
 }
-async function getActiveElementId(sessionId) {
+async function getActiveElementId2(sessionId) {
   try {
     const activeEl = await wdRequest(`/session/${sessionId}/element/active`);
     return activeEl?.value?.ELEMENT || activeEl?.value?.["element-6066-11e4-a52e-4f735466cecf"] || null;
@@ -330556,7 +330827,7 @@ async function executeType(sessionId, step, context) {
     await tapCoordinates(sessionId, bounds);
     tappedBounds = true;
     await new Promise((resolve) => setTimeout(resolve, MOBILE_FOCUS_SETTLE_MS));
-    elementId = await getActiveElementId(sessionId);
+    elementId = await getActiveElementId2(sessionId);
     if (elementId) {
       lastInputError = await trySendElementValue(sessionId, elementId, value);
       if (!lastInputError) return;
@@ -330578,10 +330849,10 @@ async function executeType(sessionId, step, context) {
     await tapCoordinates(sessionId, bounds);
     tappedBounds = true;
     await new Promise((resolve) => setTimeout(resolve, MOBILE_FOCUS_SETTLE_MS));
-    elementId = await getActiveElementId(sessionId);
+    elementId = await getActiveElementId2(sessionId);
   }
   if (!elementId) {
-    elementId = await getActiveElementId(sessionId);
+    elementId = await getActiveElementId2(sessionId);
   }
   if (elementId) {
     lastInputError = await trySendElementValue(sessionId, elementId, value);
@@ -330631,10 +330902,10 @@ async function executeClear(sessionId, step, platform3, isCrossPlatform = false)
   if (!elementId && bounds) {
     await tapCoordinates(sessionId, bounds);
     await new Promise((resolve) => setTimeout(resolve, MOBILE_FOCUS_SETTLE_MS));
-    elementId = await getActiveElementId(sessionId);
+    elementId = await getActiveElementId2(sessionId);
   }
   if (!elementId) {
-    elementId = await getActiveElementId(sessionId);
+    elementId = await getActiveElementId2(sessionId);
   }
   if (!elementId) {
     throw new Error("CLEAR step could not resolve a target or focused element");
@@ -330650,7 +330921,7 @@ async function executeSwipe(sessionId, step) {
   let screenW;
   let screenH;
   try {
-    const windowSize = await getWindowSize(sessionId);
+    const windowSize = await getWindowSize2(sessionId);
     screenW = windowSize.width;
     screenH = windowSize.height;
   } catch (err) {
@@ -330865,8 +331136,25 @@ async function executeMobileTest(options) {
       }
     }
     recordingStarted = await startScreenRecording(sessionId, options.target.platform, log2);
+    const launchStepForReset = runSteps.find((s) => s.action === "launchApp");
+    const recordedFromClearedState = launchStepForReset?.metadata?.appReset === "cleared";
+    if (recordedFromClearedState) {
+      if (shouldResetMobileAppData(options.target.platform, selectedDevice.id)) {
+        try {
+          await executeMobileScript(sessionId, "mobile: clearApp", [{ appId: options.target.appId }]);
+          log2("App data cleared before launch (test was recorded from a cold logged-out state).");
+        } catch (err) {
+          log2(`App-data clear failed (continuing with plain fresh launch): ${err instanceof Error ? err.message : String(err)}`);
+        }
+      } else {
+        log2("Test expects a cleared app state, but app-data reset is disabled by policy (physical device / VALIDATEQA_MOBILE_APP_RESET=never) \u2014 replaying against the current app state.");
+      }
+    }
     log2("Opening a fresh app instance for the test...");
     await freshLaunchTargetApp(sessionId, options.target.platform, options.target.appId, log2);
+    if (recordedFromClearedState) {
+      await waitForColdBootContent(sessionId, log2);
+    }
     if (options.target.launchMode === "DEEP_LINK" && options.target.deeplink) {
       try {
         log2(`Opening deep link: ${options.target.deeplink}`);
@@ -331381,225 +331669,6 @@ var import_os3 = require("os");
 var import_path2 = require("path");
 var import_fs2 = require("fs");
 init_dist();
-
-// src/services/mobile/appium-actions.ts
-init_dist();
-var APPIUM_REQUEST_TIMEOUT_MS = 1e4;
-var ELEMENT_ID_PATTERN = /^[A-Za-z0-9._:-]{1,128}$/;
-async function appiumRequest(path, options) {
-  const url = `http://localhost:${getAppiumState().port}${path}`;
-  const res = await fetch(url, {
-    ...options,
-    signal: options?.signal ?? AbortSignal.timeout(APPIUM_REQUEST_TIMEOUT_MS),
-    headers: { "Content-Type": "application/json", ...options?.headers }
-  });
-  if (!res.ok) {
-    const body = await res.text().catch(() => "");
-    throw new Error(`Appium error ${res.status}: ${body.slice(0, 200)}`);
-  }
-  return res.json();
-}
-function readValue(result) {
-  if (result && typeof result === "object" && "value" in result) {
-    return result.value;
-  }
-  return void 0;
-}
-async function getScreenshot(sessionPath) {
-  try {
-    const value = readValue(await appiumRequest(`${sessionPath}/screenshot`));
-    return typeof value === "string" ? value : null;
-  } catch {
-    return null;
-  }
-}
-async function getPageSource(sessionPath) {
-  try {
-    const value = readValue(await appiumRequest(`${sessionPath}/source`));
-    return typeof value === "string" ? value : null;
-  } catch {
-    return null;
-  }
-}
-async function getWindowSize2(sessionPath) {
-  const retries = 3;
-  for (let attempt = 0; attempt < retries; attempt++) {
-    try {
-      const value = readValue(await appiumRequest(`${sessionPath}/window/rect`));
-      if (value && typeof value === "object") {
-        const w = value.width;
-        const h = value.height;
-        if (typeof w === "number" && typeof h === "number" && w > 0 && h > 0) {
-          return { width: w, height: h };
-        }
-      }
-    } catch {
-    }
-    if (attempt < retries - 1) {
-      await new Promise((resolve) => setTimeout(resolve, Math.pow(2, attempt) * 100));
-    }
-  }
-  return null;
-}
-async function getActiveElementId2(sessionPath) {
-  try {
-    const value = readValue(await appiumRequest(`${sessionPath}/element/active`));
-    if (!value || typeof value !== "object") return null;
-    const v = value;
-    const elementId = v.ELEMENT ?? v["element-6066-11e4-a52e-4f735466cecf"] ?? null;
-    if (typeof elementId !== "string" || !ELEMENT_ID_PATTERN.test(elementId)) {
-      return null;
-    }
-    return elementId;
-  } catch {
-    return null;
-  }
-}
-function normaliseBounds(bounds) {
-  if (!bounds || typeof bounds !== "object" || typeof bounds.x !== "number" || typeof bounds.y !== "number" || !Number.isFinite(bounds.x) || !Number.isFinite(bounds.y)) {
-    return null;
-  }
-  const b = bounds;
-  const width = typeof b.width === "number" && Number.isFinite(b.width) ? b.width : 0;
-  const height = typeof b.height === "number" && Number.isFinite(b.height) ? b.height : 0;
-  return { x: b.x, y: b.y, width, height };
-}
-async function tapBoundsCenter(sessionPath, bounds) {
-  const box = normaliseBounds(bounds);
-  if (!box) return false;
-  const tapX = Math.round(box.x + box.width / 2);
-  const tapY = Math.round(box.y + box.height / 2);
-  await appiumRequest(`${sessionPath}/actions`, {
-    method: "POST",
-    body: JSON.stringify({
-      actions: [{
-        type: "pointer",
-        id: "finger1",
-        parameters: { pointerType: "touch" },
-        actions: [
-          // Note: button: 0 is used because Appium's WebDriver protocol
-          // translates mouse button events to touch events. Standard approach
-          // for touch actions in Appium, despite the mouse button semantics.
-          { type: "pointerMove", duration: 0, x: tapX, y: tapY },
-          { type: "pointerDown", button: 0 },
-          { type: "pause", duration: 100 },
-          { type: "pointerUp", button: 0 }
-        ]
-      }]
-    })
-  });
-  return true;
-}
-async function tapAt(sessionPath, bounds) {
-  const ok = await tapBoundsCenter(sessionPath, bounds);
-  if (!ok) {
-    throw new Error("TAP requires usable bounds (finite x/y)");
-  }
-}
-async function getElementRect(sessionPath, elementId) {
-  try {
-    const value = readValue(await appiumRequest(`${sessionPath}/element/${elementId}/rect`));
-    if (!value || typeof value !== "object") return null;
-    const r = value;
-    if (typeof r.x !== "number" || typeof r.y !== "number" || typeof r.width !== "number" || typeof r.height !== "number" || !Number.isFinite(r.x) || !Number.isFinite(r.y)) {
-      return null;
-    }
-    return { x: r.x, y: r.y, width: r.width, height: r.height };
-  } catch {
-    return null;
-  }
-}
-function rectMatchesIntendedBounds(rect, bounds) {
-  if (bounds.width <= 0 || bounds.height <= 0) return false;
-  const rectCenterX = rect.x + rect.width / 2;
-  const rectCenterY = rect.y + rect.height / 2;
-  const boundsCenterX = bounds.x + bounds.width / 2;
-  const boundsCenterY = bounds.y + bounds.height / 2;
-  const rectCenterInBounds = rectCenterX >= bounds.x && rectCenterX <= bounds.x + bounds.width && rectCenterY >= bounds.y && rectCenterY <= bounds.y + bounds.height;
-  const boundsCenterInRect = rect.width > 0 && rect.height > 0 && boundsCenterX >= rect.x && boundsCenterX <= rect.x + rect.width && boundsCenterY >= rect.y && boundsCenterY <= rect.y + rect.height;
-  return rectCenterInBounds || boundsCenterInRect;
-}
-async function resolveTypeTargetElementId(sessionPath, bounds) {
-  const box = bounds !== void 0 ? normaliseBounds(bounds) : null;
-  let elementId = await getActiveElementId2(sessionPath);
-  if (elementId && box && box.width > 0 && box.height > 0) {
-    const rect = await getElementRect(sessionPath, elementId);
-    if (!rect || !rectMatchesIntendedBounds(rect, box)) {
-      elementId = null;
-    }
-  }
-  if (!elementId && bounds !== void 0 && await tapBoundsCenter(sessionPath, bounds)) {
-    await new Promise((resolve) => setTimeout(resolve, MOBILE_FOCUS_SETTLE_MS));
-    elementId = await getActiveElementId2(sessionPath);
-  }
-  return elementId;
-}
-async function typeText(sessionPath, value, bounds) {
-  const elementId = await resolveTypeTargetElementId(sessionPath, bounds);
-  if (!elementId) {
-    throw new Error("No focused element available for TYPE. Tap an input field first.");
-  }
-  await appiumRequest(`${sessionPath}/element/${elementId}/value`, {
-    method: "POST",
-    body: JSON.stringify({ text: value })
-  });
-}
-async function clearField(sessionPath, bounds) {
-  const elementId = await resolveTypeTargetElementId(sessionPath, bounds);
-  if (!elementId) {
-    throw new Error("No focused element available for CLEAR. Tap an input field first.");
-  }
-  await appiumRequest(`${sessionPath}/element/${elementId}/clear`, {
-    method: "POST",
-    body: JSON.stringify({})
-  });
-}
-async function swipe(sessionPath, direction, distance, windowSize) {
-  const dist = clampMobileSwipeDistance(distance);
-  const { startX, startY, endX, endY } = computeMobileSwipePointers(
-    windowSize.width,
-    windowSize.height,
-    direction,
-    dist
-  );
-  await appiumRequest(`${sessionPath}/actions`, {
-    method: "POST",
-    body: JSON.stringify({
-      actions: [{
-        type: "pointer",
-        id: "finger1",
-        parameters: { pointerType: "touch" },
-        actions: [
-          { type: "pointerMove", duration: 0, x: startX, y: startY },
-          { type: "pointerDown", button: 0 },
-          { type: "pointerMove", duration: 300, x: endX, y: endY },
-          { type: "pointerUp", button: 0 }
-        ]
-      }]
-    })
-  });
-}
-async function pressBack(sessionPath) {
-  await appiumRequest(`${sessionPath}/back`, { method: "POST", body: "{}" });
-}
-async function pressHome(sessionPath, platform3) {
-  if (platform3 === "IOS") {
-    await appiumRequest(`${sessionPath}/execute/sync`, {
-      method: "POST",
-      body: JSON.stringify({
-        script: "mobile: pressButton",
-        args: [{ name: "home" }]
-      })
-    });
-    return;
-  }
-  await appiumRequest(`${sessionPath}/appium/device/press_keycode`, {
-    method: "POST",
-    body: JSON.stringify({ keycode: 3 })
-  });
-}
-
-// src/services/mobile-bridge.ts
 var MOBILE_BRIDGE_PORT2 = 9515;
 var MAX_REQUEST_BODY_BYTES = 64 * 1024;
 var MAX_TEXT_INPUT_LENGTH = 4e3;
@@ -331693,7 +331762,7 @@ async function getPageSource2() {
 async function getWindowSize3() {
   if (!state.appiumSessionId) return null;
   validateSessionId(state.appiumSessionId);
-  return getWindowSize2(`/session/${state.appiumSessionId}`);
+  return getWindowSize(`/session/${state.appiumSessionId}`);
 }
 var BRIDGE_PROCESS_MARKER = "validateqa-mobile-bridge";
 var BRIDGE_PORT = MOBILE_BRIDGE_PORT2;
@@ -332757,6 +332826,7 @@ var MobileBridgeDriver = class {
   sessionId;
   platform;
   appId;
+  allowAppReset;
   constructor(config) {
     if (!APPIUM_SESSION_ID_PATTERN2.test(config.sessionId)) {
       throw new Error("MobileBridgeDriver: invalid Appium session id");
@@ -332770,6 +332840,7 @@ var MobileBridgeDriver = class {
     this.sessionId = config.sessionId;
     this.platform = config.platform;
     this.appId = config.appId;
+    this.allowAppReset = config.allowAppReset === true;
   }
   /** WebDriver session path (`/session/<id>`), the prefix every primitive needs. */
   get sessionPath() {
@@ -332831,7 +332902,7 @@ var MobileBridgeDriver = class {
     const [xml, screenshot, windowSize] = await Promise.all([
       getPageSource(this.sessionPath),
       getScreenshot(this.sessionPath),
-      getWindowSize2(this.sessionPath)
+      getWindowSize(this.sessionPath)
     ]);
     const source = xml ?? "";
     const screenSignal = await this.enrichScreenSignal(source);
@@ -332844,7 +332915,7 @@ var MobileBridgeDriver = class {
   }
   /** Device window size; null when unreadable (swipe geometry degrades gracefully). */
   async windowSize() {
-    return getWindowSize2(this.sessionPath);
+    return getWindowSize(this.sessionPath);
   }
   // ── Action result wrapper ──────────────────────────────
   /**
@@ -332886,7 +332957,7 @@ var MobileBridgeDriver = class {
    * hard error so we never fire an off-screen gesture.
    */
   async swipe(direction, distance) {
-    const size = await getWindowSize2(this.sessionPath);
+    const size = await getWindowSize(this.sessionPath);
     if (!size) {
       return { ok: false, error: "Could not determine device screen dimensions for swipe." };
     }
@@ -332911,6 +332982,22 @@ var MobileBridgeDriver = class {
     await this.executeScript("mobile: terminateApp", [args]);
     await this.executeScript("mobile: activateApp", [args]);
   }
+  /**
+   * Deterministic state reset: clear app data + relaunch (Android emulators
+   * only, per the runner-computed allowAppReset policy). Returns false when
+   * unsupported/disallowed or when clearApp throws — callers fall back to
+   * relaunch(), preserving today's behavior.
+   */
+  async resetAppState() {
+    if (!this.allowAppReset || this.platform !== "ANDROID") return false;
+    try {
+      await this.executeScript("mobile: clearApp", [{ appId: this.appId }]);
+      await this.executeScript("mobile: activateApp", [this.appLifecycleArgs()]);
+      return true;
+    } catch {
+      return false;
+    }
+  }
   /** (Re)launch the target app (activateApp) from a backgrounded/closed state. */
   async launchApp() {
     await this.executeScript("mobile: activateApp", [this.appLifecycleArgs()]);
@@ -335052,7 +335139,11 @@ ${finalVerifyResult.logs ?? ""}`;
             const driver = new MobileBridgeDriver({
               sessionId: session.sessionId,
               platform: platform3,
-              appId: session.appId
+              appId: session.appId,
+              // Deterministic-state authorization: Android emulators only by
+              // default (VALIDATEQA_MOBILE_APP_RESET overrides) — a personal
+              // physical device must never have its app data wiped.
+              allowAppReset: shouldResetMobileAppData(platform3, session.deviceId)
             });
             discoveryResult = await (0, import_runner_core4.runMobileDiscoveryOnRunner)(ctx, driver, {
               onLog: mobileOnLog,