@validate.qa/runner 1.0.18 → 1.0.20

package/dist/cli.mjs

@@ -1532,7 +1532,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 {
@@ -1549,7 +1549,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" } : {}
     }
   };
 }
@@ -1800,7 +1803,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);
@@ -62045,7 +62048,7 @@ var require_mobile_explorer = __commonJS({
       }
       sections.push("");
       if (mode === "survey") {
-        sections.push("**Mission:** Map every reachable screen. For each new screen: mobile_snapshot -> capture_screen -> record_transition. Do NOT submit forms or mutate data. Call finish_exploration when no new screens remain.");
+        sections.push(`**Mission:** Map every reachable screen. For each new screen: mobile_snapshot -> capture_screen -> record_transition. Get PAST the entry gate into the app's real main content \u2014 the login/landing screens are the ENTRANCE, not the app. If test credentials are provided (see the Test Credentials section), SIGN IN with them FIRST and map the authenticated app; that is the real product surface. Use a guest/demo/skip entry (e.g. "See Demo Profile", "Continue as guest") ONLY as a fallback when no credentials are available or login cannot be completed \u2014 demo mode is a limited sandbox, not the authenticated app. Do NOT submit forms with junk data or mutate real data. Call finish_exploration ONLY when every reachable screen \u2014 including the authenticated content \u2014 has been captured and no unvisited frontier screens remain.`);
       } else {
         sections.push("**Mission:** Use the focus features like a real user. Tap, type, submit, and observe outcomes. After a meaningful flow, call record_journey. Call finish_exploration when the flows are covered.");
       }
@@ -62103,7 +62106,14 @@ var require_mobile_explorer = __commonJS({
 This app has stored login credentials under these keys:
 ${keyList}
 
-When you reach a login / sign-in screen, LOG IN so you can map and test the authenticated app \u2014 this OVERRIDES the "do not submit forms" rule for the login form ONLY. 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 substitutes the real value on the device; you never see, log, or echo it.
+LOG IN FIRST \u2014 before broad exploration. The authenticated app is the real product surface; a survey that only maps the logged-out/demo screens has missed most of the app. This OVERRIDES the "do not submit forms" rule for the login form ONLY. The login sequence is:
+1. Reach the email/password sign-in form (tap "Sign in with Email" / "Login" from the landing screen if needed).
+2. Fill the email field: \`mobile_fill_credential({ ref, credentialKey: "TEST_USER_EMAIL" })\`. Fill the password field: \`mobile_fill_credential({ ref, credentialKey: "TEST_USER_PASSWORD" })\`. The runner substitutes the real value on the device; you never see, log, or echo it.
+3. TAP THE SUBMIT BUTTON (e.g. "Sign In", "Log In", "Continue"). Filling the fields does NOT log you in \u2014 you MUST tap submit.
+4. VERIFY you are actually signed in: re-snapshot and confirm an authenticated signal appeared (a home/feed/dashboard with real content, an account/profile tab, a "Sign out" option, or your user identity). If you are still on the login form, the login failed \u2014 check for an error, re-enter, and submit again (up to 2 attempts).
+5. Only AFTER you have confirmed you are signed in, map the authenticated app.
+
+PREFER real login over any "demo"/"guest"/"skip" entry: those give a limited sandbox, NOT the authenticated app. Use them only if login is impossible.
 
 SECURITY RULES:
 - NEVER call \`mobile_type\` with an 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.
@@ -62410,6 +62420,8 @@ ${existingScreens.slice(0, 100).map((s) => `- ${s.screenId}${s.name ? ` "${s.nam
       let summary = "";
       let truncated = false;
       let truncatedReason;
+      let finishRedirects = 0;
+      const MAX_FINISH_REDIRECTS = 2;
       try {
         try {
           const seed = await driver.snapshot();
@@ -62539,6 +62551,20 @@ ${statePacket}` }
               continue;
             }
             if (toolName === "finish_exploration") {
+              const frontier = mode === "survey" ? state2.getFrontier() : [];
+              const budgetRemainingPct = (maxIterations - iteration) / maxIterations;
+              if (frontier.length > 0 && budgetRemainingPct >= 0.2 && finishRedirects < MAX_FINISH_REDIRECTS) {
+                finishRedirects++;
+                const targets = frontier.slice(0, 6).join(", ");
+                log2(`
+finish_exploration bounced (${finishRedirects}/${MAX_FINISH_REDIRECTS}): ${frontier.length} frontier screen(s) still unvisited, ${Math.round(budgetRemainingPct * 100)}% budget left.`);
+                pushResult({
+                  acknowledged: false,
+                  keepExploring: true,
+                  reason: `Not done yet \u2014 ${frontier.length} screen(s) were seen via transitions but never visited, and ${Math.round(budgetRemainingPct * 100)}% of the iteration budget remains. A survey must map EVERY reachable screen. Navigate into the unvisited screens (e.g. ${targets}), snapshot + capture_screen each, then call finish_exploration only once no unvisited screens remain. If a screen is genuinely unreachable (needs credentials you don't have, or leaves the app), note that and move to the next one.`
+                });
+                continue;
+              }
               explorationComplete = true;
               summary = String(toolArgs.summary ?? "");
               log2(`
@@ -62757,6 +62783,14 @@ Exploration complete: ${summary}`);
             ...actionResult.error ? { error: actionResult.error } : {},
             // Report only the KEY that was filled — never the value.
             filledCredentialKey: key,
+            // Code-level reinforcement of the login sequence: filling a field does
+            // NOT submit the form. The observed failure was fill-without-submit —
+            // the model filled email+password then wandered off (into demo content)
+            // without ever tapping Sign In, so it never reached the authenticated
+            // app. This nudge fires on every credential fill so the model is
+            // reminded to complete + verify the login rather than treating the fill
+            // as "logged in".
+            nextStep: "Credential filled \u2014 this does NOT log you in. Once all credential fields are filled, tap the submit button (Sign In / Log In / Continue), then re-snapshot and confirm an authenticated screen (home/feed/account/Sign out) appeared before exploring further.",
             screenId,
             observation,
             ...absorbed.externalBlocked ? { blockedExternalApp: true, externalApp: absorbed.externalOwner } : {},
@@ -67134,7 +67168,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}).`);
@@ -67151,7 +67185,8 @@ ${statePacket}` },
         sessionName: recording.finish?.name ?? scenario.name,
         medium,
         target,
-        actions
+        actions,
+        appResetOnLaunch: appDataCleared
       };
       let compiled;
       try {
@@ -67257,7 +67292,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,
@@ -67274,7 +67314,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;
@@ -313745,6 +313785,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);
@@ -328434,7 +328476,7 @@ var require_package4 = __commonJS({
   "package.json"(exports, module) {
     module.exports = {
       name: "@validate.qa/runner",
-      version: "1.0.18",
+      version: "1.0.20",
       description: "validate local test runner - execute Playwright tests on your machine, connected to validate.qa cloud.",
       bin: {
         "validate-runner": "dist/cli.js"
@@ -328572,9 +328614,9 @@ function shouldUseAuthState(tags, playwrightCode) {
 
 // src/services/appium-executor.ts
 init_dist();
-var import_runner_core8 = __toESM(require_dist2());
-import { execFile as execFile2 } from "child_process";
-import { promisify as promisify2 } from "util";
+
+// src/services/mobile/appium-actions.ts
+init_dist();
 
 // src/services/appium-lifecycle.ts
 import { spawn, execFileSync } from "child_process";
@@ -328859,6 +328901,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_runner_core8 = __toESM(require_dist2());
+import { execFile as execFile2 } from "child_process";
+import { promisify as promisify2 } from "util";
+
 // src/services/device-discovery.ts
 import { execFileSync as execFileSync2 } from "child_process";
 import { platform } from "os";
@@ -330024,7 +330294,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`);
@@ -330200,6 +330470,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 {
@@ -330447,7 +330737,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;
@@ -330533,7 +330823,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;
@@ -330555,10 +330845,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);
@@ -330608,10 +330898,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");
@@ -330627,7 +330917,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) {
@@ -330842,8 +331132,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}`);
@@ -331358,225 +331665,6 @@ import { homedir as homedir2 } from "os";
 import { join as join3, dirname } from "path";
 import { readFileSync as readFileSync2, writeFileSync as writeFileSync2, unlinkSync as unlinkSync2, mkdirSync as mkdirSync2 } from "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;
@@ -331670,7 +331758,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;
@@ -332734,6 +332822,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");
@@ -332747,6 +332836,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() {
@@ -332808,7 +332898,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);
@@ -332821,7 +332911,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 ──────────────────────────────
   /**
@@ -332863,7 +332953,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." };
     }
@@ -332888,6 +332978,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()]);
@@ -335029,7 +335135,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,