@vostride/agent-qa-android 0.0.1 → 0.1.1

package/dist/index.js

@@ -0,0 +1,920 @@
+// src/adapter.ts
+import { MobileSetupError as MobileSetupError2, parseMobileSource, MobileElementResolver, KEY_MAP, computeSwipe, computePinch, computeFingerPositions, warnIfOutOfBounds } from "@vostride/agent-qa-core";
+
+// src/session.ts
+import { remote } from "webdriverio";
+import { MobileSetupError } from "@vostride/agent-qa-core";
+async function createAndroidSession(config, farmSession) {
+  const match = config.device?.match ?? {};
+  const appiumUrl = process.env.AGENT_QA_APPIUM_URL ?? config.appiumUrl ?? "http://localhost:4723";
+  const url = new URL(appiumUrl);
+  const browserName = config.browserName ?? match.browserName;
+  const appPath = config.appPath;
+  if (browserName && appPath) {
+    throw new MobileSetupError({
+      category: "app-install",
+      message: "Mobile browser mode cannot be combined with app.path",
+      platform: "android",
+      deviceName: config.device?.name,
+      appId: appPath
+    });
+  }
+  const appStateNoReset = config.appState === "preserve" ? true : config.appState === "reset" ? false : void 0;
+  const capabilities = {
+    platformName: "Android",
+    "appium:automationName": match.automationName ?? "UiAutomator2",
+    "appium:deviceName": config.device?.name ?? "Android Emulator",
+    "appium:newCommandTimeout": config.timeouts?.test ? Math.ceil(config.timeouts.test / 1e3) : 300,
+    "appium:chromedriverAutodownload": true
+  };
+  if (match.platformVersion) capabilities["appium:platformVersion"] = match.platformVersion;
+  if (match.avd) capabilities["appium:avd"] = match.avd;
+  if (config.avd) capabilities["appium:avd"] = config.avd;
+  if (appPath) capabilities["appium:app"] = appPath;
+  if (browserName) {
+    capabilities.browserName = browserName;
+    capabilities["appium:autoWebview"] = true;
+  } else {
+    if (appStateNoReset !== void 0) capabilities["appium:noReset"] = appStateNoReset;
+    if (match.appPackage) capabilities["appium:appPackage"] = match.appPackage;
+    if (config.appPackage) capabilities["appium:appPackage"] = config.appPackage;
+    if (match.appActivity) capabilities["appium:appActivity"] = match.appActivity;
+    if (config.appActivity) capabilities["appium:appActivity"] = config.appActivity;
+  }
+  for (const key of Object.keys(capabilities)) {
+    if (capabilities[key] === void 0) {
+      delete capabilities[key];
+    }
+  }
+  if (farmSession) {
+    Object.assign(capabilities, farmSession.capabilities);
+    return remote({
+      protocol: "https",
+      hostname: farmSession.hostname,
+      port: farmSession.port,
+      path: farmSession.path,
+      logLevel: config.verbose ? "info" : "silent",
+      capabilities
+    });
+  }
+  return remote({
+    hostname: url.hostname,
+    port: parseInt(url.port || "4723", 10),
+    path: url.pathname === "/" ? "/" : url.pathname,
+    logLevel: config.verbose ? "info" : "silent",
+    capabilities
+  });
+}
+
+// src/adapter.ts
+var ANDROID_FILLABLE_ROLES = /* @__PURE__ */ new Set(["textbox", "searchbox", "edittext", "combobox"]);
+var ANDROID_NATIVE_SELECT_ROLES = /* @__PURE__ */ new Set(["combobox", "spinbutton", "listbox", "list"]);
+var ANDROID_NATIVE_SELECT_TYPES = /* @__PURE__ */ new Set([
+  "android.widget.Spinner",
+  "android.widget.NumberPicker",
+  "android.widget.DatePicker",
+  "android.widget.TimePicker",
+  "android.widget.ListView",
+  "androidx.recyclerview.widget.RecyclerView"
+]);
+async function safePerform(chain) {
+  try {
+    await chain.perform();
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (msg.includes("actions") && msg.includes("DELETE")) return;
+    throw err;
+  }
+}
+var LOGCAT_REGEX = /^(\d{2}-\d{2})\s+(\d{2}:\d{2}:\d{2}\.\d{3})\s+(\d+)\s+(\d+)\s+([VDIWEF])\s+(.+?)\s*:\s+(.*)/;
+var ANDROID_LEVEL_MAP = {
+  V: "debug",
+  D: "debug",
+  I: "info",
+  W: "warn",
+  E: "error",
+  F: "error"
+};
+function firstNonEmpty(...values) {
+  for (const value of values) {
+    const trimmed = typeof value === "string" ? value.trim() : "";
+    if (trimmed) return trimmed;
+  }
+  return void 0;
+}
+function isAndroidNativeSelectTarget(refData) {
+  const role = refData?.role?.toLowerCase();
+  return Boolean(
+    role && ANDROID_NATIVE_SELECT_ROLES.has(role) || refData?.nativeType && ANDROID_NATIVE_SELECT_TYPES.has(refData.nativeType)
+  );
+}
+function androidUiSelectorText(value) {
+  return `android=new UiSelector().text(${JSON.stringify(value)})`;
+}
+function androidUiSelectorDescription(value) {
+  return `android=new UiSelector().description(${JSON.stringify(value)})`;
+}
+async function findAndroidNativeOption(driver, value) {
+  for (const [selector, matchStrategy] of [
+    [androidUiSelectorText(value), "text"],
+    [androidUiSelectorDescription(value), "description"]
+  ]) {
+    try {
+      const element = await driver.$(selector);
+      if (await element.isExisting()) {
+        return { element, matchedValue: value, matchStrategy };
+      }
+    } catch {
+    }
+  }
+  return null;
+}
+function parseLogcatLine(message, timestamp, appPid) {
+  const match = message.match(LOGCAT_REGEX);
+  if (!match) return null;
+  const [, , , pid, , levelChar, tag, text] = match;
+  if (appPid && pid !== appPid) return null;
+  return {
+    level: ANDROID_LEVEL_MAP[levelChar] ?? "debug",
+    text: `[${tag.trim()}] ${text.trim()}`,
+    timestamp
+  };
+}
+var WEB_OBSERVER_SCRIPT = `
+return (function() {
+  var TAG_ROLES = {
+    A: 'link', BUTTON: 'button', INPUT: 'textbox', TEXTAREA: 'textbox',
+    SELECT: 'combobox', H1: 'heading', H2: 'heading', H3: 'heading',
+    H4: 'heading', H5: 'heading', H6: 'heading', IMG: 'image'
+  };
+
+  var vh = window.innerHeight;
+  var vw = window.innerWidth;
+  var refCounter = 0;
+  var elements = [];
+  var refs = {};
+  var lines = [];
+  var seen = {};
+
+  var all = document.querySelectorAll(
+    'a, button, input, textarea, select, h1, h2, h3, h4, h5, h6, img[alt], [role]'
+  );
+
+  for (var i = 0; i < all.length; i++) {
+    var el = all[i];
+    var rect = el.getBoundingClientRect();
+    if (rect.width === 0 && rect.height === 0) continue;
+
+    var style = window.getComputedStyle(el);
+    if (style.display === 'none' || style.visibility === 'hidden') continue;
+
+    var tag = el.tagName;
+    var ariaRole = el.getAttribute('role');
+    var role = ariaRole || TAG_ROLES[tag] || null;
+    if (!role) continue;
+
+    var name = '';
+    var ariaLabel = el.getAttribute('aria-label');
+    if (ariaLabel) {
+      name = ariaLabel;
+    } else if (tag === 'IMG') {
+      name = el.alt || '';
+    } else if (tag === 'INPUT' || tag === 'TEXTAREA') {
+      name = el.getAttribute('placeholder') || el.value || '';
+    } else {
+      name = (el.textContent || '').trim();
+    }
+
+    name = name.slice(0, 100).replace(/[\\n\\r]+/g, ' ').trim();
+    if (!name && role !== 'textbox') continue;
+
+    var key = role + ':' + name;
+    if (seen[key]) continue;
+    seen[key] = true;
+
+    refCounter++;
+    var ref = 'e' + refCounter;
+
+    var bounds = {
+      x: Math.round(rect.left),
+      y: Math.round(rect.top),
+      width: Math.round(rect.width),
+      height: Math.round(rect.height)
+    };
+
+    var offscreen = bounds.y + bounds.height < 0 || bounds.y > vh;
+
+    elements.push({ ref: ref, role: role, name: name, attributes: {} });
+    refs[ref] = { role: role, name: name, bounds: bounds };
+
+    var line = '- ' + role + ' "' + name.replace(/"/g, "'") + '" [ref=' + ref + ']';
+    if (offscreen) line += ' [offscreen]';
+    lines.push(line);
+  }
+
+  var visCount = 0, aboveCount = 0, belowCount = 0;
+  var refKeys = Object.keys(refs);
+  for (var j = 0; j < refKeys.length; j++) {
+    var b = refs[refKeys[j]].bounds;
+    if (b.y + b.height <= 0) aboveCount++;
+    else if (b.y >= vh) belowCount++;
+    else visCount++;
+  }
+
+  var header = 'Current page: ' + location.href + '\\n';
+  header += '[Viewport: ' + vw + 'x' + vh + ']';
+  if (aboveCount > 0 || belowCount > 0) {
+    header += ' [' + visCount + ' visible, ' + aboveCount + ' above, ' + belowCount + ' below]';
+  }
+
+  return {
+    tree: header + '\\n' + lines.join('\\n'),
+    elements: elements,
+    refs: refs,
+    url: location.href,
+    viewportHeight: vh,
+    viewportWidth: vw
+  };
+})();
+`;
+var AndroidPlatformAdapter = class {
+  platform = "android";
+  driver = null;
+  lastRefs = {};
+  config = null;
+  // Tracks the active web context name (e.g. 'CHROMIUM', 'WEBVIEW_...').
+  // null means last observation was native-only.
+  activeWebContext = null;
+  // Cached so we skip redundant switchContext round-trips.
+  currentContext = null;
+  // Video recording state
+  recordingEnabled = false;
+  videoDir = null;
+  videoPath = null;
+  consoleLogs = [];
+  consoleDrainIndex = 0;
+  captureConsole = true;
+  appPackage = null;
+  appPid = null;
+  async setup(config) {
+    this.config = config;
+    this.captureConsole = config.logCapture?.console !== false;
+    this.appPackage = this.config.appPackage ?? config.device?.match?.appPackage ?? null;
+    this.driver = await createAndroidSession(this.config, config.farmSession);
+    const appPackage = this.appPackage;
+    if (appPackage && !this.config.browserName && !this.config.device?.match?.browserName) {
+      try {
+        await this.driver.activateApp(appPackage);
+      } catch (err) {
+        throw new MobileSetupError2({
+          category: "app-launch",
+          message: `Failed to launch Android app "${appPackage}": ${err instanceof Error ? err.message : String(err)}`,
+          platform: "android",
+          deviceName: config.device?.name,
+          appId: appPackage,
+          cause: err
+        });
+      }
+    }
+    if (this.appPackage && this.driver) {
+      try {
+        const result = String(await this.driver.execute("mobile: shell", { command: "pidof", args: [this.appPackage] }));
+        const pid = result?.trim();
+        if (pid && /^\d+$/.test(pid)) this.appPid = pid;
+      } catch {
+      }
+    }
+    if (config.recording?.enabled && this.driver) {
+      this.videoDir = config.recording.videoDir;
+      const videoSize = config.recording.videoSize ? `${config.recording.videoSize.width}x${config.recording.videoSize.height}` : void 0;
+      try {
+        await this.driver.startRecordingScreen({ videoSize, timeLimit: 1800, forceRestart: true });
+        this.recordingEnabled = true;
+      } catch {
+        try {
+          await this.driver.execute("mobile: startScreenRecording", {
+            videoSize,
+            timeLimit: 1800,
+            forceRestart: true
+          });
+          this.recordingEnabled = true;
+        } catch {
+        }
+      }
+    }
+  }
+  async cleanup() {
+    if (this.recordingEnabled && this.driver) {
+      try {
+        await this.stopAndSaveRecording();
+      } catch {
+      }
+    }
+    try {
+      if (this.driver) {
+        await this.driver.deleteSession();
+      }
+    } catch {
+    }
+    this.driver = null;
+    this.lastRefs = {};
+    this.config = null;
+    this.consoleLogs = [];
+    this.appPackage = null;
+    this.appPid = null;
+    this.activeWebContext = null;
+    this.currentContext = null;
+    this.recordingEnabled = false;
+  }
+  // Whether we've ever successfully observed via a web context.
+  // Once true, we know a WebView/browser exists and should retry rather than
+  // falling back to native (which returns an opaque WebView and can crash UiAutomator2).
+  hasSeenWebContext = false;
+  async observe(_options) {
+    if (!this.driver) {
+      throw new Error("AndroidPlatformAdapter not initialized \u2014 call setup() first");
+    }
+    const webState = await this.tryObserveWeb();
+    if (webState) {
+      this.hasSeenWebContext = true;
+      return webState;
+    }
+    if (this.hasSeenWebContext) {
+      for (const delay of [2e3, 3e3]) {
+        await this.driver.pause(delay);
+        const retry = await this.tryObserveWeb();
+        if (retry) return retry;
+      }
+    }
+    this.activeWebContext = null;
+    try {
+      return await this.observeNative();
+    } catch {
+      return {
+        tree: "(native observation unavailable \u2014 WebView content not accessible)",
+        elements: [],
+        timestamp: Date.now(),
+        metadata: { coordSpace: "viewport", viewportWidth: 0, viewportHeight: 0 }
+      };
+    }
+  }
+  async execute(action) {
+    if (!this.driver) {
+      throw new Error("AndroidPlatformAdapter not initialized \u2014 call setup() first");
+    }
+    try {
+      if (this.activeWebContext) {
+        await this.ensureContext(this.activeWebContext);
+      }
+      return await this.executeAction(action);
+    } catch (err) {
+      let screenshot;
+      try {
+        screenshot = await this.captureScreenshot();
+      } catch {
+      }
+      return {
+        success: false,
+        error: err instanceof Error ? err.message : String(err),
+        screenshot
+      };
+    }
+  }
+  async screenshot() {
+    if (this.activeWebContext) {
+      await this.ensureContext(this.activeWebContext);
+    } else {
+      try {
+        await this.ensureContext("NATIVE_APP");
+      } catch {
+      }
+    }
+    const buf = await this.captureScreenshot();
+    if (buf && this.driver) {
+      try {
+        const { getImageDimensions } = await import("@vostride/agent-qa-core");
+        const dims = await getImageDimensions(buf);
+        const { width } = await this.driver.getWindowSize();
+        if (dims && Math.abs(dims.width - width) > 1) {
+          console.warn(`[android-adapter] screenshot width ${dims.width} != window width ${width} (coord-space divergence, handled by scaleFactor per D-19/D-20)`);
+        }
+      } catch {
+      }
+    }
+    return buf;
+  }
+  // ---------------------------------------------------------------------------
+  // Device log capture
+  // ---------------------------------------------------------------------------
+  async pollDeviceLogs() {
+    if (!this.captureConsole) return;
+    if (!this.driver) return;
+    try {
+      const logs = await this.driver.getLogs("logcat");
+      for (const entry of logs) {
+        const parsed = parseLogcatLine(entry.message, entry.timestamp ?? Date.now(), this.appPid);
+        if (!parsed) continue;
+        this.consoleLogs.push(parsed);
+      }
+      if (this.consoleLogs.length > 1e3) {
+        this.consoleLogs = this.consoleLogs.slice(-500);
+      }
+    } catch {
+    }
+  }
+  drainConsoleLogs(level) {
+    const newLogs = this.consoleLogs.slice(this.consoleDrainIndex);
+    this.consoleDrainIndex = this.consoleLogs.length;
+    if (!level) return newLogs;
+    return newLogs.filter((e) => e.level === level);
+  }
+  // ---------------------------------------------------------------------------
+  // Video recording
+  // ---------------------------------------------------------------------------
+  async getVideoPath() {
+    if (this.recordingEnabled && !this.videoPath && this.driver) {
+      await this.stopAndSaveRecording();
+    }
+    return this.videoPath;
+  }
+  async stopAndSaveRecording() {
+    if (!this.driver || !this.videoDir) return;
+    this.recordingEnabled = false;
+    let base64Video;
+    try {
+      base64Video = await this.driver.stopRecordingScreen();
+    } catch {
+      try {
+        base64Video = await this.driver.execute("mobile: stopScreenRecording");
+      } catch {
+      }
+    }
+    if (!base64Video) return;
+    const { mkdirSync, writeFileSync } = await import("fs");
+    const { join } = await import("path");
+    mkdirSync(this.videoDir, { recursive: true });
+    const filename = `android-${Date.now()}.mp4`;
+    const filePath = join(this.videoDir, filename);
+    writeFileSync(filePath, Buffer.from(base64Video, "base64"));
+    this.videoPath = filePath;
+  }
+  // ---------------------------------------------------------------------------
+  // Observation
+  // ---------------------------------------------------------------------------
+  async tryObserveWeb() {
+    const driver = this.driver;
+    try {
+      const contexts = await driver.getContexts();
+      const webCtx = contexts.find(
+        (c) => typeof c === "string" && (c.includes("CHROMIUM") || c.includes("WEBVIEW"))
+      );
+      if (!webCtx) return null;
+      await this.ensureContext(webCtx);
+      const result = await driver.execute(WEB_OBSERVER_SCRIPT);
+      if (!result || !result.elements || result.elements.length === 0) return null;
+      this.lastRefs = result.refs;
+      this.activeWebContext = webCtx;
+      return {
+        tree: result.tree,
+        elements: result.elements,
+        url: result.url,
+        timestamp: Date.now(),
+        metadata: {
+          coordSpace: "viewport",
+          viewportWidth: result.viewportWidth,
+          viewportHeight: result.viewportHeight,
+          refMap: result.refs
+        }
+      };
+    } catch {
+      return null;
+    }
+  }
+  async observeNative() {
+    const driver = this.driver;
+    await this.ensureContext("NATIVE_APP");
+    const [xml, viewport] = await Promise.all([
+      driver.getPageSource(),
+      driver.getWindowSize()
+    ]);
+    const parsed = parseMobileSource(xml, "android", viewport);
+    this.lastRefs = parsed.refs;
+    return {
+      tree: parsed.tree,
+      elements: parsed.elements,
+      timestamp: Date.now(),
+      metadata: { coordSpace: "viewport", viewportWidth: viewport.width, viewportHeight: viewport.height, refMap: parsed.refs }
+    };
+  }
+  // ---------------------------------------------------------------------------
+  // Context management
+  // ---------------------------------------------------------------------------
+  async ensureContext(target) {
+    if (this.currentContext === target) return;
+    try {
+      await this.driver.switchContext(target);
+      this.currentContext = target;
+    } catch {
+      this.currentContext = null;
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // Screenshots
+  // ---------------------------------------------------------------------------
+  async captureScreenshot() {
+    try {
+      if (this.driver) {
+        const base64 = await this.driver.takeScreenshot();
+        return Buffer.from(base64, "base64");
+      }
+      return void 0;
+    } catch {
+      return void 0;
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // Actions
+  // ---------------------------------------------------------------------------
+  async executeAction(action) {
+    const driver = this.driver;
+    const resolver = new MobileElementResolver(this.lastRefs);
+    const inWeb = !!this.activeWebContext;
+    switch (action.type) {
+      case "tap":
+      case "click": {
+        const { center, bounds } = resolver.resolve(action.ref);
+        if (inWeb) {
+          await driver.execute(
+            "var el = document.elementFromPoint(arguments[0], arguments[1]); if (el) el.click();",
+            center.x,
+            center.y
+          );
+        } else {
+          await safePerform(
+            driver.action("pointer", { parameters: { pointerType: "touch" } }).move({ x: Math.round(center.x), y: Math.round(center.y) }).down({ button: 0 }).up({ button: 0 })
+          );
+        }
+        return { success: true, coordinates: center, boundingBox: bounds };
+      }
+      case "fill": {
+        const { center, bounds } = resolver.resolve(action.ref);
+        const refData = this.lastRefs[action.ref];
+        const role = refData?.role?.toLowerCase();
+        if (role && !ANDROID_FILLABLE_ROLES.has(role)) {
+          return {
+            success: false,
+            error: `Element ${action.ref} is not fillable (role: ${role}). Use a textbox or input element instead.`
+          };
+        }
+        if (inWeb) {
+          await driver.execute(
+            "var el = document.elementFromPoint(arguments[0], arguments[1]);if (el) { el.focus(); el.click(); }",
+            center.x,
+            center.y
+          );
+          await driver.execute(
+            'var el = document.activeElement;if (el) { el.value = ""; el.value = arguments[0];el.dispatchEvent(new Event("input", {bubbles:true})); }',
+            action.value
+          );
+          return { success: true, coordinates: center, boundingBox: bounds };
+        }
+        await safePerform(
+          driver.action("pointer", { parameters: { pointerType: "touch" } }).move({ x: Math.round(center.x), y: Math.round(center.y) }).down({ button: 0 }).up({ button: 0 })
+        );
+        try {
+          const el = await driver.$('//*[@focused="true"]');
+          if (await el.isExisting()) {
+            await el.setValue(action.value);
+            return { success: true, coordinates: center, boundingBox: bounds };
+          }
+        } catch {
+        }
+        await driver.keys([action.value]);
+        return { success: true, coordinates: center, boundingBox: bounds };
+      }
+      case "select": {
+        const { center, bounds } = resolver.resolve(action.ref);
+        if (inWeb) {
+          await driver.execute(
+            'var el = document.elementFromPoint(arguments[0], arguments[1]);if (el) { el.value = arguments[2];el.dispatchEvent(new Event("change", {bubbles:true})); }',
+            center.x,
+            center.y,
+            action.value
+          );
+          return { success: true, coordinates: center, boundingBox: bounds };
+        } else {
+          return {
+            success: false,
+            error: "select is for HTML dropdowns. Use nativeSelect for Android native picker/dropdown/list controls, or tap/swipe/tapCoordinate for custom controls.",
+            coordinates: center,
+            boundingBox: bounds
+          };
+        }
+      }
+      case "nativeSelect": {
+        const { center, bounds } = resolver.resolve(action.ref);
+        const refData = this.lastRefs[action.ref];
+        if (!isAndroidNativeSelectTarget(refData)) {
+          return {
+            success: false,
+            error: "nativeSelect only supports native Android picker/dropdown/list controls. Use tap, swipe, or tapCoordinate for custom controls.",
+            coordinates: center,
+            boundingBox: bounds
+          };
+        }
+        await safePerform(
+          driver.action("pointer", { parameters: { pointerType: "touch" } }).move({ x: Math.round(center.x), y: Math.round(center.y) }).down({ button: 0 }).up({ button: 0 })
+        );
+        const option = await findAndroidNativeOption(driver, action.value);
+        if (!option) {
+          return {
+            success: false,
+            error: `Could not find native Android option "${action.value}". Open the control with tap, then use swipe/tap/tapCoordinate for custom controls.`,
+            coordinates: center,
+            boundingBox: bounds
+          };
+        }
+        if (typeof option.element.click === "function") {
+          await option.element.click();
+        } else {
+          return {
+            success: false,
+            error: `Could not click native Android option "${action.value}". Use tap, swipe, or tapCoordinate for custom controls.`,
+            coordinates: center,
+            boundingBox: bounds
+          };
+        }
+        return {
+          success: true,
+          coordinates: center,
+          boundingBox: bounds,
+          data: {
+            requestedValue: action.value,
+            matchedValue: option.matchedValue,
+            matchStrategy: option.matchStrategy
+          }
+        };
+      }
+      case "scroll": {
+        if (inWeb) {
+          const dx = action.scrollType === "horizontal" ? action.value : 0;
+          const dy = action.scrollType === "vertical" ? action.value : 0;
+          await driver.execute(
+            "window.scrollBy(arguments[0], arguments[1]);",
+            dx,
+            dy
+          );
+          return { success: true };
+        }
+        const { width, height } = await driver.getWindowSize();
+        const centerX = Math.round(width / 2);
+        const centerY = Math.round(height / 2);
+        const scrollStartX = centerX;
+        const scrollStartY = centerY;
+        const scrollEndX = action.scrollType === "horizontal" ? centerX - action.value : centerX;
+        const scrollEndY = action.scrollType === "vertical" ? centerY - action.value : centerY;
+        const scrollDuration = action.duration ?? 300;
+        await safePerform(
+          driver.action("pointer", { parameters: { pointerType: "touch" } }).move({ x: scrollStartX, y: scrollStartY }).down({ button: 0 }).move({ x: scrollEndX, y: scrollEndY, duration: scrollDuration }).up({ button: 0 })
+        );
+        return { success: true };
+      }
+      case "swipe": {
+        if (inWeb) {
+          await this.ensureContext("NATIVE_APP");
+        }
+        const { width, height } = await driver.getWindowSize();
+        let sx = Math.round(width / 2);
+        let sy = Math.round(height / 2);
+        if (action.ref) {
+          const { center } = resolver.resolve(action.ref);
+          sx = Math.round(center.x);
+          sy = Math.round(center.y);
+        }
+        const distance = Math.round(height * 0.6);
+        const pts = action.startX !== void 0 && action.startY !== void 0 && action.endX !== void 0 && action.endY !== void 0 ? {
+          startX: action.startX,
+          startY: action.startY,
+          endX: action.endX,
+          endY: action.endY
+        } : computeSwipe(sx, sy, action.direction, distance);
+        warnIfOutOfBounds({ x: pts.startX, y: pts.startY }, { width, height }, "swipe");
+        warnIfOutOfBounds({ x: pts.endX, y: pts.endY }, { width, height }, "swipe");
+        const swipeDuration = action.duration ?? 300;
+        await safePerform(
+          driver.action("pointer", { parameters: { pointerType: "touch" } }).move({ x: pts.startX, y: pts.startY }).down({ button: 0 }).move({ x: pts.endX, y: pts.endY, duration: swipeDuration }).up({ button: 0 })
+        );
+        if (inWeb) {
+          await this.ensureContext(this.activeWebContext);
+        }
+        return {
+          success: true,
+          startCoordinates: { x: pts.startX, y: pts.startY },
+          endCoordinates: { x: pts.endX, y: pts.endY }
+        };
+      }
+      case "pinch": {
+        const { width: pinchW, height: pinchH } = await driver.getWindowSize();
+        let pcx = Math.round(pinchW / 2);
+        let pcy = Math.round(pinchH / 2);
+        if (action.ref) {
+          const { center } = resolver.resolve(action.ref);
+          pcx = Math.round(center.x);
+          pcy = Math.round(center.y);
+        }
+        if (action.x !== void 0) pcx = action.x;
+        if (action.y !== void 0) pcy = action.y;
+        warnIfOutOfBounds({ x: pcx, y: pcy }, { width: pinchW, height: pinchH }, "pinch");
+        const { finger1Start, finger1End, finger2Start, finger2End } = computePinch(pcx, pcy, action.scale);
+        const pinchDuration = 500;
+        await driver.actions([
+          driver.action("pointer", { parameters: { pointerType: "touch" } }).move({ x: Math.round(finger1Start.x), y: Math.round(finger1Start.y) }).down({ button: 0 }).move({ x: Math.round(finger1End.x), y: Math.round(finger1End.y), duration: pinchDuration }).up({ button: 0 }),
+          driver.action("pointer", { parameters: { pointerType: "touch" } }).move({ x: Math.round(finger2Start.x), y: Math.round(finger2Start.y) }).down({ button: 0 }).move({ x: Math.round(finger2End.x), y: Math.round(finger2End.y), duration: pinchDuration }).up({ button: 0 })
+        ]);
+        return { success: true, coordinates: { x: pcx, y: pcy } };
+      }
+      case "multiTap": {
+        const { width: mtW, height: mtH } = await driver.getWindowSize();
+        let mtcx = Math.round(mtW / 2);
+        let mtcy = Math.round(mtH / 2);
+        if (action.ref) {
+          const { center } = resolver.resolve(action.ref);
+          mtcx = Math.round(center.x);
+          mtcy = Math.round(center.y);
+        }
+        if (action.x !== void 0) mtcx = action.x;
+        if (action.y !== void 0) mtcy = action.y;
+        warnIfOutOfBounds({ x: mtcx, y: mtcy }, { width: mtW, height: mtH }, "multiTap");
+        const positions = computeFingerPositions(mtcx, mtcy, action.fingers);
+        await driver.actions(
+          positions.map(
+            (pos) => driver.action("pointer", { parameters: { pointerType: "touch" } }).move({ x: Math.round(pos.x), y: Math.round(pos.y) }).down({ button: 0 }).pause(100).up({ button: 0 })
+          )
+        );
+        return { success: true };
+      }
+      case "longpress": {
+        const { center } = resolver.resolve(action.ref);
+        await safePerform(
+          driver.action("pointer", { parameters: { pointerType: "touch" } }).move({ x: Math.round(center.x), y: Math.round(center.y) }).down({ button: 0 }).pause(action.duration ?? 1e3).up({ button: 0 })
+        );
+        return { success: true };
+      }
+      case "waitFor": {
+        await driver.pause(action.timeout ?? 2e3);
+        return { success: true };
+      }
+      case "delay": {
+        await driver.pause(action.ms);
+        return { success: true };
+      }
+      case "keypress": {
+        for (const rawKey of action.keys) {
+          const mapped = KEY_MAP[rawKey] ?? rawKey;
+          await driver.keys([mapped]);
+        }
+        return { success: true };
+      }
+      case "navigate": {
+        try {
+          await driver.url(action.url);
+          return { success: true };
+        } catch {
+          return { success: false, error: "navigate is not supported for this app. Use tap/fill on UI elements to navigate." };
+        }
+      }
+      case "hover": {
+        return { success: false, error: "hover is a web-only action. Use tap or longpress instead." };
+      }
+      case "assert": {
+        return { success: true };
+      }
+      // --- New actions ---
+      case "hideKeyboard": {
+        try {
+          await driver.hideKeyboard();
+        } catch {
+          try {
+            await driver.execute("mobile: pressKey", { keycode: 4 });
+          } catch {
+          }
+        }
+        return { success: true };
+      }
+      case "clearText": {
+        const { center, bounds } = resolver.resolve(action.ref);
+        const clearRefData = this.lastRefs[action.ref];
+        const clearRole = clearRefData?.role?.toLowerCase();
+        if (clearRole && !ANDROID_FILLABLE_ROLES.has(clearRole)) {
+          return {
+            success: false,
+            error: `Element ${action.ref} is not fillable (role: ${clearRole}). clearText only works on text inputs. Use a textbox or input element instead.`
+          };
+        }
+        await safePerform(
+          driver.action("pointer", { parameters: { pointerType: "touch" } }).move({ x: Math.round(center.x), y: Math.round(center.y) }).down({ button: 0 }).up({ button: 0 })
+        );
+        try {
+          const el = await driver.$('//*[@focused="true"]');
+          if (await el.isExisting()) {
+            await el.clearValue();
+          }
+        } catch {
+        }
+        return { success: true, coordinates: center, boundingBox: bounds };
+      }
+      case "openLink": {
+        const appPackage = firstNonEmpty(action.appId, action.appPackage, this.appPackage);
+        const isWebUrl = /^https?:\/\//i.test(action.url);
+        if (!appPackage && !isWebUrl) {
+          return { success: false, error: `Missing Android app package for native deep link: ${action.url}` };
+        }
+        try {
+          if (appPackage) {
+            await driver.execute("mobile: deepLink", { url: action.url, package: appPackage });
+          } else {
+            await driver.url(action.url);
+          }
+          return { success: true };
+        } catch (err) {
+          if (!isWebUrl) {
+            return { success: false, error: `Failed to open link ${action.url} in Android app ${appPackage}: ${err instanceof Error ? err.message : String(err)}` };
+          }
+          try {
+            await driver.url(action.url);
+            return { success: true };
+          } catch (fallbackErr) {
+            return { success: false, error: `Failed to open link: ${action.url}: ${fallbackErr instanceof Error ? fallbackErr.message : String(fallbackErr)}` };
+          }
+        }
+      }
+      case "drag": {
+        const from = resolver.resolve(action.fromRef);
+        const to = resolver.resolve(action.toRef);
+        if (inWeb) await this.ensureContext("NATIVE_APP");
+        await safePerform(
+          driver.action("pointer", { parameters: { pointerType: "touch" } }).move({ x: Math.round(from.center.x), y: Math.round(from.center.y) }).down({ button: 0 }).pause(300).move({ x: Math.round(to.center.x), y: Math.round(to.center.y), duration: 500 }).up({ button: 0 })
+        );
+        if (inWeb) await this.ensureContext(this.activeWebContext);
+        return { success: true };
+      }
+      case "doubleTap": {
+        const { center, bounds } = resolver.resolve(action.ref);
+        const x = Math.round(center.x);
+        const y = Math.round(center.y);
+        await safePerform(
+          driver.action("pointer", { parameters: { pointerType: "touch" } }).move({ x, y }).down({ button: 0 }).up({ button: 0 }).pause(50).down({ button: 0 }).up({ button: 0 })
+        );
+        return { success: true, coordinates: center, boundingBox: bounds };
+      }
+      case "launchApp": {
+        await driver.activateApp(action.bundleId);
+        return { success: true };
+      }
+      case "stopApp": {
+        await driver.terminateApp(action.bundleId);
+        return { success: true };
+      }
+      case "setOrientation": {
+        await driver.setOrientation(action.orientation === "landscape" ? "LANDSCAPE" : "PORTRAIT");
+        return { success: true };
+      }
+      case "executeScript": {
+        const result = await driver.execute(action.command, action.args ?? {});
+        return { success: true, data: result };
+      }
+      case "tapCoordinate": {
+        const x = action.x;
+        const y = action.y;
+        const tcVp = await driver.getWindowSize();
+        warnIfOutOfBounds({ x, y }, { width: tcVp.width, height: tcVp.height }, "tapCoordinate");
+        if (inWeb) {
+          await driver.execute(
+            "var el = document.elementFromPoint(arguments[0], arguments[1]); if (el) el.click();",
+            x,
+            y
+          );
+        } else {
+          await safePerform(
+            driver.action("pointer", { parameters: { pointerType: "touch" } }).move({ x, y }).down({ button: 0 }).up({ button: 0 })
+          );
+        }
+        return { success: true, coordinates: { x, y } };
+      }
+      case "readConsoleLogs": {
+        await this.pollDeviceLogs();
+        const all = [...this.consoleLogs];
+        const entries = action.level ? all.filter((e) => e.level === action.level) : all;
+        return { success: true, data: entries };
+      }
+      default: {
+        return { success: false, error: `Unknown action type: ${action.type}` };
+      }
+    }
+  }
+};
+export {
+  AndroidPlatformAdapter,
+  createAndroidSession
+};
+//# sourceMappingURL=index.js.map