@irsprs/mobwright 0.1.0

package/dist/index.js

@@ -0,0 +1,1163 @@
+// src/fixtures/device.ts
+import { test as base } from "@playwright/test";
+
+// src/appium/session.ts
+import { remote } from "webdriverio";
+
+// src/types.ts
+var Platform = /* @__PURE__ */ ((Platform2) => {
+  Platform2["ANDROID"] = "android";
+  Platform2["IOS"] = "ios";
+  return Platform2;
+})(Platform || {});
+
+// src/appium/capabilities.ts
+function buildCapabilities(project) {
+  const { platform, device, buildPath } = project.use;
+  const base2 = {
+    // W3C capabilities require platformName as a top-level property
+    platformName: platformNameFor(platform)
+  };
+  if (platform === "android" /* ANDROID */) {
+    const caps = {
+      ...base2,
+      "appium:automationName": "UiAutomator2",
+      "appium:deviceName": device.name,
+      "appium:avd": device.name,
+      ...buildPath ? { "appium:app": resolveAppPath(buildPath) } : {},
+      "appium:autoGrantPermissions": true,
+      "appium:avdLaunchTimeout": 12e4,
+      "appium:avdReadyTimeout": 12e4,
+      "appium:noReset": false,
+      "appium:fullReset": false,
+      "appium:enforceAppInstall": false,
+      "appium:clearSystemFiles": true,
+      // Wait for any activity to become foreground (handles onboarding/splash screens)
+      "appium:appWaitActivity": "*",
+      "appium:appWaitDuration": 3e4
+    };
+    if (project.use.appActivity) {
+      caps["appium:appActivity"] = project.use.appActivity;
+    }
+    if (project.use.appPackage) {
+      caps["appium:appPackage"] = project.use.appPackage;
+    }
+    return caps;
+  }
+  if (platform === "ios" /* IOS */) {
+    const caps = {
+      ...base2,
+      "appium:automationName": "XCUITest",
+      "appium:deviceName": device.name,
+      "appium:autoAcceptAlerts": true,
+      "appium:noReset": false,
+      "appium:newCommandTimeout": 120,
+      // Give the simulator time to launch Rosetta-translated apps
+      "appium:appActivateTimeout": 12e4,
+      "appium:wdaLaunchTimeout": 18e4,
+      "appium:wdaConnectionTimeout": 18e4,
+      "appium:waitForQuiescenceTimeout": 6e4
+    };
+    if (buildPath) {
+      caps["appium:app"] = resolveAppPath(buildPath);
+    }
+    if (project.use.bundleId) {
+      caps["appium:bundleId"] = project.use.bundleId;
+    }
+    if (project.use.platformVersion) {
+      caps["appium:platformVersion"] = project.use.platformVersion;
+    }
+    if (project.use.udid) {
+      caps["appium:udid"] = project.use.udid;
+    }
+    return caps;
+  }
+  throw new Error(`Unsupported platform: ${String(platform)}`);
+}
+function platformNameFor(platform) {
+  switch (platform) {
+    case "android" /* ANDROID */:
+      return "Android";
+    case "ios" /* IOS */:
+      return "iOS";
+    default:
+      throw new Error(`Unknown platform: ${String(platform)}`);
+  }
+}
+function resolveAppPath(p) {
+  if (p.startsWith("~")) {
+    const home = process.env.HOME ?? "";
+    return p.replace(/^~/, home);
+  }
+  if (p.startsWith("./") || p.startsWith("../")) {
+    return new URL(p, `file://${process.cwd()}/`).pathname;
+  }
+  return p;
+}
+
+// src/appium/session.ts
+async function createSession(project, options = {}) {
+  const capabilities = buildCapabilities(project);
+  return await remote({
+    hostname: options.hostname ?? "127.0.0.1",
+    port: options.port ?? 4723,
+    path: options.path ?? "/",
+    logLevel: options.logLevel ?? "warn",
+    capabilities
+  });
+}
+async function destroySession(browser) {
+  try {
+    await browser.deleteSession();
+  } catch (err) {
+    console.warn("[mobwright] session teardown error (ignored):", err);
+  }
+}
+
+// src/device/selectors.ts
+function parseSelector(selector) {
+  if (selector.startsWith("~")) {
+    return { strategy: "accessibility-id", value: selector.slice(1) };
+  }
+  if (selector.startsWith("#")) {
+    return { strategy: "id", value: selector.slice(1) };
+  }
+  if (selector.startsWith("//") || selector.startsWith("(")) {
+    return { strategy: "xpath", value: selector };
+  }
+  return { strategy: "accessibility-id", value: selector };
+}
+function toWdioSelector(parsed, platform) {
+  switch (parsed.strategy) {
+    case "accessibility-id":
+      return `~${parsed.value}`;
+    case "id":
+      if (platform === "android" /* ANDROID */) {
+        return `//*[contains(@resource-id, ":id/${parsed.value}") or @resource-id="${parsed.value}"]`;
+      }
+      return `//*[@name="${parsed.value}"]`;
+    case "xpath":
+      return parsed.value;
+    case "text":
+      if (platform === "android" /* ANDROID */) {
+        return `//*[@text="${parsed.value}"]`;
+      }
+      return `//*[@label="${parsed.value}" or @name="${parsed.value}" or @value="${parsed.value}"]`;
+    default:
+      throw new Error(`Unknown selector strategy: ${String(parsed.strategy)}`);
+  }
+}
+
+// src/utils/retry.ts
+async function pollUntil(fn, options = {}) {
+  const timeout = options.timeout ?? 5e3;
+  const interval = options.interval ?? 100;
+  const message = options.message ?? `pollUntil timed out after ${timeout}ms`;
+  const deadline = Date.now() + timeout;
+  let lastError;
+  while (Date.now() < deadline) {
+    try {
+      const result = await fn();
+      if (result) return result;
+    } catch (err) {
+      lastError = err;
+    }
+    await sleep(interval);
+  }
+  const causeMsg = lastError instanceof Error ? `: ${lastError.message}` : "";
+  throw new Error(`${message}${causeMsg}`);
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// src/device/locator.ts
+var Locator = class {
+  selector;
+  browser;
+  platform;
+  defaultTimeout;
+  constructor(browser, platform, selector, options = {}) {
+    this.browser = browser;
+    this.platform = platform;
+    this.selector = selector;
+    this.defaultTimeout = options.timeout ?? 5e3;
+  }
+  /**
+   * Wait for the element to be present in the tree AND displayed.
+   * Returns the wdio element handle once ready.
+   */
+  async waitForElement(timeout = this.defaultTimeout) {
+    const wdioSelector = toWdioSelector(parseSelector(this.selector), this.platform);
+    return pollUntil(
+      async () => {
+        const el = this.browser.$(wdioSelector);
+        const exists = await el.isExisting();
+        if (!exists) return null;
+        const displayed = await el.isDisplayed();
+        if (!displayed) return null;
+        const enabled = await el.isEnabled();
+        if (!enabled) return null;
+        return el;
+      },
+      {
+        timeout,
+        message: `Locator "${this.selector}" not found or not visible after ${timeout}ms`
+      }
+    );
+  }
+  /**
+   * Tap (click) the element. Auto-waits until visible + enabled.
+   */
+  async tap() {
+    const el = await this.waitForElement();
+    await el.click();
+  }
+  /**
+   * Type text into the element. Auto-waits until visible.
+   * Clears existing content first.
+   */
+  async fill(text) {
+    const el = await this.waitForElement();
+    await el.clearValue();
+    await el.setValue(text);
+  }
+  /**
+   * Get the visible text of the element.
+   */
+  async getText() {
+    const el = await this.waitForElement();
+    return await el.getText() ?? "";
+  }
+  /**
+   * Check if the element is currently visible (no waiting).
+   * Returns false if not present.
+   */
+  async isVisible() {
+    try {
+      const wdioSelector = toWdioSelector(parseSelector(this.selector), this.platform);
+      const el = this.browser.$(wdioSelector);
+      if (!await el.isExisting()) return false;
+      return await el.isDisplayed();
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Wait for the element to become visible.
+   * Useful for explicit waits without performing an action.
+   */
+  async waitFor(options = {}) {
+    await this.waitForElement(options.timeout);
+  }
+  /**
+   * Press and hold the element for `duration` ms (long-press).
+   * Default duration: 1000 ms.
+   */
+  async tapAndHold(options = {}) {
+    const el = await this.waitForElement();
+    const duration = options.duration ?? 1e3;
+    const location = await el.getLocation();
+    const size = await el.getSize();
+    const x = Math.round(location.x + size.width / 2);
+    const y = Math.round(location.y + size.height / 2);
+    await this.browser.performActions([
+      {
+        type: "pointer",
+        id: "finger1",
+        parameters: { pointerType: "touch" },
+        actions: [
+          { type: "pointerMove", duration: 0, x, y, origin: "viewport" },
+          { type: "pointerDown", button: 0 },
+          { type: "pause", duration },
+          { type: "pointerUp", button: 0 }
+        ]
+      }
+    ]);
+    await this.browser.releaseActions();
+  }
+  // ─── Swipe gestures ────────────────────────────────────────────────────────
+  /** Swipe left within the element bounds. */
+  async swipeLeft(options = {}) {
+    await this._swipe("left", options);
+  }
+  /** Swipe right within the element bounds. */
+  async swipeRight(options = {}) {
+    await this._swipe("right", options);
+  }
+  /** Swipe up within the element bounds. */
+  async swipeUp(options = {}) {
+    await this._swipe("up", options);
+  }
+  /** Swipe down within the element bounds. */
+  async swipeDown(options = {}) {
+    await this._swipe("down", options);
+  }
+  // ─── Scroll gestures ───────────────────────────────────────────────────────
+  /**
+   * Scroll up inside a scrollable container.
+   * Slower and longer than swipeUp — use on lists/pages.
+   */
+  async scrollUp(options = {}) {
+    await this._scroll("up", options);
+  }
+  /**
+   * Scroll down inside a scrollable container.
+   * Slower and longer than swipeDown — use on lists/pages.
+   */
+  async scrollDown(options = {}) {
+    await this._scroll("down", options);
+  }
+  /**
+   * Check if the element is currently enabled (not greyed out / disabled).
+   * Returns false if not present or not enabled.
+   * Does NOT auto-wait — for retry behavior, use expect(locator).toBeEnabled().
+   */
+  async isEnabled() {
+    try {
+      const wdioSelector = toWdioSelector(parseSelector(this.selector), this.platform);
+      const el = this.browser.$(wdioSelector);
+      if (!await el.isExisting()) return false;
+      return await el.isEnabled();
+    } catch {
+      return false;
+    }
+  }
+  // ─── Private helpers ───────────────────────────────────────────────────────
+  async _swipe(direction, options = {}) {
+    const el = await this.waitForElement();
+    const duration = options.duration ?? 400;
+    const distance = options.distance ?? 0.7;
+    if (this.platform === "ios" /* IOS */) {
+      const elementId = await el.elementId;
+      await this.browser.execute("mobile: swipe", { direction, element: elementId });
+      return;
+    }
+    await this._performSwipeAction(el, direction, duration, distance);
+  }
+  async _scroll(direction, options = {}) {
+    const el = await this.waitForElement();
+    const duration = options.duration ?? 800;
+    const distance = options.distance ?? 0.8;
+    if (this.platform === "ios" /* IOS */) {
+      const elementId = await el.elementId;
+      await this.browser.execute("mobile: scroll", { direction, element: elementId });
+      return;
+    }
+    await this._performSwipeAction(el, direction, duration, distance);
+  }
+  async _performSwipeAction(el, direction, duration, distance) {
+    const location = await el.getLocation();
+    const size = await el.getSize();
+    const cx = Math.round(location.x + size.width / 2);
+    const cy = Math.round(location.y + size.height / 2);
+    const dx = Math.round(size.width * distance * 0.5);
+    const dy = Math.round(size.height * distance * 0.5);
+    const coords = {
+      left: [cx + dx, cy, cx - dx, cy],
+      right: [cx - dx, cy, cx + dx, cy],
+      up: [cx, cy + dy, cx, cy - dy],
+      down: [cx, cy - dy, cx, cy + dy]
+    };
+    const [startX, startY, endX, endY] = coords[direction];
+    await this.browser.performActions([
+      {
+        type: "pointer",
+        id: "finger1",
+        parameters: { pointerType: "touch" },
+        actions: [
+          { type: "pointerMove", duration: 0, x: startX, y: startY, origin: "viewport" },
+          { type: "pointerDown", button: 0 },
+          { type: "pause", duration: 100 },
+          { type: "pointerMove", duration, x: endX, y: endY, origin: "viewport" },
+          { type: "pointerUp", button: 0 }
+        ]
+      }
+    ]);
+    await this.browser.releaseActions();
+  }
+};
+
+// src/device/tree.ts
+async function getCleanTree(browser, platform) {
+  const raw = await browser.getPageSource();
+  return cleanTree(raw, platform);
+}
+function cleanTree(raw, platform) {
+  let cleaned = raw;
+  if (platform === "android" /* ANDROID */) {
+    cleaned = cleaned.replace(/\s+bounds="[^"]*"/g, "");
+    cleaned = cleaned.replace(/\s+index="[^"]*"/g, "");
+    cleaned = cleaned.replace(/\s+package="[^"]*"/g, "");
+    cleaned = cleaned.replace(/\s+(checkable|long-clickable|password|scrollable|selected|checked)="false"/g, "");
+    cleaned = cleaned.replace(/\s+focusable="false"/g, "");
+    cleaned = cleaned.replace(/\s+focused="false"/g, "");
+    cleaned = cleaned.replace(/\s+enabled="true"/g, "");
+    cleaned = cleaned.replace(/\s+displayed="true"/g, "");
+    cleaned = cleaned.replace(/\s+text=""/g, "");
+    cleaned = cleaned.replace(/\s+content-desc=""/g, "");
+    cleaned = cleaned.replace(/\s+resource-id=""/g, "");
+  } else {
+    cleaned = cleaned.replace(/\s+(x|y|width|height)="[^"]*"/g, "");
+    cleaned = cleaned.replace(/\s+enabled="true"/g, "");
+    cleaned = cleaned.replace(/\s+visible="true"/g, "");
+    cleaned = cleaned.replace(/\s+accessible="true"/g, "");
+    cleaned = cleaned.replace(/\s+name=""/g, "");
+    cleaned = cleaned.replace(/\s+label=""/g, "");
+    cleaned = cleaned.replace(/\s+value=""/g, "");
+  }
+  cleaned = cleaned.replace(/\s{2,}/g, " ");
+  cleaned = cleaned.replace(/^<\?xml[^?]*\?>\s*/, "");
+  return cleaned.trim();
+}
+var CHARS_PER_TOKEN = 4;
+var DEFAULT_TREE_CHAR_BUDGET = 12e3;
+function fitTreeToBudget(tree, budget = DEFAULT_TREE_CHAR_BUDGET) {
+  if (tree.length <= budget) return tree;
+  console.warn(
+    `[mobwright] accessibility tree (${tree.length} chars) exceeds budget (${budget} chars). Truncating \u2014 AI may miss elements beyond the cutoff.`
+  );
+  return tree.slice(0, budget) + "\n<!-- ...truncated -->";
+}
+function estimateTokens(text) {
+  return Math.ceil(text.length / CHARS_PER_TOKEN);
+}
+
+// src/ai/errors.ts
+var AIError = class extends Error {
+  constructor(message, cause) {
+    super(message);
+    this.cause = cause;
+    this.name = "AIError";
+  }
+  cause;
+};
+var AIRequestError = class extends AIError {
+  constructor(message, cause) {
+    super(message, cause);
+    this.name = "AIRequestError";
+  }
+};
+var AIResponseError = class extends AIError {
+  constructor(message, raw, cause) {
+    super(message, cause);
+    this.raw = raw;
+    this.name = "AIResponseError";
+  }
+  raw;
+};
+var AIValidationError = class extends AIError {
+  constructor(message, cause) {
+    super(message, cause);
+    this.name = "AIValidationError";
+  }
+};
+
+// src/device/ai-locator.ts
+var AILocator = class {
+  description;
+  browser;
+  platform;
+  provider;
+  options;
+  /** Cached resolution. Populated on first action. */
+  resolved = null;
+  /** Cached underlying Locator. Populated on first action. */
+  locator = null;
+  constructor(browser, platform, provider, description, options = {}) {
+    this.browser = browser;
+    this.platform = platform;
+    this.provider = provider;
+    this.description = description;
+    this.options = {
+      timeout: options.timeout ?? 5e3,
+      minConfidence: options.minConfidence ?? 0.5,
+      treeCharBudget: options.treeCharBudget ?? 12e3
+    };
+  }
+  /**
+   * Resolve the description to a Locator. Called automatically on first action.
+   * Exposed for advanced use / debugging.
+   */
+  async resolve() {
+    if (this.locator) return this.locator;
+    const tree = await getCleanTree(this.browser, this.platform);
+    const bounded = fitTreeToBudget(tree, this.options.treeCharBudget);
+    const result = await this.provider.resolveLocator({
+      description: this.description,
+      accessibilityTree: bounded,
+      platform: this.platform
+    });
+    this.validate(result);
+    this.resolved = result;
+    const selector = this.buildSelectorString(result);
+    this.locator = new Locator(this.browser, this.platform, selector, {
+      timeout: this.options.timeout
+    });
+    console.log(
+      `[mobwright.ai] "${this.description}" \u2192 ${selector} (${result.strategy}, confidence ${result.confidence})`
+    );
+    return this.locator;
+  }
+  /** Validate the AI's response before trusting it. */
+  validate(result) {
+    if (result.confidence < this.options.minConfidence) {
+      throw new AIValidationError(
+        `AI returned low confidence (${result.confidence}) for "${this.description}". Rationale: ${result.rationale ?? "(none)"}
+Try a more specific description, or use device.locator() directly.`
+      );
+    }
+    if (!result.selector || result.selector.trim().length === 0) {
+      throw new AIValidationError(
+        `AI returned empty selector for "${this.description}".`
+      );
+    }
+  }
+  /** Build a mobwright selector string from the AI's strategy + value. */
+  buildSelectorString(result) {
+    switch (result.strategy) {
+      case "accessibility-id":
+        return `~${result.selector}`;
+      case "id":
+        return `#${result.selector}`;
+      case "xpath":
+        return result.selector;
+      case "text":
+        return this.platform === "android" /* ANDROID */ ? `//*[@text="${result.selector}"]` : `//*[@label="${result.selector}" or @name="${result.selector}" or @value="${result.selector}"]`;
+      default: {
+        const _exhaustive = result.strategy;
+        throw new AIError(`Unknown selector strategy from AI: ${String(_exhaustive)}`);
+      }
+    }
+  }
+  /** Tap the resolved element. Resolves on first call. */
+  async tap() {
+    const locator = await this.resolve();
+    await locator.tap();
+  }
+  /** Type text into the resolved element. */
+  async fill(text) {
+    const locator = await this.resolve();
+    await locator.fill(text);
+  }
+  /** Get the visible text of the resolved element. */
+  async getText() {
+    const locator = await this.resolve();
+    return locator.getText();
+  }
+  /** Check visibility of the resolved element (snapshot, no waiting). */
+  async isVisible() {
+    try {
+      const locator = await this.resolve();
+      return locator.isVisible();
+    } catch {
+      return false;
+    }
+  }
+  /** Wait for the resolved element to be visible. */
+  async waitFor(options = {}) {
+    const locator = await this.resolve();
+    await locator.waitFor(options);
+  }
+  /** Check if the resolved element is enabled (snapshot, no waiting). */
+  async isEnabled() {
+    try {
+      const locator = await this.resolve();
+      return locator.isEnabled();
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Inspect the resolved selector. Returns null if not yet resolved.
+   * Useful for debugging or "save back to a stable selector" workflows.
+   */
+  getResolved() {
+    return this.resolved;
+  }
+};
+
+// src/device/device.ts
+var Device = class {
+  stub = false;
+  project;
+  platform;
+  browser;
+  /** Optional AI provider — only set if AI is configured. */
+  aiProvider;
+  defaultTimeout;
+  constructor(browser, project, aiProvider) {
+    this.browser = browser;
+    this.project = project.name;
+    this.platform = project.use.platform;
+    this.defaultTimeout = project.use.actionTimeout ?? 5e3;
+    this.aiProvider = aiProvider;
+  }
+  /**
+   * Create a lazy reference to a UI element by selector string.
+   *
+   * Selector syntax:
+   *   ~foo     → accessibility id
+   *   #foo     → resource id (ends-with match; package prefix optional)
+   *   //...    → xpath
+   *   foo      → accessibility id (no prefix)
+   */
+  locator(selector, options = {}) {
+    return new Locator(this.browser, this.platform, selector, {
+      timeout: options.timeout ?? this.defaultTimeout
+    });
+  }
+  /**
+   * Convenience: locate an element by its visible text or label (exact match).
+   */
+  getByText(text, options = {}) {
+    const xpath = this.platform === "android" /* ANDROID */ ? `//*[@text="${text}"]` : `//*[@label="${text}" or @name="${text}" or @value="${text}"]`;
+    return new Locator(this.browser, this.platform, xpath, {
+      timeout: options.timeout ?? this.defaultTimeout
+    });
+  }
+  /**
+   * Locate an element whose visible text **contains** the substring.
+   * Case-insensitive by default.
+   *
+   * @example
+   *   device.getByContainingText('get started');   // matches "Get Started", "GET STARTED", etc.
+   *   device.getByContainingText('Started', { ignoreCase: false }); // case-sensitive substring
+   */
+  getByContainingText(text, options = {}) {
+    const ignoreCase = options.ignoreCase ?? true;
+    const lc = "abcdefghijklmnopqrstuvwxyz";
+    const uc = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";
+    let xpath;
+    if (this.platform === "android" /* ANDROID */) {
+      xpath = ignoreCase ? `//*[contains(translate(@text,"${uc}","${lc}"),"${text.toLowerCase()}")]` : `//*[contains(@text,"${text}")]`;
+    } else {
+      xpath = ignoreCase ? `//*[contains(translate(@label,"${uc}","${lc}"),"${text.toLowerCase()}") or contains(translate(@name,"${uc}","${lc}"),"${text.toLowerCase()}") or contains(translate(@value,"${uc}","${lc}"),"${text.toLowerCase()}")]` : `//*[contains(@label,"${text}") or contains(@name,"${text}") or contains(@value,"${text}")]`;
+    }
+    return new Locator(this.browser, this.platform, xpath, {
+      timeout: options.timeout ?? this.defaultTimeout
+    });
+  }
+  /**
+   * Take a screenshot. Returns raw PNG bytes.
+   */
+  async screenshot() {
+    const base64 = await this.browser.takeScreenshot();
+    return Buffer.from(base64, "base64");
+  }
+  /**
+   * Get the current accessibility tree as an XML string.
+   * Used later by AI locator resolution.
+   */
+  async getPageSource() {
+    return await this.browser.getPageSource();
+  }
+  /**
+  * Create a natural-language locator. Resolves on first action via AI.
+  *
+  * Requires AI to be configured (MOBWRIGHT_AI_PROVIDER + MOBWRIGHT_AI_API_KEY).
+  * Throws AIError immediately if AI is not configured.
+  *
+  * @example
+  *   await device.ai('the blue Continue button at the bottom').tap();
+  *   await device.ai('the email input field').fill('me@example.com');
+  */
+  ai(description, options = {}) {
+    if (!this.aiProvider) {
+      throw new AIError(
+        "device.ai() requires an AI provider. Set MOBWRIGHT_AI_PROVIDER and MOBWRIGHT_AI_API_KEY in your environment."
+      );
+    }
+    return new AILocator(this.browser, this.platform, this.aiProvider, description, {
+      timeout: options.timeout ?? this.defaultTimeout,
+      minConfidence: options.minConfidence,
+      treeCharBudget: options.treeCharBudget
+    });
+  }
+  /**
+   * Get cumulative token usage from the AI provider (if it tracks tokens).
+   * Returns null if AI is not configured or if the provider doesn't support token tracking.
+   */
+  getAITokenUsage() {
+    if (!this.aiProvider || !("getTokenUsage" in this.aiProvider)) {
+      return null;
+    }
+    return this.aiProvider.getTokenUsage();
+  }
+};
+
+// src/ai/openai.ts
+import OpenAI from "openai";
+
+// src/ai/prompts.ts
+var LOCATOR_SYSTEM_PROMPT = `
+You are a mobile UI testing assistant. Given an accessibility tree from
+a mobile app and a natural-language description of a target element,
+return a concrete selector to find that element.
+
+Your response MUST be valid JSON with this shape:
+{
+  "selector": "string \u2014 the locator value",
+  "strategy": "accessibility-id" | "id" | "xpath" | "text",
+  "confidence": 0.0\u20131.0,
+  "rationale": "string \u2014 brief explanation"
+}
+
+Selector formats by strategy:
+- accessibility-id: just the value (no prefix). Maps to content-desc (Android) or name (iOS).
+- id: just the value (no prefix). Maps to resource-id suffix (Android) or name (iOS).
+- xpath: full xpath expression starting with //
+- text: just the visible text value
+
+Prefer accessibility-id > id > text > xpath, in that order.
+Lower confidence (<0.7) if you are guessing.
+Return ONLY the JSON, no markdown fences, no extra prose.
+`.trim();
+function buildUserPrompt(input) {
+  return [
+    `Platform: ${input.platform}`,
+    `Target element: ${input.description}`,
+    "",
+    "Accessibility tree:",
+    input.accessibilityTree
+  ].join("\n");
+}
+
+// src/ai/openai.ts
+var OpenAICompatibleProvider = class {
+  name;
+  client;
+  model;
+  constructor(config) {
+    this.name = config.name ?? "openai";
+    this.model = config.model;
+    this.client = new OpenAI({
+      apiKey: config.apiKey,
+      baseURL: config.baseURL,
+      timeout: config.timeout ?? 3e4
+    });
+  }
+  async resolveLocator(input) {
+    let response;
+    try {
+      response = await this.client.chat.completions.create({
+        model: this.model,
+        messages: [
+          { role: "system", content: LOCATOR_SYSTEM_PROMPT },
+          { role: "user", content: buildUserPrompt(input) }
+        ],
+        // Many recent OpenAI/DeepSeek models support JSON mode
+        response_format: { type: "json_object" },
+        temperature: 0
+      });
+    } catch (err) {
+      throw new AIRequestError(`${this.name} request failed`, err);
+    }
+    const raw = response.choices[0]?.message?.content;
+    if (!raw) {
+      throw new AIResponseError(`${this.name} returned empty content`);
+    }
+    return parseLocatorResponse(raw, this.name);
+  }
+};
+function parseLocatorResponse(raw, providerName) {
+  let parsed;
+  try {
+    const cleaned = raw.replace(/^```(?:json)?\s*|\s*```$/g, "").trim();
+    parsed = JSON.parse(cleaned);
+  } catch (err) {
+    throw new AIResponseError(`${providerName} returned non-JSON`, raw, err);
+  }
+  if (!parsed || typeof parsed !== "object") {
+    throw new AIResponseError(`${providerName} returned non-object`, raw);
+  }
+  const obj = parsed;
+  const selector = obj.selector;
+  const strategy = obj.strategy;
+  const confidence = obj.confidence;
+  if (typeof selector !== "string" || selector.length === 0) {
+    throw new AIResponseError(`${providerName}: missing or invalid "selector"`, raw);
+  }
+  if (!isValidStrategy(strategy)) {
+    throw new AIResponseError(
+      `${providerName}: invalid "strategy" \u2014 got ${String(strategy)}`,
+      raw
+    );
+  }
+  if (typeof confidence !== "number" || confidence < 0 || confidence > 1) {
+    throw new AIResponseError(
+      `${providerName}: invalid "confidence" \u2014 got ${String(confidence)}`,
+      raw
+    );
+  }
+  const rationale = typeof obj.rationale === "string" ? obj.rationale : void 0;
+  return { selector, strategy, confidence, rationale };
+}
+function isValidStrategy(value) {
+  return value === "accessibility-id" || value === "id" || value === "xpath" || value === "text";
+}
+
+// src/ai/deepseek.ts
+var DeepSeekProvider = class extends OpenAICompatibleProvider {
+  constructor(config) {
+    super({
+      name: "deepseek",
+      apiKey: config.apiKey,
+      model: config.model || "deepseek-chat",
+      baseURL: config.baseURL ?? "https://api.deepseek.com",
+      timeout: config.timeout
+    });
+  }
+};
+
+// src/ai/anthropic.ts
+import Anthropic from "@anthropic-ai/sdk";
+var AnthropicProvider = class {
+  name = "anthropic";
+  client;
+  model;
+  totalInputTokens = 0;
+  totalOutputTokens = 0;
+  constructor(config) {
+    this.model = config.model;
+    this.client = new Anthropic({
+      apiKey: config.apiKey,
+      baseURL: config.baseURL,
+      timeout: config.timeout ?? 3e4
+    });
+  }
+  async resolveLocator(input) {
+    let response;
+    try {
+      response = await this.client.messages.create({
+        model: this.model,
+        max_tokens: 1024,
+        system: LOCATOR_SYSTEM_PROMPT,
+        messages: [{ role: "user", content: buildUserPrompt(input) }],
+        temperature: 0
+      });
+    } catch (err) {
+      throw new AIRequestError(`${this.name} request failed`, err);
+    }
+    const text = response.content.filter((block) => block.type === "text").map((block) => block.text).join("").trim();
+    if (!text) {
+      throw new AIResponseError(`${this.name} returned no text content`);
+    }
+    const usage = response.usage;
+    if (!usage) {
+      return parseLocatorResponse(text, this.name);
+    }
+    this.totalInputTokens += usage.input_tokens;
+    this.totalOutputTokens += usage.output_tokens;
+    const totalTokens = usage.input_tokens + usage.output_tokens;
+    console.log(
+      `[${this.name}] tokens: ${usage.input_tokens} in + ${usage.output_tokens} out = ${totalTokens} total`
+    );
+    return parseLocatorResponse(text, this.name);
+  }
+  /** Get cumulative token usage across all requests. */
+  getTokenUsage() {
+    return {
+      inputTokens: this.totalInputTokens,
+      outputTokens: this.totalOutputTokens,
+      totalTokens: this.totalInputTokens + this.totalOutputTokens
+    };
+  }
+};
+
+// src/ai/factory.ts
+var DEFAULT_MODELS = {
+  anthropic: "claude-haiku-4-5-20251001",
+  openai: "gpt-4o-mini",
+  deepseek: "deepseek-chat"
+};
+function createProvider(config) {
+  const model = config.model || DEFAULT_MODELS[config.provider];
+  switch (config.provider) {
+    case "anthropic":
+      return new AnthropicProvider({
+        apiKey: config.apiKey,
+        model,
+        baseURL: config.baseURL,
+        timeout: config.timeout
+      });
+    case "openai":
+      return new OpenAICompatibleProvider({
+        apiKey: config.apiKey,
+        model,
+        baseURL: config.baseURL,
+        timeout: config.timeout,
+        name: "openai"
+      });
+    case "deepseek":
+      return new DeepSeekProvider({
+        apiKey: config.apiKey,
+        model,
+        baseURL: config.baseURL,
+        timeout: config.timeout
+      });
+    default: {
+      const _exhaustive = config.provider;
+      throw new Error(`Unknown AI provider: ${String(_exhaustive)}`);
+    }
+  }
+}
+
+// src/appium/ios-utils.ts
+import { execFile } from "child_process";
+import { promisify } from "util";
+var exec = promisify(execFile);
+async function isIOSAppInstalled(bundleId, udid) {
+  const target = udid ?? "booted";
+  try {
+    const { stdout } = await exec("xcrun", [
+      "simctl",
+      "get_app_container",
+      target,
+      bundleId,
+      "app"
+    ]);
+    return stdout.trim().length > 0;
+  } catch {
+    return false;
+  }
+}
+
+// src/fixtures/device.ts
+function resolveProjectConfig(projectName) {
+  if (projectName === "android") {
+    const appPath = process.env.MOBWRIGHT_APP_PATH;
+    if (!appPath) {
+      throw new Error(
+        "MOBWRIGHT_APP_PATH is not set. Point it at your .apk:\n  MOBWRIGHT_APP_PATH=/absolute/path/to/app.apk"
+      );
+    }
+    const avd = process.env.MOBWRIGHT_ANDROID_AVD;
+    if (!avd) {
+      throw new Error(
+        "MOBWRIGHT_ANDROID_AVD is not set. Set your emulator AVD name:\n  MOBWRIGHT_ANDROID_AVD=Pixel_9_Pro_API_Baklava"
+      );
+    }
+    return {
+      name: "android",
+      use: {
+        platform: "android" /* ANDROID */,
+        device: { provider: "emulator", name: avd },
+        buildPath: appPath,
+        appActivity: process.env.MOBWRIGHT_ANDROID_APP_ACTIVITY,
+        appPackage: process.env.MOBWRIGHT_ANDROID_APP_PACKAGE
+      }
+    };
+  }
+  if (projectName === "ios") {
+    const sim = process.env.MOBWRIGHT_IOS_DEVICE ?? "iPhone 15";
+    const bundleId = process.env.MOBWRIGHT_IOS_BUNDLE_ID;
+    const appPath = process.env.MOBWRIGHT_IOS_APP_PATH;
+    if (!bundleId && !appPath) {
+      throw new Error(
+        "iOS needs MOBWRIGHT_IOS_BUNDLE_ID, MOBWRIGHT_IOS_APP_PATH, or both:\n  MOBWRIGHT_IOS_BUNDLE_ID=com.voila.id\n  MOBWRIGHT_IOS_APP_PATH=/absolute/path/to/Voila.app"
+      );
+    }
+    return {
+      name: "ios",
+      use: {
+        platform: "ios" /* IOS */,
+        device: { provider: "simulator", name: sim },
+        buildPath: appPath ?? "",
+        bundleId,
+        platformVersion: process.env.MOBWRIGHT_IOS_PLATFORM_VERSION,
+        udid: process.env.MOBWRIGHT_IOS_UDID
+      }
+    };
+  }
+  throw new Error(`Unknown mobwright project: ${projectName}. Use 'android' or 'ios'.`);
+}
+async function reconcileIOSInstall(project) {
+  if (project.use.platform !== "ios" /* IOS */) return project;
+  if (!project.use.bundleId) return project;
+  const installed = await isIOSAppInstalled(project.use.bundleId, project.use.udid);
+  if (installed) {
+    console.log(
+      `[mobwright] ${project.use.bundleId} already installed \u2014 launching by bundleId`
+    );
+    return {
+      ...project,
+      use: { ...project.use, buildPath: "" }
+    };
+  }
+  if (!project.use.buildPath) {
+    throw new Error(
+      `iOS app ${project.use.bundleId} is not installed on the simulator and MOBWRIGHT_IOS_APP_PATH is not set. Either install the app manually or provide MOBWRIGHT_IOS_APP_PATH.`
+    );
+  }
+  console.log(
+    `[mobwright] ${project.use.bundleId} not installed \u2014 installing from ${project.use.buildPath}`
+  );
+  return project;
+}
+var test = base.extend({
+  // eslint-disable-next-line no-empty-pattern
+  device: async ({}, use, testInfo) => {
+    let projectConfig = resolveProjectConfig(testInfo.project.name);
+    projectConfig = await reconcileIOSInstall(projectConfig);
+    const aiConfig = resolveAIConfig();
+    const aiProvider = aiConfig ? createProvider(aiConfig) : void 0;
+    const browser = await createSession(projectConfig);
+    const device = new Device(browser, projectConfig, aiProvider);
+    try {
+      await use(device);
+    } finally {
+      await destroySession(browser);
+    }
+  }
+});
+function resolveAIConfig() {
+  const provider = process.env.MOBWRIGHT_AI_PROVIDER;
+  const apiKey = process.env.MOBWRIGHT_AI_API_KEY;
+  if (!provider || !apiKey) return void 0;
+  if (provider !== "anthropic" && provider !== "openai" && provider !== "deepseek") {
+    throw new Error(
+      `MOBWRIGHT_AI_PROVIDER must be one of 'anthropic', 'openai', 'deepseek' \u2014 got '${provider}'`
+    );
+  }
+  return {
+    provider,
+    model: process.env.MOBWRIGHT_AI_MODEL ?? "",
+    apiKey,
+    baseURL: process.env.MOBWRIGHT_AI_BASE_URL
+  };
+}
+
+// src/expect/matchers.ts
+import { expect as baseExpect } from "@playwright/test";
+var DEFAULT_TIMEOUT = 5e3;
+var POLL_INTERVAL = 100;
+async function pollUntilTrue(fn, timeout) {
+  const deadline = Date.now() + timeout;
+  while (Date.now() < deadline) {
+    try {
+      if (await fn()) return true;
+    } catch {
+    }
+    await new Promise((r) => setTimeout(r, POLL_INTERVAL));
+  }
+  try {
+    return await fn();
+  } catch {
+    return false;
+  }
+}
+function matchText(actual, expected) {
+  if (expected instanceof RegExp) return expected.test(actual);
+  return actual === expected;
+}
+function containsText(actual, expected, options = {}) {
+  if (expected instanceof RegExp) return expected.test(actual);
+  const ignoreCase = options.ignoreCase ?? true;
+  if (ignoreCase) {
+    return actual.toLowerCase().includes(expected.toLowerCase());
+  }
+  return actual.includes(expected);
+}
+var expect = baseExpect.extend({
+  /**
+   * Assert the element is currently visible (present + displayed).
+   * Auto-retries until visible or timeout.
+   */
+  async toBeVisible(received, options = {}) {
+    const timeout = options.timeout ?? DEFAULT_TIMEOUT;
+    const pass = await pollUntilTrue(() => received.isVisible(), timeout);
+    return {
+      pass,
+      name: "toBeVisible",
+      message: () => pass ? `Expected locator "${received.selector}" NOT to be visible, but it was.` : `Expected locator "${received.selector}" to be visible within ${timeout}ms, but it was not.`
+    };
+  },
+  /**
+   * Assert the element's visible text matches.
+   * Pass a string for exact match, or a RegExp for pattern match.
+   * Auto-retries until match or timeout.
+   */
+  async toHaveText(received, expected, options = {}) {
+    const timeout = options.timeout ?? DEFAULT_TIMEOUT;
+    let lastText = "";
+    const pass = await pollUntilTrue(async () => {
+      lastText = await received.getText();
+      return matchText(lastText, expected);
+    }, timeout);
+    return {
+      pass,
+      name: "toHaveText",
+      expected,
+      actual: lastText,
+      message: () => pass ? `Expected locator "${received.selector}" NOT to have text ${JSON.stringify(expected)}, but it did.` : `Expected locator "${received.selector}" to have text ${JSON.stringify(expected)} within ${timeout}ms, but got ${JSON.stringify(lastText)}.`
+    };
+  },
+  /**
+   * Assert the element's visible text **contains** the expected substring.
+   * Case-insensitive by default. Pass `ignoreCase: false` for exact-case check.
+   * Also accepts a RegExp.
+   * Auto-retries until match or timeout.
+   */
+  async toContainText(received, expected, options = {}) {
+    const timeout = options.timeout ?? DEFAULT_TIMEOUT;
+    let lastText = "";
+    const pass = await pollUntilTrue(async () => {
+      lastText = await received.getText();
+      return containsText(lastText, expected, { ignoreCase: options.ignoreCase });
+    }, timeout);
+    return {
+      pass,
+      name: "toContainText",
+      expected,
+      actual: lastText,
+      message: () => pass ? `Expected locator "${received.selector}" NOT to contain text ${JSON.stringify(expected)}, but it did (got ${JSON.stringify(lastText)}).` : `Expected locator "${received.selector}" to contain text ${JSON.stringify(expected)} within ${timeout}ms, but got ${JSON.stringify(lastText)}.`
+    };
+  },
+  /**
+   * Assert the element is enabled (interactable).
+   * Auto-retries until enabled or timeout.
+   */
+  async toBeEnabled(received, options = {}) {
+    const timeout = options.timeout ?? DEFAULT_TIMEOUT;
+    if (!received.isEnabled) {
+      throw new Error(
+        `Locator "${received.selector}" does not support isEnabled(). Make sure you're using the latest mobwright version.`
+      );
+    }
+    const pass = await pollUntilTrue(() => received.isEnabled(), timeout);
+    return {
+      pass,
+      name: "toBeEnabled",
+      message: () => pass ? `Expected locator "${received.selector}" NOT to be enabled, but it was.` : `Expected locator "${received.selector}" to be enabled within ${timeout}ms, but it was not.`
+    };
+  }
+});
+
+// src/config.ts
+function defineConfig(config) {
+  return config;
+}
+export {
+  AIError,
+  AILocator,
+  AIRequestError,
+  AIResponseError,
+  AIValidationError,
+  AnthropicProvider,
+  DEFAULT_TREE_CHAR_BUDGET,
+  DeepSeekProvider,
+  Device,
+  Locator,
+  OpenAICompatibleProvider,
+  Platform,
+  cleanTree,
+  createProvider,
+  defineConfig,
+  estimateTokens,
+  expect,
+  fitTreeToBudget,
+  getCleanTree,
+  test
+};
+//# sourceMappingURL=index.js.map