prowl-tools 0.1.5 → 0.1.7

package/dist/{chunk-2KD2XCTH.js → chunk-R7NUH44M.js}

@@ -7,7 +7,7 @@ import {
   loadHunt,
   loadHuntTags,
   resolveViewport
-} from "./chunk-ITOSUJCN.js";
+} from "./chunk-O3OUTZ2P.js";
 
 // src/config/interpolate.ts
 import crypto from "crypto";
@@ -303,6 +303,11 @@ function interpolateStep(step, vars, stepPath2, redacted) {
       }
     };
   }
+  if ("assertWithAI" in step) {
+    return {
+      assertWithAI: interpolateString(step.assertWithAI, vars).value
+    };
+  }
   if ("copyText" in step) {
     return {
       copyText: {
@@ -752,27 +757,71 @@ function createMacDriver(client, options = {}) {
   };
 }
 
+// src/browser/macdriver-release.ts
+import os from "os";
+import path2 from "path";
+var HELPER_BINARY = "prowl-macdriver";
+var MACDRIVER_VERSION = "0.1.0";
+var MACDRIVER_REPO = "prowl-tools/prowl";
+var MACDRIVER_SIGNING_IDENTIFIER = "tools.prowl.macdriver";
+var MACDRIVER_SIGNING_AUTHORITY_PREFIX = "Developer ID Application: Genkei Labs";
+var MACDRIVER_VERSION_PATTERN = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z][0-9A-Za-z.-]*)?(?:\+[0-9A-Za-z][0-9A-Za-z.-]*)?$/;
+function validateMacdriverVersion(version) {
+  if (!MACDRIVER_VERSION_PATTERN.test(version)) {
+    throw new Error(
+      `Invalid prowl-macdriver version "${version}". Expected a release version like 0.1.0.`
+    );
+  }
+  return version;
+}
+function macdriverReleaseTag(version = MACDRIVER_VERSION) {
+  return `macdriver-v${validateMacdriverVersion(version)}`;
+}
+function macdriverAssetName(version = MACDRIVER_VERSION) {
+  return `prowl-macdriver-v${validateMacdriverVersion(version)}-universal.zip`;
+}
+function macdriverChecksumName(version = MACDRIVER_VERSION) {
+  return `${macdriverAssetName(version)}.sha256`;
+}
+function macdriverAssetUrl(assetName, version = MACDRIVER_VERSION) {
+  return `https://github.com/${MACDRIVER_REPO}/releases/download/${macdriverReleaseTag(version)}/${assetName}`;
+}
+function macdriverInstallRoot(homedir = os.homedir()) {
+  return path2.join(homedir, ".prowl", "macdriver");
+}
+function macdriverVersionDir(version = MACDRIVER_VERSION, homedir = os.homedir()) {
+  const root = path2.resolve(macdriverInstallRoot(homedir));
+  const versionDir = path2.resolve(root, validateMacdriverVersion(version));
+  if (!versionDir.startsWith(root + path2.sep)) {
+    throw new Error(`Resolved prowl-macdriver version directory escaped install root: ${versionDir}`);
+  }
+  return versionDir;
+}
+function macdriverInstalledBinary(version = MACDRIVER_VERSION, homedir = os.homedir()) {
+  return path2.join(macdriverVersionDir(version, homedir), HELPER_BINARY);
+}
+
 // src/browser/mac-helper.ts
 import { spawn } from "child_process";
 import fs2 from "fs";
-import path2 from "path";
+import os2 from "os";
+import path3 from "path";
 import { fileURLToPath } from "url";
-var HELPER_BINARY = "prowl-macdriver";
 function macdriverBuildInstructions() {
-  return "The macOS target requires the experimental `prowl-macdriver` helper, which is not shipped in the npm package. Build it locally:\n  cd macdriver && swift build -c release\nor point Prowl at a prebuilt binary via the PROWL_MACDRIVER_BIN environment variable.";
+  return "The macOS target needs the `prowl-macdriver` helper. Install the prebuilt, signed binary (recommended):\n  prowl macdriver install\nContributors building from source can instead run:\n  cd macdriver && swift build -c release\nor point Prowl at a prebuilt binary via the PROWL_MACDRIVER_BIN environment variable.";
 }
 function getPackageRoot() {
-  let dir = path2.dirname(fileURLToPath(import.meta.url));
-  const root = path2.parse(dir).root;
+  let dir = path3.dirname(fileURLToPath(import.meta.url));
+  const root = path3.parse(dir).root;
   while (dir !== root) {
-    if (fs2.existsSync(path2.join(dir, "package.json"))) {
+    if (fs2.existsSync(path3.join(dir, "package.json"))) {
       return dir;
     }
-    dir = path2.dirname(dir);
+    dir = path3.dirname(dir);
   }
   return root;
 }
-function resolveHelperBinary(env = process.env) {
+function resolveHelperBinary(env = process.env, options = {}) {
   const override = env.PROWL_MACDRIVER_BIN;
   if (override) {
     if (!fs2.existsSync(override)) {
@@ -783,10 +832,15 @@ ${macdriverBuildInstructions()}`
     }
     return override;
   }
+  const homedir = options.homedir ?? os2.homedir();
+  const userBinary = macdriverInstalledBinary(MACDRIVER_VERSION, homedir);
+  if (fs2.existsSync(userBinary)) {
+    return userBinary;
+  }
   const root = getPackageRoot();
   const candidates = [
-    path2.join(root, "macdriver", ".build", "release", HELPER_BINARY),
-    path2.join(root, "macdriver", ".build", "debug", HELPER_BINARY)
+    path3.join(root, "macdriver", ".build", "release", HELPER_BINARY),
+    path3.join(root, "macdriver", ".build", "debug", HELPER_BINARY)
   ];
   for (const candidate of candidates) {
     if (fs2.existsSync(candidate)) {
@@ -958,6 +1012,287 @@ async function closeMacSession(session) {
   }
 }
 
+// src/analyzer/xml.ts
+var ENTITIES = {
+  amp: "&",
+  lt: "<",
+  gt: ">",
+  quot: '"',
+  apos: "'"
+};
+function decodeXmlEntities(value) {
+  if (!value.includes("&")) {
+    return value;
+  }
+  return value.replace(/&(#(?:[xX][0-9a-fA-F]+|[0-9]+)|[a-zA-Z]+);/g, (match, code) => {
+    if (code[0] === "#") {
+      const hex = code[1] === "x" || code[1] === "X";
+      const num2 = Number.parseInt(code.slice(hex ? 2 : 1), hex ? 16 : 10);
+      return Number.isSafeInteger(num2) && num2 <= 1114111 ? String.fromCodePoint(num2) : match;
+    }
+    const named = ENTITIES[code];
+    return named ?? match;
+  });
+}
+var ATTR_RE = /([^\s=/]+)\s*=\s*("([^"]*)"|'([^']*)')/g;
+function parseTagBody(body) {
+  const trimmed = body.trim();
+  const nameMatch = /^([^\s/>]+)/.exec(trimmed);
+  const tag = nameMatch ? nameMatch[1] : "";
+  const attrs = {};
+  const rest = trimmed.slice(tag.length);
+  ATTR_RE.lastIndex = 0;
+  let m;
+  while ((m = ATTR_RE.exec(rest)) !== null) {
+    const rawValue = m[3] !== void 0 ? m[3] : m[4] ?? "";
+    attrs[m[1]] = decodeXmlEntities(rawValue);
+  }
+  return { tag, attrs };
+}
+function parseXml(input) {
+  const n = input.length;
+  const stack = [];
+  let root = null;
+  let i = 0;
+  while (i < n) {
+    const lt = input.indexOf("<", i);
+    if (lt < 0) {
+      break;
+    }
+    i = lt + 1;
+    const ch = input[i];
+    if (ch === "?") {
+      const end = input.indexOf("?>", i);
+      i = end < 0 ? n : end + 2;
+      continue;
+    }
+    if (ch === "!") {
+      if (input.startsWith("!--", i)) {
+        const end = input.indexOf("-->", i);
+        i = end < 0 ? n : end + 3;
+      } else {
+        const end = input.indexOf(">", i);
+        i = end < 0 ? n : end + 1;
+      }
+      continue;
+    }
+    if (ch === "/") {
+      const gt = input.indexOf(">", i);
+      i = gt < 0 ? n : gt + 1;
+      stack.pop();
+      continue;
+    }
+    let j = i;
+    let quote2 = null;
+    while (j < n) {
+      const c = input[j];
+      if (quote2 !== null) {
+        if (c === quote2) {
+          quote2 = null;
+        }
+      } else if (c === '"' || c === "'") {
+        quote2 = c;
+      } else if (c === ">") {
+        break;
+      }
+      j += 1;
+    }
+    const inner = input.slice(i, j);
+    i = j + 1;
+    const selfClose = inner.endsWith("/");
+    const body = selfClose ? inner.slice(0, -1) : inner;
+    const { tag, attrs } = parseTagBody(body);
+    if (tag.length === 0) {
+      continue;
+    }
+    const element = { tag, attrs, children: [] };
+    const parent = stack[stack.length - 1];
+    if (parent) {
+      parent.children.push(element);
+    }
+    if (root === null) {
+      root = element;
+    }
+    if (!selfClose) {
+      stack.push(element);
+    }
+  }
+  return root;
+}
+
+// src/selector/native.ts
+function unquoteSelectorValue(value) {
+  const trimmed = value.trim();
+  const first = trimmed[0];
+  if ((first === '"' || first === "'") && trimmed.endsWith(first) && trimmed.length >= 2) {
+    return trimmed.slice(1, -1);
+  }
+  return trimmed;
+}
+function quoteSelectorValue(value) {
+  return `"${value}"`;
+}
+var ROLE_SELECTOR_RE = /^role=([A-Za-z][\w.$-]*)(?:\[name=(.+)\])?$/s;
+var NATIVE_SELECTOR_PREFIX_RE = /^(id|label|text|role)=/;
+function invalidSelectorMessage(selector, reason) {
+  return `Invalid native selector ${JSON.stringify(selector)}: ${reason}.`;
+}
+function parseNativeSelector(selector) {
+  const trimmed = selector.trim();
+  if (trimmed.length === 0) {
+    throw new Error(
+      invalidSelectorMessage(
+        selector,
+        "selector is empty; use id=, label=, text=, role=, :focus, or a bare text value"
+      )
+    );
+  }
+  if (trimmed === ":focus") {
+    return { kind: "focused" };
+  }
+  const idMatch = /^id=(.+)$/s.exec(trimmed);
+  if (idMatch) {
+    return { kind: "id", value: unquoteSelectorValue(idMatch[1]) };
+  }
+  const roleMatch = ROLE_SELECTOR_RE.exec(trimmed);
+  if (roleMatch) {
+    const name = roleMatch[2] !== void 0 ? unquoteSelectorValue(roleMatch[2]) : void 0;
+    return name !== void 0 && name.length > 0 ? { kind: "role", role: roleMatch[1], name } : { kind: "role", role: roleMatch[1] };
+  }
+  const labelMatch = /^label=(.+)$/s.exec(trimmed);
+  if (labelMatch) {
+    return { kind: "label", value: unquoteSelectorValue(labelMatch[1]) };
+  }
+  const textMatch = /^text=(.+)$/s.exec(trimmed);
+  if (textMatch) {
+    return { kind: "text", value: unquoteSelectorValue(textMatch[1]) };
+  }
+  const prefix = NATIVE_SELECTOR_PREFIX_RE.exec(trimmed);
+  if (prefix) {
+    throw new Error(
+      invalidSelectorMessage(
+        selector,
+        `malformed ${prefix[1]}= selector; expected id=<value>, label=<value>, text=<value>, or role=<Type>[name=<value>]`
+      )
+    );
+  }
+  return { kind: "text", value: trimmed };
+}
+function unwrapNativeTextSelector(selector) {
+  const trimmed = selector.trim();
+  if (!trimmed.startsWith("text=")) {
+    return null;
+  }
+  return unquoteSelectorValue(trimmed.slice("text=".length));
+}
+function qualifyResourceId(value, appPackage) {
+  if (value.includes(":") || !appPackage) {
+    return value;
+  }
+  return `${appPackage}:id/${value}`;
+}
+function normalizeXcuiClassName(role) {
+  return role.startsWith("XCUIElementType") ? role : `XCUIElementType${role}`;
+}
+function shortIosType(type) {
+  return type.startsWith("XCUIElementType") ? type.slice("XCUIElementType".length) : type;
+}
+function rankNativeSelectors(fields) {
+  const selectors = [];
+  if (fields.id) {
+    selectors.push(`id=${fields.id}`);
+  }
+  if (fields.label) {
+    selectors.push(`label=${quoteSelectorValue(fields.label)}`);
+  }
+  if (fields.role && fields.name) {
+    selectors.push(`role=${fields.role}[name=${quoteSelectorValue(fields.name)}]`);
+  }
+  if (fields.name) {
+    selectors.push(`text=${quoteSelectorValue(fields.name)}`);
+  }
+  if (selectors.length === 0 && fields.role) {
+    selectors.push(`role=${fields.role}`);
+  }
+  return selectors;
+}
+var NATIVE_ATTRIBUTE_MAP = {
+  android: {
+    id: { attribute: "resource-id", match: "exact (package-qualified)" },
+    label: { attribute: "content-desc", match: "exact" },
+    text: { attribute: "text", match: "substring" },
+    role: { attribute: "class", match: "exact" }
+  },
+  ios: {
+    id: { attribute: "accessibility id (name)", match: "exact" },
+    label: { attribute: "label", match: "exact" },
+    text: { attribute: "label | value", match: "substring" },
+    role: { attribute: "type (XCUIElementType\u2026)", match: "exact" }
+  },
+  macos: {
+    id: { attribute: "AXIdentifier", match: "exact" },
+    label: { attribute: "title | description", match: "exact" },
+    text: { attribute: "title | description | value", match: "substring" },
+    role: { attribute: "AXRole", match: "exact" }
+  }
+};
+var ANDROID_MATCH_DIALECT = {
+  platform: "android",
+  normalizeRole: (role) => role,
+  normalizeId: (value, options) => qualifyResourceId(value, options.appPackage)
+};
+var IOS_MATCH_DIALECT = {
+  platform: "ios",
+  normalizeRole: (role) => normalizeXcuiClassName(role),
+  normalizeId: (value) => value
+};
+var MACOS_MATCH_DIALECT = {
+  platform: "macos",
+  normalizeRole: (role) => role,
+  normalizeId: (value) => value
+};
+function nodeMatchesSelector(dialect, selector, node, options = {}) {
+  switch (selector.kind) {
+    case "id":
+      return node.id !== void 0 && node.id === dialect.normalizeId(selector.value, options);
+    case "label":
+      return node.label !== void 0 && node.label === selector.value;
+    case "text":
+      return node.textValues.some((t) => t.includes(selector.value));
+    case "focused":
+      return node.focused === true;
+    case "role": {
+      if (node.role === void 0) {
+        return false;
+      }
+      if (dialect.normalizeRole(node.role) !== dialect.normalizeRole(selector.role)) {
+        return false;
+      }
+      if (selector.name === void 0 || selector.name.length === 0) {
+        return true;
+      }
+      const name = selector.name;
+      return node.textValues.some((t) => t.includes(name));
+    }
+  }
+}
+function matchNativeTree(dialect, selector, root, project, children, options = {}) {
+  const out = [];
+  const visit = (node) => {
+    if (nodeMatchesSelector(dialect, selector, project(node), options)) {
+      out.push(node);
+    }
+    for (const child of children(node)) {
+      visit(child);
+    }
+  };
+  visit(root);
+  return out;
+}
+function parseSnapshot(xml) {
+  return parseXml(xml);
+}
+
 // src/browser/android-driver.ts
 import fs3 from "fs";
 var ANDROID_CAPABILITIES = /* @__PURE__ */ new Set([
@@ -993,50 +1328,29 @@ var ANDROID_KEYCODES = {
   pageup: 92,
   pagedown: 93
 };
-function unquote2(value) {
-  const trimmed = value.trim();
-  const first = trimmed[0];
-  if ((first === '"' || first === "'") && trimmed.endsWith(first) && trimmed.length >= 2) {
-    return trimmed.slice(1, -1);
-  }
-  return trimmed;
-}
 function escapeUiSelectorArg(value) {
   return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
 }
-function parseAndroidSelector(selector) {
-  const trimmed = selector.trim();
-  if (trimmed === ":focus") {
-    return { by: "focused" };
-  }
-  const idMatch = /^id=(.+)$/s.exec(trimmed);
-  if (idMatch) {
-    return { by: "id", value: unquote2(idMatch[1]) };
-  }
-  const roleMatch = /^role=([A-Za-z][\w.$-]*)(?:\[name=(.+)\])?$/s.exec(trimmed);
-  if (roleMatch) {
-    const name = roleMatch[2] !== void 0 ? unquote2(roleMatch[2]) : void 0;
-    return name !== void 0 && name.length > 0 ? { by: "role", role: roleMatch[1], name } : { by: "role", role: roleMatch[1] };
-  }
-  const labelMatch = /^label=(.+)$/s.exec(trimmed);
-  if (labelMatch) {
-    return { by: "accessibilityId", value: unquote2(labelMatch[1]) };
-  }
-  const textMatch = /^text=(.+)$/s.exec(trimmed);
-  if (textMatch) {
-    return { by: "text", value: unquote2(textMatch[1]) };
+function toAndroidQuery(selector) {
+  switch (selector.kind) {
+    case "focused":
+      return { by: "focused" };
+    case "id":
+      return { by: "id", value: selector.value };
+    case "role":
+      return selector.name !== void 0 ? { by: "role", role: selector.role, name: selector.name } : { by: "role", role: selector.role };
+    case "label":
+      return { by: "accessibilityId", value: selector.value };
+    case "text":
+      return { by: "text", value: selector.value };
   }
-  return { by: "text", value: trimmed };
+}
+function parseAndroidSelector(selector) {
+  return toAndroidQuery(parseNativeSelector(selector));
 }
 function locator(strategy, selector) {
   return { strategy, selector, context: "" };
 }
-function qualifyResourceId(value, appPackage) {
-  if (value.includes(":") || !appPackage) {
-    return value;
-  }
-  return `${appPackage}:id/${value}`;
-}
 function androidQueryToLocator(query, options = {}) {
   switch (query.by) {
     case "id":
@@ -1063,11 +1377,7 @@ function androidQueryToLocator(query, options = {}) {
   }
 }
 function unwrapAndroidTextSelector(selector) {
-  const trimmed = selector.trim();
-  if (!trimmed.startsWith("text=")) {
-    return null;
-  }
-  return unquote2(trimmed.slice(5));
+  return unwrapNativeTextSelector(selector);
 }
 function keyCodeFor(key) {
   const code = ANDROID_KEYCODES[key.trim().toLowerCase()];
@@ -1342,22 +1652,63 @@ async function installApk(runner, serial, apkPath) {
     );
   }
 }
+function formatUnknownError(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function runnerPhaseError(message, error) {
+  return new Error(`${message}: ${formatUnknownError(error)}`, { cause: error });
+}
+function parseResolvedComponent(stdout, pkg) {
+  const lines = stdout.split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
+  for (let i = lines.length - 1; i >= 0; i--) {
+    if (/^[\w.]+\/[\w.$]+$/.test(lines[i]) && lines[i].startsWith(`${pkg}/`)) {
+      return lines[i];
+    }
+  }
+  return null;
+}
 async function launchPackage(runner, serial, pkg) {
-  const result = await runner(
-    withSerial(serial, [
-      "shell",
-      "monkey",
-      "-p",
-      pkg,
-      "-c",
-      "android.intent.category.LAUNCHER",
-      "1"
-    ]),
-    { timeoutMs: 3e4 }
-  );
-  if (result.code !== 0 || /no activities found|aborted|cannot launch/i.test(result.stdout + result.stderr)) {
+  let resolved;
+  try {
+    resolved = await runner(
+      withSerial(serial, [
+        "shell",
+        "cmd",
+        "package",
+        "resolve-activity",
+        "--brief",
+        "-c",
+        "android.intent.category.LAUNCHER",
+        pkg
+      ]),
+      { timeoutMs: 3e4 }
+    );
+  } catch (error) {
+    throw runnerPhaseError(
+      `Failed to resolve the launcher activity for Android package "${pkg}" via adb`,
+      error
+    );
+  }
+  const component = parseResolvedComponent(resolved.stdout, pkg);
+  if (resolved.code !== 0 || !component) {
+    throw new Error(
+      `Could not resolve a launcher activity for Android package "${pkg}" (exit ${resolved.code})${(resolved.stdout + resolved.stderr).trim() ? `: ${(resolved.stdout + resolved.stderr).trim().slice(0, 300)}` : ""}. Is it installed?`
+    );
+  }
+  let start;
+  try {
+    start = await runner(withSerial(serial, ["shell", "am", "start", "-n", component]), {
+      timeoutMs: 3e4
+    });
+  } catch (error) {
+    throw runnerPhaseError(
+      `Failed to launch Android package "${pkg}" with \`am start\` (${component}) via adb`,
+      error
+    );
+  }
+  if (start.code !== 0 || /error|does not exist|cannot start/i.test(start.stdout + start.stderr)) {
     throw new Error(
-      `Failed to launch Android package "${pkg}" (exit ${result.code}): ${(result.stdout + result.stderr).trim().slice(0, 400)}. Is it installed?`
+      `Failed to launch Android package "${pkg}" (${component}, exit ${start.code}): ${(start.stdout + start.stderr).trim().slice(0, 400)}.`
     );
   }
 }
@@ -1419,12 +1770,12 @@ var Uia2Transport = class {
    * {@link Uia2HttpError} on a non-2xx response, or a timeout error when the
    * per-request deadline elapses.
    */
-  async request(method, path16, body, timeoutMs) {
+  async request(method, path18, body, timeoutMs) {
     const requestTimeoutMs = timeoutMs ?? this.requestTimeoutMs;
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), requestTimeoutMs);
     timer.unref?.();
-    const url = `${this.baseUrl}${path16}`;
+    const url = `${this.baseUrl}${path18}`;
     let response;
     try {
       response = await this.fetchImpl(url, {
@@ -1436,7 +1787,7 @@ var Uia2Transport = class {
     } catch (error) {
       if (controller.signal.aborted) {
         const shown = requestTimeoutMs >= 1e3 ? `${Math.round(requestTimeoutMs / 1e3)}s` : `${requestTimeoutMs}ms`;
-        throw new Error(`uiautomator2 request ${method} ${path16} timed out after ${shown}`);
+        throw new Error(`uiautomator2 request ${method} ${path18} timed out after ${shown}`);
       }
       throw error instanceof Error ? error : new Error(String(error));
     } finally {
@@ -1447,7 +1798,7 @@ var Uia2Transport = class {
     if (!response.ok) {
       const wdError = extractWebdriverError(parsed);
       throw new Uia2HttpError(
-        `uiautomator2 ${method} ${path16} failed (${response.status})${wdError ? `: ${wdError}` : ""}`,
+        `uiautomator2 ${method} ${path18} failed (${response.status})${wdError ? `: ${wdError}` : ""}`,
         response.status,
         wdError
       );
@@ -1530,10 +1881,10 @@ function sleep(ms) {
 }
 function createUia2AgentClient(transport, sessionId, options = {}) {
   const base = `/session/${sessionId}`;
-  async function locate(query, path16) {
+  async function locate(query, path18) {
     return transport.request(
       "POST",
-      `${base}${path16}`,
+      `${base}${path18}`,
       androidQueryToLocator(query, { appPackage: options.appPackage })
     );
   }
@@ -1575,6 +1926,13 @@ function createUia2AgentClient(transport, sessionId, options = {}) {
       }
       return Buffer.from(value, "base64");
     },
+    async source() {
+      const value = await transport.request("GET", `${base}/source`);
+      if (typeof value !== "string") {
+        throw new Error("uiautomator2 /source did not return XML text; cannot analyze Android UI hierarchy");
+      }
+      return value;
+    },
     async close() {
       await transport.request("DELETE", base).catch(() => void 0);
     }
@@ -1585,7 +1943,7 @@ function createUia2AgentClient(transport, sessionId, options = {}) {
 import { createRequire } from "module";
 import { execFile as execFile2 } from "child_process";
 import fs4 from "fs";
-import path3 from "path";
+import path4 from "path";
 var UIA2_REMOTE_PORT = 6790;
 function resolveAgentApks(requireFn = createRequire(import.meta.url)) {
   let pkgJsonPath;
@@ -1596,10 +1954,10 @@ function resolveAgentApks(requireFn = createRequire(import.meta.url)) {
       "The Android target requires the `appium-uiautomator2-server` package (its prebuilt APKs). It is an optional dependency of prowl-tools; it may have been skipped (--omit=optional) or failed to install. Restore it for a global Prowl install with: npm install -g appium-uiautomator2-server@10.6.2. If Prowl is installed locally in a project, run: npm install appium-uiautomator2-server@10.6.2"
     );
   }
-  const pkgDir = path3.dirname(pkgJsonPath);
+  const pkgDir = path4.dirname(pkgJsonPath);
   const version = requireFn(pkgJsonPath).version;
-  const serverApk = path3.join(pkgDir, "apks", `appium-uiautomator2-server-v${version}.apk`);
-  const testApk = path3.join(pkgDir, "apks", "appium-uiautomator2-server-debug-androidTest.apk");
+  const serverApk = path4.join(pkgDir, "apks", `appium-uiautomator2-server-v${version}.apk`);
+  const testApk = path4.join(pkgDir, "apks", "appium-uiautomator2-server-debug-androidTest.apk");
   for (const apk of [serverApk, testApk]) {
     if (!fs4.existsSync(apk)) {
       throw new Error(`Expected uiautomator2 agent APK is missing: ${apk}. Reinstall dependencies.`);
@@ -1647,7 +2005,7 @@ async function resolvePackage(app, runner, serial, aaptResolver, allowedApps) {
     assertAndroidAppAllowed(allowedApps, app);
     return app;
   }
-  const apkPath = path3.resolve(app);
+  const apkPath = path4.resolve(app);
   if (!fs4.existsSync(apkPath)) {
     throw new Error(`APK not found: ${apkPath}`);
   }
@@ -1729,43 +2087,25 @@ var IOS_CAPABILITIES = /* @__PURE__ */ new Set([
 var WAIT_POLL_INTERVAL_MS2 = 250;
 var DEFAULT_WAIT_TIMEOUT_MS2 = 5e3;
 var IOS_PRESS_KEYS = ["backspace", "del", "delete", "enter", "home", "return"];
-function unquote3(value) {
-  const trimmed = value.trim();
-  const first = trimmed[0];
-  if ((first === '"' || first === "'") && trimmed.endsWith(first) && trimmed.length >= 2) {
-    return trimmed.slice(1, -1);
-  }
-  return trimmed;
-}
 function escapePredicateArg(value) {
   return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
 }
-function normalizeXcuiClassName(role) {
-  return role.startsWith("XCUIElementType") ? role : `XCUIElementType${role}`;
+function toIosQuery(selector) {
+  switch (selector.kind) {
+    case "focused":
+      return { by: "focused" };
+    case "id":
+      return { by: "accessibilityId", value: selector.value };
+    case "role":
+      return selector.name !== void 0 ? { by: "role", role: selector.role, name: selector.name } : { by: "role", role: selector.role };
+    case "label":
+      return { by: "label", value: selector.value };
+    case "text":
+      return { by: "text", value: selector.value };
+  }
 }
 function parseIosSelector(selector) {
-  const trimmed = selector.trim();
-  if (trimmed === ":focus") {
-    return { by: "focused" };
-  }
-  const idMatch = /^id=(.+)$/s.exec(trimmed);
-  if (idMatch) {
-    return { by: "accessibilityId", value: unquote3(idMatch[1]) };
-  }
-  const roleMatch = /^role=([A-Za-z][\w.$-]*)(?:\[name=(.+)\])?$/s.exec(trimmed);
-  if (roleMatch) {
-    const name = roleMatch[2] !== void 0 ? unquote3(roleMatch[2]) : void 0;
-    return name !== void 0 && name.length > 0 ? { by: "role", role: roleMatch[1], name } : { by: "role", role: roleMatch[1] };
-  }
-  const labelMatch = /^label=(.+)$/s.exec(trimmed);
-  if (labelMatch) {
-    return { by: "label", value: unquote3(labelMatch[1]) };
-  }
-  const textMatch = /^text=(.+)$/s.exec(trimmed);
-  if (textMatch) {
-    return { by: "text", value: unquote3(textMatch[1]) };
-  }
-  return { by: "text", value: trimmed };
+  return toIosQuery(parseNativeSelector(selector));
 }
 function iosQueryToLocator(query) {
   switch (query.by) {
@@ -1797,11 +2137,7 @@ function iosQueryToLocator(query) {
   }
 }
 function unwrapIosTextSelector(selector) {
-  const trimmed = selector.trim();
-  if (!trimmed.startsWith("text=")) {
-    return null;
-  }
-  return unquote3(trimmed.slice(5));
+  return unwrapNativeTextSelector(selector);
 }
 function delay2(ms) {
   return new Promise((resolve) => {
@@ -1960,12 +2296,25 @@ function createIosDriver(client, options) {
 }
 
 // src/browser/ios-simctl.ts
-import { execFile as execFile3 } from "child_process";
+import { execFile as execFile3, spawn as spawn3 } from "child_process";
 import { mkdir, readFile, rm, writeFile } from "fs/promises";
 import net from "net";
-import os from "os";
-import path4 from "path";
-var DEFAULT_SIMULATOR_LOCK_ROOT = path4.join(os.tmpdir(), "prowl-ios-simulator-locks");
+import os3 from "os";
+import path5 from "path";
+var spawnXcrunProcess = (args, options) => {
+  const child = spawn3("xcrun", args, {
+    stdio: "ignore",
+    env: options?.env ? { ...process.env, ...options.env } : process.env
+  });
+  child.on("error", () => {
+  });
+  return {
+    kill: () => {
+      child.kill();
+    }
+  };
+};
+var DEFAULT_SIMULATOR_LOCK_ROOT = path5.join(os3.tmpdir(), "prowl-ios-simulator-locks");
 var SIMULATOR_LOCK_OWNER_FILE = "owner.json";
 var execFileXcrunRunner = (args, options) => new Promise((resolve) => {
   execFile3(
@@ -2005,7 +2354,7 @@ function isProcessAlive(pid) {
 }
 async function removeStaleSimulatorLock(lockPath) {
   try {
-    const ownerText = await readFile(path4.join(lockPath, SIMULATOR_LOCK_OWNER_FILE), "utf8");
+    const ownerText = await readFile(path5.join(lockPath, SIMULATOR_LOCK_OWNER_FILE), "utf8");
     const owner = JSON.parse(ownerText);
     if (typeof owner.pid === "number" && Number.isInteger(owner.pid) && owner.pid > 0 && !isProcessAlive(owner.pid)) {
       await rm(lockPath, { recursive: true, force: true });
@@ -2023,7 +2372,7 @@ function simulatorReservedError(udid) {
 }
 async function reserveSimulatorUdid(udid, options = {}) {
   const lockRoot = options.lockRoot ?? DEFAULT_SIMULATOR_LOCK_ROOT;
-  const lockPath = path4.join(lockRoot, simulatorLockName(udid));
+  const lockPath = path5.join(lockRoot, simulatorLockName(udid));
   await mkdir(lockRoot, { recursive: true });
   for (let attempt = 0; attempt < 2; attempt += 1) {
     try {
@@ -2047,7 +2396,7 @@ async function reserveSimulatorUdid(udid, options = {}) {
     };
     try {
       await writeFile(
-        path4.join(lockPath, SIMULATOR_LOCK_OWNER_FILE),
+        path5.join(lockPath, SIMULATOR_LOCK_OWNER_FILE),
         `${JSON.stringify({ pid: process.pid, udid, createdAt: (/* @__PURE__ */ new Date()).toISOString() })}
 `,
         { flag: "wx" }
@@ -2239,15 +2588,15 @@ var WdaTransport = class {
    * {@link WdaHttpError} on a non-2xx response, or a timeout error when the
    * per-request deadline elapses.
    */
-  async requestFull(method, path16, body, timeoutMs) {
+  async requestFull(method, path18, body, timeoutMs) {
     const requestTimeoutMs = timeoutMs ?? this.requestTimeoutMs;
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), requestTimeoutMs);
     timer.unref?.();
-    const url = `${this.baseUrl}${path16}`;
+    const url = `${this.baseUrl}${path18}`;
     const timeoutError = () => {
       const shown = requestTimeoutMs >= 1e3 ? `${Math.round(requestTimeoutMs / 1e3)}s` : `${requestTimeoutMs}ms`;
-      return new Error(`WebDriverAgent request ${method} ${path16} timed out after ${shown}`);
+      return new Error(`WebDriverAgent request ${method} ${path18} timed out after ${shown}`);
     };
     let response;
     try {
@@ -2279,7 +2628,7 @@ var WdaTransport = class {
     if (!response.ok) {
       const wdError = extractWebdriverError2(parsed);
       throw new WdaHttpError(
-        `WebDriverAgent ${method} ${path16} failed (${response.status})${wdError ? `: ${wdError}` : ""}`,
+        `WebDriverAgent ${method} ${path18} failed (${response.status})${wdError ? `: ${wdError}` : ""}`,
         response.status,
         wdError
       );
@@ -2287,8 +2636,8 @@ var WdaTransport = class {
     return parsed;
   }
   /** Like {@link requestFull} but returns just the `value` field. */
-  async request(method, path16, body, timeoutMs) {
-    const parsed = await this.requestFull(method, path16, body, timeoutMs);
+  async request(method, path18, body, timeoutMs) {
+    const parsed = await this.requestFull(method, path18, body, timeoutMs);
     return parsed?.value;
   }
 };
@@ -2364,8 +2713,8 @@ function sleep2(ms) {
 }
 function createWdaAgentClient(transport, sessionId) {
   const base = `/session/${sessionId}`;
-  async function locate(query, path16) {
-    return transport.request("POST", `${base}${path16}`, iosQueryToLocator(query));
+  async function locate(query, path18) {
+    return transport.request("POST", `${base}${path18}`, iosQueryToLocator(query));
   }
   return {
     async findElement(query) {
@@ -2401,6 +2750,13 @@ function createWdaAgentClient(transport, sessionId) {
     async homescreen() {
       await transport.request("POST", "/wda/homescreen", {});
     },
+    async source() {
+      const value = await transport.request("GET", "/source");
+      if (typeof value !== "string") {
+        throw new Error("WebDriverAgent /source did not return XML text; cannot analyze iOS UI hierarchy");
+      }
+      return value;
+    },
     async close() {
       await transport.request("DELETE", base).catch(() => void 0);
     }
@@ -2409,12 +2765,13 @@ function createWdaAgentClient(transport, sessionId) {
 
 // src/browser/ios-helper.ts
 import { createRequire as createRequire2 } from "module";
+import { execFile as execFile4 } from "child_process";
 import fs5 from "fs";
-import os2 from "os";
-import path5 from "path";
+import os4 from "os";
+import path6 from "path";
 var WDA_RUNNER_BUNDLE_ID = "com.facebook.WebDriverAgentRunner.xctrunner";
-var WDA_RUNNER_APP_NAME = "WebDriverAgentRunner-Runner.app";
 var WDA_USE_PORT_ENV = "USE_PORT";
+var PREPARED_XCTESTRUN_PREFIX = "prowl-wda-xctestrun-";
 var WDA_STARTUP_ATTEMPTS = 2;
 var defaultIosAgentConnector = async ({
   host,
@@ -2437,32 +2794,63 @@ function resolveWdaProject(requireFn = createRequire2(import.meta.url)) {
       "The iOS target requires the `appium-webdriveragent` package (its WDA Xcode project). It is an optional dependency of prowl-tools; it may have been skipped (--omit=optional) or failed to install. Restore it for a global Prowl install with: npm install -g appium-webdriveragent@16.4.0. If Prowl is installed locally in a project, run: npm install appium-webdriveragent@16.4.0"
     );
   }
-  const pkgDir = path5.dirname(pkgJsonPath);
+  const pkgDir = path6.dirname(pkgJsonPath);
   const version = requireFn(pkgJsonPath).version;
-  const projectPath = path5.join(pkgDir, "WebDriverAgent.xcodeproj");
+  const projectPath = path6.join(pkgDir, "WebDriverAgent.xcodeproj");
   if (!fs5.existsSync(projectPath)) {
     throw new Error(`Expected WebDriverAgent project is missing: ${projectPath}. Reinstall dependencies.`);
   }
   return { projectPath, version };
 }
-function wdaCacheDir(wdaVersion, xcode, homeDir = os2.homedir()) {
-  return path5.join(homeDir, ".prowl", "wda", `${wdaVersion}-xcode${xcode}`);
+function wdaCacheDir(wdaVersion, xcode, homeDir = os4.homedir()) {
+  return path6.join(homeDir, ".prowl", "wda", `${wdaVersion}-xcode${xcode}`);
 }
-function runnerAppPath(derivedDataPath) {
-  return path5.join(derivedDataPath, "Build", "Products", "Debug-iphonesimulator", WDA_RUNNER_APP_NAME);
+function productsDir(derivedDataPath) {
+  return path6.join(derivedDataPath, "Build", "Products");
 }
-async function resolveWdaRunner(options = {}) {
-  const runner = options.runner ?? execFileXcrunRunner;
-  const env = options.env ?? process.env;
-  const homeDir = options.homeDir ?? os2.homedir();
-  const log = options.logger ?? ((message) => process.stderr.write(`${message}
-`));
+function findXctestrunIn(dir) {
+  let entries;
+  try {
+    entries = fs5.readdirSync(dir);
+  } catch {
+    return null;
+  }
+  const match = entries.filter((name) => name.endsWith(".xctestrun") && !name.startsWith(PREPARED_XCTESTRUN_PREFIX)).sort()[0];
+  return match ? path6.join(dir, match) : null;
+}
+function resolveOverrideXctestrun(override) {
+  if (!fs5.existsSync(override)) {
+    throw new Error(`PROWL_WDA_RUNNER points at a missing path: ${override}`);
+  }
+  if (override.endsWith(".xctestrun")) {
+    return override;
+  }
+  const candidates = [];
+  const stat = fs5.statSync(override);
+  if (override.endsWith(".app")) {
+    candidates.push(path6.dirname(path6.dirname(override)));
+  } else if (stat.isDirectory()) {
+    candidates.push(override, productsDir(override));
+  }
+  for (const dir of candidates) {
+    const found = findXctestrunIn(dir);
+    if (found) {
+      return found;
+    }
+  }
+  throw new Error(
+    `PROWL_WDA_RUNNER (${override}) does not resolve to a WebDriverAgent .xctestrun. Point it at the generated \`*.xctestrun\`, at the \`-derivedDataPath\` directory from \`xcodebuild build-for-testing\`, or at that build's runner \`.app\`.`
+  );
+}
+async function resolveWdaTestRun(options = {}) {
+  const runner = options.runner ?? execFileXcrunRunner;
+  const env = options.env ?? process.env;
+  const homeDir = options.homeDir ?? os4.homedir();
+  const log = options.logger ?? ((message) => process.stderr.write(`${message}
+`));
   const override = env.PROWL_WDA_RUNNER;
   if (override) {
-    if (!fs5.existsSync(override)) {
-      throw new Error(`PROWL_WDA_RUNNER points at a missing path: ${override}`);
-    }
-    return override;
+    return resolveOverrideXctestrun(override);
   }
   const { projectPath, version } = resolveWdaProject(options.requireFn);
   const xcode = await xcodeVersion(runner);
@@ -2472,9 +2860,9 @@ async function resolveWdaRunner(options = {}) {
     );
   }
   const cacheDir = wdaCacheDir(version, xcode, homeDir);
-  const cachedRunner = runnerAppPath(cacheDir);
-  if (fs5.existsSync(cachedRunner)) {
-    return cachedRunner;
+  const cached = findXctestrunIn(productsDir(cacheDir));
+  if (cached) {
+    return cached;
   }
   log(
     `Prowl: building WebDriverAgent for the iOS target (first run only; this can take a few minutes)\u2026`
@@ -2501,12 +2889,106 @@ async function resolveWdaRunner(options = {}) {
       `Failed to build WebDriverAgent with \`xcodebuild build-for-testing\`. Ensure a full Xcode (not just the command-line tools) is installed and selected (\`xcode-select -p\`). Details: ${(result.stderr.trim() || result.stdout.trim()).slice(-800)}`
     );
   }
-  if (!fs5.existsSync(cachedRunner)) {
+  const built = findXctestrunIn(productsDir(cacheDir));
+  if (!built) {
+    throw new Error(
+      `WebDriverAgent build succeeded but no .xctestrun was found under ${productsDir(cacheDir)}. This may indicate an Xcode layout change; set PROWL_WDA_RUNNER to a prebuilt runner/xctestrun.`
+    );
+  }
+  return built;
+}
+function injectUsePortIntoXctestrun(plist, port) {
+  const clone = structuredClone(plist);
+  let injected = 0;
+  const visit = (node) => {
+    if (Array.isArray(node)) {
+      for (const entry of node) {
+        visit(entry);
+      }
+      return;
+    }
+    if (!node || typeof node !== "object") {
+      return;
+    }
+    const obj = node;
+    const isTarget = typeof obj.TestBundlePath === "string" || typeof obj.TestHostPath === "string";
+    const existingEnv = obj.EnvironmentVariables && typeof obj.EnvironmentVariables === "object" && !Array.isArray(obj.EnvironmentVariables) ? obj.EnvironmentVariables : void 0;
+    if (isTarget || existingEnv) {
+      const env = existingEnv ?? {};
+      env[WDA_USE_PORT_ENV] = String(port);
+      obj.EnvironmentVariables = env;
+      injected += 1;
+    }
+    for (const value of Object.values(obj)) {
+      visit(value);
+    }
+  };
+  visit(clone);
+  if (injected === 0) {
     throw new Error(
-      `WebDriverAgent build succeeded but the runner app was not found at ${cachedRunner}. This may indicate an Xcode layout change; set PROWL_WDA_RUNNER to a prebuilt runner.`
+      "Could not find a test target in the WebDriverAgent .xctestrun to set USE_PORT. The xctestrun format may have changed; set PROWL_WDA_RUNNER to a compatible runner."
     );
   }
-  return cachedRunner;
+  return clone;
+}
+function runPlutil(args) {
+  return new Promise((resolve, reject) => {
+    execFile4(
+      "plutil",
+      args,
+      { encoding: "utf-8", maxBuffer: 32 * 1024 * 1024 },
+      (error, stdout, stderr) => {
+        if (error) {
+          reject(
+            new Error(
+              `\`plutil ${args.join(" ")}\` failed: ${(stderr || error.message).slice(0, 400)}`
+            )
+          );
+          return;
+        }
+        resolve(stdout ?? "");
+      }
+    );
+  });
+}
+var defaultWdaTestRunPreparer = async ({ xctestrunPath, port }) => {
+  const json = await runPlutil(["-convert", "json", "-o", "-", xctestrunPath]);
+  let parsed;
+  try {
+    parsed = JSON.parse(json);
+  } catch {
+    throw new Error(`Could not parse the WebDriverAgent .xctestrun as JSON: ${xctestrunPath}`);
+  }
+  const injected = injectUsePortIntoXctestrun(parsed, port);
+  const stem = `${PREPARED_XCTESTRUN_PREFIX}${port}-${process.pid}`;
+  const outPath = path6.join(path6.dirname(xctestrunPath), `${stem}.xctestrun`);
+  const jsonPath = path6.join(os4.tmpdir(), `${stem}.json`);
+  fs5.writeFileSync(jsonPath, JSON.stringify(injected));
+  try {
+    await runPlutil(["-convert", "xml1", jsonPath, "-o", outPath]);
+  } finally {
+    fs5.rmSync(jsonPath, { force: true });
+  }
+  return outPath;
+};
+function cleanupPreparedTestRun(preparedPath) {
+  if (!preparedPath) {
+    return;
+  }
+  if (!path6.basename(preparedPath).startsWith(PREPARED_XCTESTRUN_PREFIX)) {
+    return;
+  }
+  fs5.rmSync(preparedPath, { force: true });
+}
+function wdaTestRunArgs(xctestrunPath, udid) {
+  return [
+    "xcodebuild",
+    "test-without-building",
+    "-xctestrun",
+    xctestrunPath,
+    "-destination",
+    `id=${udid}`
+  ];
 }
 async function resolveBundleId(app, runner, udid, coldStart, allowedApps) {
   if (!looksLikeIosAppPath(app)) {
@@ -2518,7 +3000,7 @@ async function resolveBundleId(app, runner, udid, coldStart, allowedApps) {
     }
     return app;
   }
-  const appPath = path5.resolve(app);
+  const appPath = path6.resolve(app);
   if (!fs5.existsSync(appPath)) {
     throw new Error(`.app bundle not found: ${appPath}`);
   }
@@ -2537,6 +3019,8 @@ async function resolveBundleId(app, runner, udid, coldStart, allowedApps) {
 }
 async function launchIosSession(options) {
   const runner = options.runner ?? execFileXcrunRunner;
+  const spawner = options.spawner ?? spawnXcrunProcess;
+  const preparer = options.testRunPreparer ?? defaultWdaTestRunPreparer;
   const portAllocator = options.portAllocator ?? findFreePort;
   const connector = options.agentConnector ?? defaultIosAgentConnector;
   const requestTimeoutMs = Math.max(options.timeoutMs ?? 1e4, DEFAULT_WDA_REQUEST_TIMEOUT_MS) + 5e3;
@@ -2560,14 +3044,14 @@ async function launchIosSession(options) {
       options.coldStart ?? false,
       options.allowedApps ?? []
     );
-    const wdaRunnerApp = options.wdaRunnerApp ?? await resolveWdaRunner({ runner, logger: options.logger });
-    await installApp(runner, udid, wdaRunnerApp);
+    const baseTestRun = options.wdaTestRun ?? await resolveWdaTestRun({ runner, logger: options.logger });
     for (let attempt = 1; attempt <= WDA_STARTUP_ATTEMPTS; attempt += 1) {
       let client;
+      let wdaProcess;
+      let preparedTestRun;
       let tornDown = false;
-      let terminateWda = false;
       let terminateTarget = false;
-      let stage = "port";
+      let stage = "prepare";
       const teardownAttempt = async () => {
         if (tornDown) {
           return;
@@ -2576,18 +3060,18 @@ async function launchIosSession(options) {
         if (client) {
           await client.close().catch(() => void 0);
         }
-        if (terminateWda) {
-          await terminateApp(runner, udid, WDA_RUNNER_BUNDLE_ID);
-        }
+        wdaProcess?.kill();
+        await terminateApp(runner, udid, WDA_RUNNER_BUNDLE_ID);
         if (terminateTarget) {
           await terminateApp(runner, udid, bundleId);
         }
+        cleanupPreparedTestRun(preparedTestRun);
       };
       try {
         const port = await portAllocator();
+        preparedTestRun = await preparer({ xctestrunPath: baseTestRun, port });
         stage = "wda-launch";
-        terminateWda = true;
-        await launchApp(runner, udid, WDA_RUNNER_BUNDLE_ID, { [WDA_USE_PORT_ENV]: String(port) });
+        wdaProcess = spawner(wdaTestRunArgs(preparedTestRun, udid));
         stage = "target-launch";
         terminateTarget = true;
         await launchApp(runner, udid, bundleId);
@@ -2675,14 +3159,14 @@ async function healSelector(probe, selector, options) {
 
 // src/runner/history.ts
 import fs6 from "fs";
-import path6 from "path";
+import path7 from "path";
 var HISTORY_FILE = "history.json";
 var LOCK_FILE_SUFFIX = ".lock";
 var LOCK_RETRY_MS = 10;
 var LOCK_TIMEOUT_MS = 5e3;
 var SLEEP_BUFFER = new Int32Array(new SharedArrayBuffer(4));
 function historyPath(configDir) {
-  return path6.join(configDir, HISTORY_FILE);
+  return path7.join(configDir, HISTORY_FILE);
 }
 function isHistoryEntry(value) {
   if (!value || typeof value !== "object") {
@@ -2736,7 +3220,7 @@ function sleepSync(ms) {
 function withHistoryLock(configDir, fn) {
   const filePath = historyPath(configDir);
   const lockPath = `${filePath}${LOCK_FILE_SUFFIX}`;
-  fs6.mkdirSync(path6.dirname(filePath), { recursive: true });
+  fs6.mkdirSync(path7.dirname(filePath), { recursive: true });
   const startedAt = Date.now();
   while (Date.now() - startedAt < LOCK_TIMEOUT_MS) {
     let fd;
@@ -2777,11 +3261,11 @@ function appendEntry(configDir, entry, maxRuns) {
 
 // src/runner/index.ts
 import fs12 from "fs";
-import path12 from "path";
+import path13 from "path";
 
 // src/browser/playwright-driver.ts
 import fs7 from "fs";
-import path7 from "path";
+import path8 from "path";
 import {
   chromium,
   firefox,
@@ -2814,7 +3298,7 @@ async function launchBrowser(options) {
       }
     }
     if (options.recordHar) {
-      contextOptions.recordHar = { path: path7.join(options.runDir, "network.har") };
+      contextOptions.recordHar = { path: path8.join(options.runDir, "network.har") };
     }
     const context = await browser.newContext(contextOptions);
     const page = await context.newPage();
@@ -2822,7 +3306,7 @@ async function launchBrowser(options) {
     page.setDefaultNavigationTimeout(options.timeout);
     let tracePath;
     if (options.trace) {
-      tracePath = path7.join(options.runDir, "trace.zip");
+      tracePath = path8.join(options.runDir, "trace.zip");
       await context.tracing.start({ screenshots: true, snapshots: true, sources: true });
     }
     return { browser, context, page, tracePath };
@@ -3001,7 +3485,7 @@ function createPlaywrightDriver(page) {
 
 // src/runner/steps.ts
 import fs8 from "fs";
-import path8 from "path";
+import path9 from "path";
 
 // src/runner/policy.ts
 var ALWAYS_ALLOWED_PROTOCOLS = ["about:", "data:"];
@@ -3100,6 +3584,246 @@ function createRunPolicy(driver, options) {
   };
 }
 
+// src/generator/ai.ts
+var DEFAULT_BASE_URL = {
+  anthropic: "https://api.anthropic.com",
+  openai: "https://api.openai.com"
+};
+var AI_REQUEST_TIMEOUT_MS = 3e4;
+function apiRoot(config) {
+  return config.baseUrl ?? DEFAULT_BASE_URL[config.provider];
+}
+function defaultModelFor(provider) {
+  return provider === "anthropic" ? "claude-sonnet-4-5-20250929" : "gpt-4o";
+}
+function resolveAiEnv() {
+  const provider = process.env.PROWL_AI_PROVIDER ?? "anthropic";
+  if (provider !== "anthropic" && provider !== "openai") {
+    throw new Error(`Unsupported AI provider: ${provider}. Use "anthropic" or "openai".`);
+  }
+  const model = process.env.PROWL_AI_MODEL ?? defaultModelFor(provider);
+  const baseUrl = normalizeBaseUrl(process.env.PROWL_AI_BASE_URL) ?? DEFAULT_BASE_URL[provider];
+  return { provider, model, baseUrl, apiKey: process.env.PROWL_AI_KEY };
+}
+function normalizeBaseUrl(value) {
+  if (value === void 0) return void 0;
+  const trimmed = value.trim().replace(/\/+$/, "");
+  return trimmed.length > 0 ? trimmed : void 0;
+}
+function resolveAiConfig() {
+  const env = resolveAiEnv();
+  if (!env.apiKey) {
+    throw new Error(
+      "PROWL_AI_KEY environment variable is required. Set it to your Anthropic or OpenAI API key."
+    );
+  }
+  return { provider: env.provider, model: env.model, apiKey: env.apiKey, baseUrl: env.baseUrl };
+}
+function tryResolveAiConfig() {
+  const env = resolveAiEnv();
+  if (!env.apiKey) {
+    return null;
+  }
+  return { provider: env.provider, model: env.model, apiKey: env.apiKey, baseUrl: env.baseUrl };
+}
+async function generateWithAi(prompt, config) {
+  if (config.provider === "anthropic") {
+    return generateWithAnthropic(prompt, config);
+  }
+  return generateWithOpenAi(prompt, config);
+}
+async function generateWithAnthropic(prompt, config) {
+  const data = await postJson(
+    "Anthropic",
+    `${apiRoot(config)}/v1/messages`,
+    anthropicHeaders(config),
+    {
+      model: config.model,
+      max_tokens: 4096,
+      messages: [
+        { role: "user", content: prompt }
+      ]
+    }
+  );
+  return extractAnthropicText(data);
+}
+async function generateWithOpenAi(prompt, config) {
+  const data = await postJson(
+    "OpenAI",
+    `${apiRoot(config)}/v1/chat/completions`,
+    openAiHeaders(config),
+    {
+      model: config.model,
+      messages: [
+        { role: "user", content: prompt }
+      ],
+      max_tokens: 4096
+    }
+  );
+  return extractOpenAiText(data);
+}
+function buildVisionPrompt(assertion) {
+  return [
+    "You are a meticulous QA reviewer. You are given a screenshot of an application",
+    "and a single assertion describing what should be true about it.",
+    "",
+    "Assertion:",
+    assertion,
+    "",
+    "Decide whether the assertion holds for the screenshot. Judge ONLY what is",
+    "visible; do not assume behavior you cannot see. Be strict: if the assertion",
+    "is not clearly satisfied, it fails.",
+    "",
+    "Reply with ONLY a single JSON object on one line, no markdown, no code fences:",
+    '{"pass": <true|false>, "reason": "<one concise sentence explaining the verdict>"}'
+  ].join("\n");
+}
+function parseVisionVerdict(raw) {
+  const cleaned = stripCodeFences(raw).trim();
+  const candidate = extractJsonObject(cleaned);
+  if (candidate === null) {
+    throw new Error(
+      `Could not parse a JSON verdict from the AI response: ${truncateForError(raw)}`
+    );
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(candidate);
+  } catch {
+    throw new Error(
+      `AI verdict was not valid JSON: ${truncateForError(raw)}`
+    );
+  }
+  if (typeof parsed !== "object" || parsed === null) {
+    throw new Error(`AI verdict was not a JSON object: ${truncateForError(raw)}`);
+  }
+  const record = parsed;
+  if (typeof record.pass !== "boolean") {
+    throw new Error(
+      `AI verdict is missing a boolean "pass" field: ${truncateForError(raw)}`
+    );
+  }
+  const reason = typeof record.reason === "string" && record.reason.trim().length > 0 ? record.reason.trim() : record.pass ? "Assertion satisfied." : "Assertion not satisfied.";
+  return { pass: record.pass, reason };
+}
+function stripCodeFences(text) {
+  const fence = text.match(/```(?:json)?\s*([\s\S]*?)```/i);
+  return fence ? fence[1] : text;
+}
+function extractJsonObject(text) {
+  const trimmed = text.trim();
+  if (trimmed.startsWith("{") && trimmed.endsWith("}")) {
+    return trimmed;
+  }
+  const first = trimmed.indexOf("{");
+  const last = trimmed.lastIndexOf("}");
+  if (first === -1 || last === -1 || last <= first) {
+    return null;
+  }
+  return trimmed.slice(first, last + 1);
+}
+function truncateForError(text) {
+  const collapsed = text.replace(/\s+/g, " ").trim();
+  return collapsed.length > 200 ? `${collapsed.slice(0, 199)}\u2026` : collapsed;
+}
+async function assertWithAiVision(input, config) {
+  const raw = config.provider === "anthropic" ? await visionWithAnthropic(input, config) : await visionWithOpenAi(input, config);
+  return parseVisionVerdict(raw);
+}
+async function visionWithAnthropic(input, config) {
+  const data = await postJson(
+    "Anthropic",
+    `${apiRoot(config)}/v1/messages`,
+    anthropicHeaders(config),
+    {
+      model: config.model,
+      max_tokens: 1024,
+      temperature: 0,
+      messages: [
+        {
+          role: "user",
+          content: [
+            {
+              type: "image",
+              source: {
+                type: "base64",
+                media_type: input.mediaType,
+                data: input.imageBase64
+              }
+            },
+            { type: "text", text: buildVisionPrompt(input.assertion) }
+          ]
+        }
+      ]
+    }
+  );
+  return extractAnthropicText(data);
+}
+async function visionWithOpenAi(input, config) {
+  const data = await postJson(
+    "OpenAI",
+    `${apiRoot(config)}/v1/chat/completions`,
+    openAiHeaders(config),
+    {
+      model: config.model,
+      max_tokens: 1024,
+      temperature: 0,
+      messages: [
+        {
+          role: "user",
+          content: [
+            { type: "text", text: buildVisionPrompt(input.assertion) },
+            {
+              type: "image_url",
+              image_url: { url: `data:${input.mediaType};base64,${input.imageBase64}` }
+            }
+          ]
+        }
+      ]
+    }
+  );
+  return extractOpenAiText(data);
+}
+async function postJson(provider, url, headers, body) {
+  const response = await fetch(url, {
+    method: "POST",
+    headers,
+    body: JSON.stringify(body),
+    signal: AbortSignal.timeout(AI_REQUEST_TIMEOUT_MS)
+  });
+  if (!response.ok) {
+    const responseBody = await response.text();
+    throw new Error(`${provider} API error (${response.status}): ${responseBody}`);
+  }
+  return await response.json();
+}
+function anthropicHeaders(config) {
+  return {
+    "Content-Type": "application/json",
+    "x-api-key": config.apiKey,
+    "anthropic-version": "2023-06-01"
+  };
+}
+function openAiHeaders(config) {
+  return {
+    "Content-Type": "application/json",
+    "Authorization": `Bearer ${config.apiKey}`
+  };
+}
+function extractAnthropicText(data) {
+  const textBlock = data.content?.find((c) => c.type === "text");
+  if (!textBlock?.text) {
+    throw new Error("Anthropic API returned no text content");
+  }
+  return textBlock.text;
+}
+function extractOpenAiText(data) {
+  if (!data.choices?.[0]?.message?.content) {
+    throw new Error("OpenAI API returned no content");
+  }
+  return data.choices[0].message.content;
+}
+
 // src/runner/steps.ts
 function getStepType(step) {
   if ("navigate" in step) return "navigate";
@@ -3128,6 +3852,7 @@ function getStepType(step) {
   if ("evalScript" in step) return "evalScript";
   if ("runScript" in step) return "runScript";
   if ("assertScreenshot" in step) return "assertScreenshot";
+  if ("assertWithAI" in step) return "assertWithAI";
   if ("copyText" in step) return "copyText";
   if ("waitForDownload" in step) return "waitForDownload";
   return "step";
@@ -3187,6 +3912,9 @@ function applyRuntimeVars(step, vars) {
       }
     };
   }
+  if ("assertWithAI" in step) {
+    return { assertWithAI: sub(step.assertWithAI) };
+  }
   if ("copyText" in step) {
     return { copyText: { selector: sub(step.copyText.selector), as: step.copyText.as } };
   }
@@ -3437,7 +4165,7 @@ async function runInlineAssert(driver, policy, assertion) {
   throw new Error("assert step is missing an assertion type");
 }
 function screenshotPath(screenshotsDir, fileName) {
-  return path8.join(screenshotsDir, fileName);
+  return path9.join(screenshotsDir, fileName);
 }
 function stepPath(prefix, index) {
   return prefix ? `${prefix}.${index}` : `${index}`;
@@ -3454,7 +4182,7 @@ function validateDownloadFilename(suggestedFilename) {
   const safeFilename = suggestedFilename.trim();
   const allowedFilenamePattern = /^[^<>:"/\\|?*]+$/;
   const hasControlCharacter = Array.from(safeFilename).some((char) => char.charCodeAt(0) < 32);
-  if (safeFilename.length === 0 || safeFilename !== suggestedFilename || safeFilename !== path8.basename(safeFilename) || safeFilename.includes("..") || /[/\\]/.test(safeFilename) || hasControlCharacter || !allowedFilenamePattern.test(safeFilename)) {
+  if (safeFilename.length === 0 || safeFilename !== suggestedFilename || safeFilename !== path9.basename(safeFilename) || safeFilename.includes("..") || /[/\\]/.test(safeFilename) || hasControlCharacter || !allowedFilenamePattern.test(safeFilename)) {
     throw new Error(`Invalid download filename: "${suggestedFilename}"`);
   }
   return safeFilename;
@@ -3634,7 +4362,7 @@ var STEP_HANDLERS = {
       if (!("setInputFiles" in h.step)) unknownStep();
       const resolvedInput = await h.policy.resolveActionSelector(h.step.setInputFiles.selector);
       const rawFiles = h.step.setInputFiles.files;
-      const resolveFile = (f) => path8.isAbsolute(f) ? f : path8.join(h.context.configDir, f);
+      const resolveFile = (f) => path9.isAbsolute(f) ? f : path9.join(h.context.configDir, f);
       const resolvedFiles = Array.isArray(rawFiles) ? rawFiles.map(resolveFile) : resolveFile(rawFiles);
       await h.driver.setInputFiles(resolvedInput.selector, resolvedFiles);
       h.policy.ensureLocationAllowed(h.driver);
@@ -3996,11 +4724,11 @@ var STEP_HANDLERS = {
         if (!responseFile) {
           throw new Error("mock.response must include either body or file");
         }
-        const candidateFilePath = path8.isAbsolute(responseFile) ? responseFile : path8.join(h.context.configDir, responseFile);
-        const resolvedConfigDir = path8.resolve(h.context.configDir);
-        const resolvedFilePath = path8.resolve(candidateFilePath);
-        const relativePath = path8.relative(resolvedConfigDir, resolvedFilePath);
-        const isWithinConfigDir = relativePath === "" || relativePath !== ".." && !relativePath.startsWith(`..${path8.sep}`) && !path8.isAbsolute(relativePath);
+        const candidateFilePath = path9.isAbsolute(responseFile) ? responseFile : path9.join(h.context.configDir, responseFile);
+        const resolvedConfigDir = path9.resolve(h.context.configDir);
+        const resolvedFilePath = path9.resolve(candidateFilePath);
+        const relativePath = path9.relative(resolvedConfigDir, resolvedFilePath);
+        const isWithinConfigDir = relativePath === "" || relativePath !== ".." && !relativePath.startsWith(`..${path9.sep}`) && !path9.isAbsolute(relativePath);
         if (!isWithinConfigDir) {
           throw new Error("mock.response.file must resolve within config directory");
         }
@@ -4067,7 +4795,7 @@ var STEP_HANDLERS = {
     capabilities: ["evaluate"],
     run: async (h) => {
       if (!("runScript" in h.step)) unknownStep();
-      const filePath = path8.isAbsolute(h.step.runScript.file) ? h.step.runScript.file : path8.join(h.context.configDir, h.step.runScript.file);
+      const filePath = path9.isAbsolute(h.step.runScript.file) ? h.step.runScript.file : path9.join(h.context.configDir, h.step.runScript.file);
       const fileContents = fs8.readFileSync(filePath, "utf-8");
       await h.driver.evaluate(fileContents);
       return {
@@ -4089,11 +4817,11 @@ var STEP_HANDLERS = {
       const name = h.step.assertScreenshot.name;
       const threshold = h.step.assertScreenshot.threshold ?? 0.1;
       const baselineDir = ensureBaselineDir(h.context.configDir);
-      const baselinePath = path8.join(baselineDir, `${name}.png`);
-      const currentScreenshotPath = path8.join(h.context.runDir, "screenshots", `${name}-current.png`);
-      fs8.mkdirSync(path8.dirname(currentScreenshotPath), { recursive: true });
+      const baselinePath = path9.join(baselineDir, `${name}.png`);
+      const currentScreenshotPath = path9.join(h.context.runDir, "screenshots", `${name}-current.png`);
+      fs8.mkdirSync(path9.dirname(currentScreenshotPath), { recursive: true });
       await h.driver.screenshot({ path: currentScreenshotPath, fullPage: true });
-      h.screenshots.push(path8.join("screenshots", `${name}-current.png`));
+      h.screenshots.push(path9.join("screenshots", `${name}-current.png`));
       if (!fs8.existsSync(baselinePath)) {
         fs8.copyFileSync(currentScreenshotPath, baselinePath);
         return {
@@ -4101,7 +4829,7 @@ var STEP_HANDLERS = {
           result: { type: "assertScreenshot", status: "pass", durationMs: Date.now() - h.stepStart, value: "baseline created" }
         };
       }
-      const diffPath = path8.join(h.context.runDir, "screenshots", `${name}-diff.png`);
+      const diffPath = path9.join(h.context.runDir, "screenshots", `${name}-diff.png`);
       const comparison = await compareScreenshots(baselinePath, currentScreenshotPath, diffPath, threshold);
       if (comparison.match) {
         return {
@@ -4114,12 +4842,54 @@ var STEP_HANDLERS = {
           }
         };
       }
-      h.screenshots.push(path8.join("screenshots", `${name}-diff.png`));
+      h.screenshots.push(path9.join("screenshots", `${name}-diff.png`));
       throw new Error(
         `Visual regression: ${(comparison.diffPercentage * 100).toFixed(2)}% diff exceeds threshold ${(threshold * 100).toFixed(0)}%`
       );
     }
   },
+  assertWithAI: {
+    capabilities: ["screenshot"],
+    run: async (h) => {
+      if (!("assertWithAI" in h.step)) unknownStep();
+      const assertion = h.step.assertWithAI;
+      const resolve = h.context.resolveAiConfig ?? tryResolveAiConfig;
+      const aiConfig = resolve();
+      if (!aiConfig) {
+        return {
+          kind: "result",
+          result: {
+            type: "assertWithAI",
+            status: "warn",
+            durationMs: Date.now() - h.stepStart,
+            value: `skipped: no AI provider configured (set PROWL_AI_KEY to enable) \u2014 "${assertion}"`
+          }
+        };
+      }
+      const fileName = `assertWithAI_step_${h.index + 1}.png`;
+      const relative = await h.addScreenshot(fileName);
+      const screenshotFullPath = path9.join(h.context.runDir, relative);
+      const imageBase64 = fs8.readFileSync(screenshotFullPath).toString("base64");
+      const assertVision = h.context.assertVision ?? assertWithAiVision;
+      const verdict = await assertVision(
+        { imageBase64, mediaType: "image/png", assertion },
+        aiConfig
+      );
+      if (verdict.pass) {
+        return {
+          kind: "result",
+          result: {
+            type: "assertWithAI",
+            status: "pass",
+            durationMs: Date.now() - h.stepStart,
+            value: verdict.reason,
+            screenshot: relative
+          }
+        };
+      }
+      throw new Error(`AI assertion failed: ${verdict.reason}`);
+    }
+  },
   copyText: {
     capabilities: ["query"],
     run: async (h) => {
@@ -4156,7 +4926,7 @@ var STEP_HANDLERS = {
           `Download filename mismatch: expected "${opts.filename}", got "${suggestedFilename}"`
         );
       }
-      const savePath = path8.join(h.context.runDir, suggestedFilename);
+      const savePath = path9.join(h.context.runDir, suggestedFilename);
       await download.saveAs(savePath);
       return {
         kind: "result",
@@ -4185,7 +4955,7 @@ async function executeSteps(context) {
     maxSteps: context.maxSteps,
     selfHealing: context.selfHealing
   });
-  const screenshotsDir = path8.join(context.runDir, "screenshots");
+  const screenshotsDir = path9.join(context.runDir, "screenshots");
   fs8.mkdirSync(screenshotsDir, { recursive: true });
   const currentHuntName = context.huntStack?.[context.huntStack.length - 1];
   policy.assertWithinMaxSteps(context.steps.length, currentHuntName);
@@ -4196,7 +4966,7 @@ async function executeSteps(context) {
   const addScreenshot = async (fileName) => {
     const fullPath = screenshotPath(screenshotsDir, fileName);
     await captureScreenshot2(driver, fullPath);
-    const relative = path8.join("screenshots", fileName);
+    const relative = path9.join("screenshots", fileName);
     screenshots.push(relative);
     return relative;
   };
@@ -4284,12 +5054,12 @@ async function executeSteps(context) {
   return { results, screenshots, failed: false };
 }
 async function captureFinalScreenshot(page, runDir) {
-  const screenshotsDir = path8.join(runDir, "screenshots");
+  const screenshotsDir = path9.join(runDir, "screenshots");
   fs8.mkdirSync(screenshotsDir, { recursive: true });
   const fileName = "final.png";
   const filePath = screenshotPath(screenshotsDir, fileName);
   await captureScreenshot2(page, filePath);
-  return path8.join("screenshots", fileName);
+  return path9.join("screenshots", fileName);
 }
 
 // src/runner/assertions.ts
@@ -4411,6 +5181,59 @@ async function evaluateAssertions(options) {
   }
   return results;
 }
+async function evaluateNativeAssertions(options) {
+  const assertions = mergeAssertions(options.config, options.huntAssertions);
+  const authoredTypes = new Set(
+    (options.huntAssertions ?? []).map((assertion) => Object.keys(assertion)[0])
+  );
+  const results = [];
+  const warnings = [];
+  for (const assertion of assertions) {
+    const type = Object.keys(assertion)[0] ?? "assertion";
+    try {
+      if ("selectorExists" in assertion) {
+        options.assertAllowedSelector?.(assertion.selectorExists);
+        const count = await options.driver.count(assertion.selectorExists);
+        results.push({
+          type: "selectorExists",
+          value: assertion.selectorExists,
+          status: count > 0 ? "pass" : "fail",
+          error: count > 0 ? void 0 : "Selector not found"
+        });
+        continue;
+      }
+      if ("selectorNotExists" in assertion) {
+        options.assertAllowedSelector?.(assertion.selectorNotExists);
+        const count = await options.driver.count(assertion.selectorNotExists);
+        results.push({
+          type: "selectorNotExists",
+          value: assertion.selectorNotExists,
+          status: count === 0 ? "pass" : "fail",
+          error: count === 0 ? void 0 : "Selector exists"
+        });
+        continue;
+      }
+      const rawValue = assertion[type];
+      results.push({
+        type,
+        value: rawValue,
+        status: "skipped",
+        error: `skipped (web-only): not supported on the ${options.targetLabel} target`
+      });
+      if (authoredTypes.has(type)) {
+        warnings.push(`${type} is web-only; skipped on ${options.targetLabel} target`);
+      }
+    } catch (error) {
+      const detail = error instanceof Error ? error.message : "no error details";
+      results.push({
+        type,
+        status: "fail",
+        error: `Native assertion "${type}" failed: ${detail}`
+      });
+    }
+  }
+  return { results, warnings };
+}
 
 // src/runner/tracing.ts
 var DEFAULT_TRACE_HEADER = "traceparent";
@@ -4450,17 +5273,17 @@ function captureTraceCorrelation(response, headerName, sink, redactionValues = [
 
 // src/reporter/result.ts
 import fs9 from "fs";
-import path9 from "path";
+import path10 from "path";
 function writeResult(runDir, result) {
   const fileName = "result.json";
-  const fullPath = path9.join(runDir, fileName);
+  const fullPath = path10.join(runDir, fileName);
   fs9.writeFileSync(fullPath, JSON.stringify(result, null, 2));
   return fileName;
 }
 
 // src/reporter/summary.ts
 import fs10 from "fs";
-import path10 from "path";
+import path11 from "path";
 function escapeMd(text) {
   return text.replace(/([|`*_{}[\]()#+\-!\\])/g, "\\$1");
 }
@@ -4538,7 +5361,7 @@ function writeSummary(runDir, result) {
     }
   }
   const fileName = "summary.md";
-  const fullPath = path10.join(runDir, fileName);
+  const fullPath = path11.join(runDir, fileName);
   fs10.writeFileSync(fullPath, `${lines.join("\n")}
 `);
   return fileName;
@@ -4546,20 +5369,21 @@ function writeSummary(runDir, result) {
 
 // src/reporter/junit.ts
 import fs11 from "fs";
-import path11 from "path";
+import path12 from "path";
 function escapeXml(text) {
   return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
 }
 function writeJunit(runDir, result) {
   const totalTests = result.steps.length + result.assertions.length;
   const failures = result.steps.filter((s) => s.status === "fail").length + result.assertions.filter((a) => a.status === "fail").length;
+  const skipped = result.assertions.filter((a) => a.status === "skipped").length;
   const timeSeconds = (result.durationMs / 1e3).toFixed(3);
   const huntName = escapeXml(result.hunt);
   const lines = [];
   lines.push('<?xml version="1.0" encoding="UTF-8"?>');
   lines.push("<testsuites>");
   lines.push(
-    `  <testsuite name="${huntName}" tests="${totalTests}" failures="${failures}" errors="0" time="${timeSeconds}" timestamp="${escapeXml(result.startedAt)}">`
+    `  <testsuite name="${huntName}" tests="${totalTests}" failures="${failures}" errors="0" skipped="${skipped}" time="${timeSeconds}" timestamp="${escapeXml(result.startedAt)}">`
   );
   for (let i = 0; i < result.steps.length; i++) {
     const step = result.steps[i];
@@ -4583,6 +5407,11 @@ function writeJunit(runDir, result) {
       lines.push(`    <testcase name="${caseName}" classname="${huntName}" time="0">`);
       lines.push(`      <failure message="${escapedFailureText}" type="assertion">${escapedFailureText}</failure>`);
       lines.push("    </testcase>");
+    } else if (assertion.status === "skipped") {
+      const skipText = escapeXml(assertion.error ?? "skipped");
+      lines.push(`    <testcase name="${caseName}" classname="${huntName}" time="0">`);
+      lines.push(`      <skipped message="${skipText}"/>`);
+      lines.push("    </testcase>");
     } else {
       lines.push(`    <testcase name="${caseName}" classname="${huntName}" time="0"/>`);
     }
@@ -4590,7 +5419,7 @@ function writeJunit(runDir, result) {
   lines.push("  </testsuite>");
   lines.push("</testsuites>");
   const fileName = "junit.xml";
-  const fullPath = path11.join(runDir, fileName);
+  const fullPath = path12.join(runDir, fileName);
   fs11.writeFileSync(fullPath, `${lines.join("\n")}
 `);
   return fileName;
@@ -4633,11 +5462,11 @@ function parseViewportFlag(value) {
   return value;
 }
 function resolvePath(configDir, inputPath) {
-  if (path12.isAbsolute(inputPath)) {
+  if (path13.isAbsolute(inputPath)) {
     return inputPath;
   }
-  const projectRoot = path12.dirname(configDir);
-  return path12.join(projectRoot, inputPath);
+  const projectRoot = path13.dirname(configDir);
+  return path13.join(projectRoot, inputPath);
 }
 function buildRunResult(options) {
   return {
@@ -4656,7 +5485,7 @@ function buildRunResult(options) {
 }
 function writeConsoleLog(runDir, entries) {
   const fileName = "console.log";
-  const filePath = path12.join(runDir, fileName);
+  const filePath = path13.join(runDir, fileName);
   const lines = entries.map((entry) => {
     const location = entry.location ? ` (${entry.location})` : "";
     return `[${entry.type}] ${entry.text}${location}`;
@@ -4669,7 +5498,7 @@ async function executeHuntAttempt(options, config, configDir, interpolatedHunt,
   const headless = options.headed ? false : config.browser.headless;
   const slowMo = options.slowMo ?? config.browser.slowMo;
   const maxSteps = config.guardrails.maxSteps;
-  const runDir = path12.join(configDir, "runs", timestamp());
+  const runDir = path13.join(configDir, "runs", timestamp());
   fs12.mkdirSync(runDir, { recursive: true });
   const storageStatePath = config.auth.storageStatePath ? resolvePath(configDir, config.auth.storageStatePath) : void 0;
   const engine = options.browser ?? config.browser.engine;
@@ -4853,7 +5682,7 @@ async function runHunt(options) {
 }
 async function executeNativeHuntAttempt(options, config, configDir, interpolatedHunt, redactedFillSteps, randomVars, allowedApps, native) {
   const maxSteps = config.guardrails.maxSteps;
-  const runDir = path12.join(configDir, "runs", timestamp());
+  const runDir = path13.join(configDir, "runs", timestamp());
   fs12.mkdirSync(runDir, { recursive: true });
   const session = await native.launchSession();
   let result;
@@ -4862,6 +5691,13 @@ async function executeNativeHuntAttempt(options, config, configDir, interpolated
     const appIdentity = native.sessionAppIdentity(session);
     const targetLabel = `${native.targetType}:${appIdentity}`;
     const effectiveAllowedApps = [.../* @__PURE__ */ new Set([...allowedApps, native.targetApp, appIdentity])];
+    const assertionPolicy = createRunPolicy(driver, {
+      forbiddenSelectors: config.guardrails.forbiddenSelectors,
+      allowedDomains: [],
+      allowedApps: effectiveAllowedApps,
+      maxSteps,
+      selfHealing: config.guardrails.selfHealing
+    });
     const startedAt = (/* @__PURE__ */ new Date()).toISOString();
     const startTime = Date.now();
     let stepResults = [];
@@ -4901,8 +5737,19 @@ async function executeNativeHuntAttempt(options, config, configDir, interpolated
     } catch {
       finalScreenshot = void 0;
     }
+    const { results: assertionResults, warnings: assertionWarnings } = await evaluateNativeAssertions({
+      driver,
+      config,
+      huntAssertions: interpolatedHunt.assertions,
+      assertAllowedSelector: assertionPolicy.assertAllowedSelector,
+      targetLabel: nativeTargetLabel(native.targetType)
+    });
+    for (const warning of assertionWarnings) {
+      console.warn(warning);
+    }
     const durationMs = Date.now() - startTime;
-    const status = stepFailed ? "fail" : "pass";
+    const assertionsFailed = assertionResults.some((assertion) => assertion.status === "fail");
+    const status = stepFailed || assertionsFailed ? "fail" : "pass";
     const artifacts = {
       screenshots: finalScreenshot ? [...stepScreenshots, finalScreenshot] : stepScreenshots
     };
@@ -4913,7 +5760,7 @@ async function executeNativeHuntAttempt(options, config, configDir, interpolated
       hunt: options.huntName,
       targetUrl: targetLabel,
       steps: stepResults,
-      assertions: [],
+      assertions: assertionResults,
       artifacts
     });
     result = writeReports(runDir, runResult, { junit: options.junit ?? config.artifacts.junit });
@@ -5026,7 +5873,6 @@ async function runNativeHunt(options, config, configDir, target, native) {
   const hunt = loadHunt(options.huntName, configDir);
   const { hunt: interpolatedHunt, redactedFillSteps, randomVars } = interpolateHunt(hunt, process.env);
   assertStepsSupportedByTarget(interpolatedHunt.steps, native.targetType);
-  assertHuntAssertionsSupportedByTarget(interpolatedHunt.assertions, native.targetType);
   native.assertAppAllowed(config.guardrails.allowedApps, target);
   const maxSteps = config.guardrails.maxSteps;
   if (interpolatedHunt.steps.length > maxSteps) {
@@ -5067,7 +5913,7 @@ async function runNativeHunt(options, config, configDir, target, native) {
 }
 function recordHistory(configDir, outcome, maxRuns) {
   try {
-    const relativeRunDir = path12.relative(configDir, outcome.runDir);
+    const relativeRunDir = path13.relative(configDir, outcome.runDir);
     appendEntry(
       configDir,
       {
@@ -5189,7 +6035,7 @@ function clusterFailures(failures) {
 
 // src/backlog/index.ts
 import fs13 from "fs";
-import path13 from "path";
+import path14 from "path";
 
 // src/backlog/parse.ts
 var MARKER_FP = /<!--\s*prowl:fp=([0-9a-f]+)/;
@@ -5295,7 +6141,7 @@ function buildFailure(hunt) {
   if (!hunt.runDir) return failure;
   let run;
   try {
-    const resultJson = readFileOrEmpty(path13.join(hunt.runDir, "result.json"));
+    const resultJson = readFileOrEmpty(path14.join(hunt.runDir, "result.json"));
     if (!resultJson) return failure;
     run = JSON.parse(resultJson);
   } catch (error) {
@@ -5324,8 +6170,8 @@ function extractFailures(suiteResult) {
 }
 function updateBacklogFromSuite(suiteResult, options = {}) {
   const projectRoot = options.projectRoot ?? process.cwd();
-  const backlogPath = options.backlogPath ?? path13.join(projectRoot, "docs", "backlog.md");
-  const resolvedPath = options.resolvedPath ?? path13.join(projectRoot, "docs", "resolved.md");
+  const backlogPath = options.backlogPath ?? path14.join(projectRoot, "docs", "backlog.md");
+  const resolvedPath = options.resolvedPath ?? path14.join(projectRoot, "docs", "resolved.md");
   const date = options.date ?? (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
   const summary = { created: [], regressions: [], skipped: [], backlogPath };
   const failures = extractFailures(suiteResult);
@@ -5357,18 +6203,18 @@ function updateBacklogFromSuite(suiteResult, options = {}) {
     }
   }
   if (ticketsToAdd.length > 0) {
-    fs13.mkdirSync(path13.dirname(backlogPath), { recursive: true });
+    fs13.mkdirSync(path14.dirname(backlogPath), { recursive: true });
     fs13.writeFileSync(backlogPath, insertTickets(backlogContent, ticketsToAdd));
   }
   return summary;
 }
 
 // src/runner/suite.ts
-import path15 from "path";
+import path16 from "path";
 
 // src/reporter/ci-summary.ts
 import fs14 from "fs";
-import path14 from "path";
+import path15 from "path";
 import chalk from "chalk";
 function countCiResults(results) {
   return {
@@ -5433,7 +6279,7 @@ function writeCiResult(ciRunDir, results, startedAt, totalDurationMs, flaky = []
     ...clusters.length > 0 ? { clusters } : {}
   };
   fs14.mkdirSync(ciRunDir, { recursive: true });
-  const filePath = path14.join(ciRunDir, "ci-result.json");
+  const filePath = path15.join(ciRunDir, "ci-result.json");
   fs14.writeFileSync(filePath, JSON.stringify(ciResult, null, 2) + "\n");
   return filePath;
 }
@@ -5619,7 +6465,7 @@ async function runSuite(options = {}) {
   const clusters = clusterFailures(
     extractFailures({ result: { hunts: results }, resultPath: null })
   ).filter((cluster) => cluster.count > 1);
-  const ciRunDir = path15.join(configDir, "runs", timestamp("ci"));
+  const ciRunDir = path16.join(configDir, "runs", timestamp("ci"));
   const resultPath = writeCiResult(ciRunDir, results, startedAt, totalDurationMs, flaky, clusters);
   const { passed, failed, skipped } = countCiResults(results);
   return {
@@ -5882,6 +6728,273 @@ async function readStatusMenu(client, menuTimeoutSeconds) {
   }
 }
 
+// src/analyzer/android.ts
+var ANDROID_INTERACTIVE_CLASSES = /* @__PURE__ */ new Set([
+  "android.widget.Button",
+  "android.widget.ImageButton",
+  "android.widget.EditText",
+  "android.widget.CheckBox",
+  "android.widget.RadioButton",
+  "android.widget.Switch",
+  "android.widget.ToggleButton",
+  "android.widget.Spinner",
+  "android.widget.SeekBar",
+  "android.widget.RatingBar",
+  "android.widget.CompoundButton",
+  "android.widget.AutoCompleteTextView",
+  "android.widget.MultiAutoCompleteTextView",
+  "android.widget.CheckedTextView",
+  "androidx.appcompat.widget.SwitchCompat",
+  "androidx.appcompat.widget.AppCompatButton",
+  "androidx.appcompat.widget.AppCompatEditText"
+]);
+function str2(value) {
+  if (value === void 0) {
+    return void 0;
+  }
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : void 0;
+}
+function bool(value) {
+  if (value === void 0) {
+    return void 0;
+  }
+  return value === "true";
+}
+function toAndroidNode(element) {
+  const a = element.attrs;
+  return {
+    className: str2(a["class"]),
+    resourceId: str2(a["resource-id"]),
+    contentDesc: str2(a["content-desc"]),
+    text: str2(a.text),
+    package: str2(a.package),
+    clickable: bool(a.clickable),
+    longClickable: bool(a["long-clickable"]),
+    checkable: bool(a.checkable),
+    checked: bool(a.checked),
+    scrollable: bool(a.scrollable),
+    focusable: bool(a.focusable),
+    focused: bool(a.focused),
+    enabled: bool(a.enabled),
+    children: element.children.map(toAndroidNode)
+  };
+}
+function parseAndroidHierarchy(xml) {
+  const root = parseXml(xml);
+  return root ? toAndroidNode(root) : null;
+}
+function isAndroidInteractive(node) {
+  if (node.clickable || node.longClickable || node.checkable || node.scrollable) {
+    return true;
+  }
+  return node.className !== void 0 && ANDROID_INTERACTIVE_CLASSES.has(node.className);
+}
+function rankAndroidSelectors(node) {
+  return rankNativeSelectors({
+    id: node.resourceId,
+    label: node.contentDesc,
+    role: node.className,
+    name: node.text
+  });
+}
+function androidNodeToNative(node) {
+  return {
+    ...node.resourceId !== void 0 ? { id: node.resourceId } : {},
+    ...node.contentDesc !== void 0 ? { label: node.contentDesc } : {},
+    ...node.className !== void 0 ? { role: node.className } : {},
+    textValues: node.text !== void 0 ? [node.text] : [],
+    ...node.focused !== void 0 ? { focused: node.focused } : {}
+  };
+}
+function matchAndroidSelector(xml, selector, options = {}) {
+  const parsedSelector = parseNativeSelector(selector);
+  const root = parseAndroidHierarchy(xml);
+  if (!root) {
+    return [];
+  }
+  return matchNativeTree(
+    ANDROID_MATCH_DIALECT,
+    parsedSelector,
+    root,
+    androidNodeToNative,
+    (node) => node.children,
+    options
+  );
+}
+function toElement2(node) {
+  return {
+    className: node.className ?? "?",
+    ...node.resourceId ? { resourceId: node.resourceId } : {},
+    ...node.contentDesc ? { contentDesc: node.contentDesc } : {},
+    ...node.text ? { text: node.text } : {},
+    ...node.clickable !== void 0 ? { clickable: node.clickable } : {},
+    ...node.checkable !== void 0 ? { checkable: node.checkable } : {},
+    ...node.scrollable !== void 0 ? { scrollable: node.scrollable } : {},
+    ...node.enabled !== void 0 ? { enabled: node.enabled } : {},
+    selectors: rankAndroidSelectors(node)
+  };
+}
+function collectInteractive2(root) {
+  const out = [];
+  const visit = (node) => {
+    if (isAndroidInteractive(node)) {
+      out.push(toElement2(node));
+    }
+    for (const child of node.children) {
+      visit(child);
+    }
+  };
+  visit(root);
+  return out;
+}
+async function analyzeAndroidApp(client, options) {
+  const xml = await client.source();
+  const root = parseAndroidHierarchy(xml);
+  const elements = root ? collectInteractive2(root) : [];
+  return { app: options.app, elements };
+}
+
+// src/analyzer/ios.ts
+var IOS_INTERACTIVE_TYPES = /* @__PURE__ */ new Set([
+  "XCUIElementTypeButton",
+  "XCUIElementTypeCell",
+  "XCUIElementTypeTextField",
+  "XCUIElementTypeSecureTextField",
+  "XCUIElementTypeSearchField",
+  "XCUIElementTypeSwitch",
+  "XCUIElementTypeToggle",
+  "XCUIElementTypeLink",
+  "XCUIElementTypeMenuItem",
+  "XCUIElementTypeSlider",
+  "XCUIElementTypeStepper",
+  "XCUIElementTypeTextView",
+  "XCUIElementTypePickerWheel",
+  "XCUIElementTypeTab",
+  "XCUIElementTypeSegmentedControl",
+  "XCUIElementTypeCheckBox",
+  "XCUIElementTypeRadioButton",
+  "XCUIElementTypeKey"
+]);
+var IOS_WINDOW_TYPE = "XCUIElementTypeWindow";
+function str3(value) {
+  if (value === void 0) {
+    return void 0;
+  }
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : void 0;
+}
+function bool2(value) {
+  if (value === void 0) {
+    return void 0;
+  }
+  return value === "true" || value === "1";
+}
+function toIosNode(element) {
+  const a = element.attrs;
+  return {
+    type: str3(a.type) ?? str3(element.tag),
+    name: str3(a.name),
+    label: str3(a.label),
+    value: str3(a.value),
+    enabled: bool2(a.enabled),
+    visible: bool2(a.visible),
+    children: element.children.map(toIosNode)
+  };
+}
+function parseIosHierarchy(xml) {
+  const root = parseXml(xml);
+  return root ? toIosNode(root) : null;
+}
+function hasAccessibilityId(node) {
+  return node.name !== void 0 && node.name !== node.label;
+}
+function rankIosSelectors(node) {
+  return rankNativeSelectors({
+    id: hasAccessibilityId(node) ? node.name : void 0,
+    label: node.label,
+    role: node.type ? shortIosType(node.type) : void 0,
+    name: node.label ?? node.value
+  });
+}
+function iosNodeToNative(node) {
+  const textValues = [];
+  if (node.label !== void 0) {
+    textValues.push(node.label);
+  }
+  if (node.value !== void 0) {
+    textValues.push(node.value);
+  }
+  return {
+    ...node.name !== void 0 ? { id: node.name } : {},
+    ...node.label !== void 0 ? { label: node.label } : {},
+    ...node.type !== void 0 ? { role: node.type } : {},
+    textValues
+  };
+}
+function matchIosSelector(xml, selector) {
+  const parsedSelector = parseNativeSelector(selector);
+  const root = parseIosHierarchy(xml);
+  if (!root) {
+    return [];
+  }
+  return matchNativeTree(
+    IOS_MATCH_DIALECT,
+    parsedSelector,
+    root,
+    iosNodeToNative,
+    (node) => node.children
+  );
+}
+function toElement3(node) {
+  return {
+    type: node.type ?? "?",
+    ...node.name ? { name: node.name } : {},
+    ...node.label ? { label: node.label } : {},
+    ...node.value ? { value: node.value } : {},
+    ...node.enabled !== void 0 ? { enabled: node.enabled } : {},
+    ...node.visible !== void 0 ? { visible: node.visible } : {},
+    selectors: rankIosSelectors(node)
+  };
+}
+function toWindow2(node) {
+  const [best] = rankIosSelectors(node);
+  return {
+    ...node.name ? { name: node.name } : {},
+    ...node.label ? { label: node.label } : {},
+    selector: best ?? `role=${shortIosType(IOS_WINDOW_TYPE)}`
+  };
+}
+function isIosInteractive(node) {
+  return node.type !== void 0 && IOS_INTERACTIVE_TYPES.has(node.type);
+}
+function collect(root) {
+  const elements = [];
+  const windows = [];
+  const visit = (node) => {
+    if (node.type === IOS_WINDOW_TYPE) {
+      windows.push(toWindow2(node));
+    }
+    if (isIosInteractive(node)) {
+      elements.push(toElement3(node));
+    }
+    for (const child of node.children) {
+      visit(child);
+    }
+  };
+  visit(root);
+  return { elements, windows };
+}
+async function analyzeIosApp(client, options) {
+  const xml = await client.source();
+  const root = parseIosHierarchy(xml);
+  if (!root) {
+    return { app: options.app, elements: [], windows: [] };
+  }
+  const { elements, windows } = collect(root);
+  return { app: options.app, elements, windows };
+}
+
 // src/generator/index.ts
 import yaml from "yaml";
 
@@ -5942,6 +7055,7 @@ var STEP_REFERENCE = `
 
 ### Visual Regression
 - assertScreenshot: { name: "baseline-name", threshold: 0.1 }
+- assertWithAI: "The login form should show email and password fields" \u2014 AI checks the screenshot against the claim
 
 ### Control Flow
 - if: { visible: ".banner", then: [steps...] }
@@ -5983,81 +7097,6 @@ function extractYamlFromResponse(response) {
   return response.trim();
 }
 
-// src/generator/ai.ts
-function resolveAiConfig() {
-  const provider = process.env.PROWL_AI_PROVIDER ?? "anthropic";
-  if (provider !== "anthropic" && provider !== "openai") {
-    throw new Error(`Unsupported AI provider: ${provider}. Use "anthropic" or "openai".`);
-  }
-  const apiKey = process.env.PROWL_AI_KEY;
-  if (!apiKey) {
-    throw new Error(
-      "PROWL_AI_KEY environment variable is required. Set it to your Anthropic or OpenAI API key."
-    );
-  }
-  const defaultModel = provider === "anthropic" ? "claude-sonnet-4-5-20250929" : "gpt-4o";
-  const model = process.env.PROWL_AI_MODEL ?? defaultModel;
-  return { provider, model, apiKey };
-}
-async function generateWithAi(prompt, config) {
-  if (config.provider === "anthropic") {
-    return generateWithAnthropic(prompt, config);
-  }
-  return generateWithOpenAi(prompt, config);
-}
-async function generateWithAnthropic(prompt, config) {
-  const response = await fetch("https://api.anthropic.com/v1/messages", {
-    method: "POST",
-    headers: {
-      "Content-Type": "application/json",
-      "x-api-key": config.apiKey,
-      "anthropic-version": "2023-06-01"
-    },
-    body: JSON.stringify({
-      model: config.model,
-      max_tokens: 4096,
-      messages: [
-        { role: "user", content: prompt }
-      ]
-    })
-  });
-  if (!response.ok) {
-    const body = await response.text();
-    throw new Error(`Anthropic API error (${response.status}): ${body}`);
-  }
-  const data = await response.json();
-  const textBlock = data.content.find((c) => c.type === "text");
-  if (!textBlock?.text) {
-    throw new Error("Anthropic API returned no text content");
-  }
-  return textBlock.text;
-}
-async function generateWithOpenAi(prompt, config) {
-  const response = await fetch("https://api.openai.com/v1/chat/completions", {
-    method: "POST",
-    headers: {
-      "Content-Type": "application/json",
-      "Authorization": `Bearer ${config.apiKey}`
-    },
-    body: JSON.stringify({
-      model: config.model,
-      messages: [
-        { role: "user", content: prompt }
-      ],
-      max_tokens: 4096
-    })
-  });
-  if (!response.ok) {
-    const body = await response.text();
-    throw new Error(`OpenAI API error (${response.status}): ${body}`);
-  }
-  const data = await response.json();
-  if (!data.choices?.[0]?.message?.content) {
-    throw new Error("OpenAI API returned no content");
-  }
-  return data.choices[0].message.content;
-}
-
 // src/generator/index.ts
 function parseViewportFlag2(value) {
   const match = /^(\d+)x(\d+)$/i.exec(value);
@@ -6101,6 +7140,298 @@ async function generateHunt(options) {
   return yamlStr;
 }
 
+// src/browser/macdriver-install.ts
+import { execFile as execFile5 } from "child_process";
+import { createHash as createHash2 } from "crypto";
+import fs15 from "fs";
+import os5 from "os";
+import path17 from "path";
+import { promisify } from "util";
+var execFileAsync = promisify(execFile5);
+function parseChecksumFile(text) {
+  const token = text.trim().split(/\s+/, 1)[0] ?? "";
+  const digest = token.toLowerCase();
+  if (!/^[0-9a-f]{64}$/.test(digest)) {
+    throw new Error(`Malformed .sha256 checksum file (expected a 64-char hex digest, got: ${text.trim().slice(0, 80)})`);
+  }
+  return digest;
+}
+function sha256Hex(bytes) {
+  return createHash2("sha256").update(bytes).digest("hex");
+}
+var commandRunner = async (file, args) => execFileAsync(file, args);
+function commandOutput(result) {
+  return [result.stdout, result.stderr].filter((value) => value !== void 0).map((value) => value.toString()).join("\n").trim();
+}
+function commandErrorDetail(error) {
+  const err = error;
+  return [err.stderr, err.stdout, err.message].filter((value) => value !== void 0 && value !== "").map((value) => value.toString()).join("\n").trim();
+}
+async function runRequiredCommand(run, binaryPath, command, args, label) {
+  try {
+    return await run(command, args);
+  } catch (error) {
+    const detail = commandErrorDetail(error);
+    throw new Error(`${label} failed for ${binaryPath}${detail ? `: ${detail}` : ""}`);
+  }
+}
+var zipinfoArchiveLister = async (zipPath) => {
+  try {
+    const { stdout } = await execFileAsync("zipinfo", ["-1", zipPath]);
+    return stdout.toString().split(/\r?\n/).filter((entry) => entry.length > 0);
+  } catch (error) {
+    const detail = commandErrorDetail(error);
+    throw new Error(`Failed to inspect release archive ${zipPath} with zipinfo${detail ? `: ${detail}` : ""}`);
+  }
+};
+function normalizeArchiveEntryName(entry) {
+  if (entry.length === 0 || entry !== entry.trim() || entry.includes("\0") || entry.includes("\\")) {
+    throw new Error(`Unsafe path in prowl-macdriver release archive: ${JSON.stringify(entry)}`);
+  }
+  if (entry.endsWith("/")) {
+    throw new Error(`Unexpected directory in prowl-macdriver release archive: ${entry}`);
+  }
+  if (path17.posix.isAbsolute(entry)) {
+    throw new Error(`Unsafe absolute path in prowl-macdriver release archive: ${entry}`);
+  }
+  const parts = entry.split("/");
+  if (parts.some((part) => part === "" || part === "." || part === "..")) {
+    throw new Error(`Unsafe path in prowl-macdriver release archive: ${entry}`);
+  }
+  return entry;
+}
+function validateMacdriverArchiveEntries(entries) {
+  const normalized = entries.map(normalizeArchiveEntryName);
+  if (normalized.length !== 1 || normalized[0] !== HELPER_BINARY) {
+    const shown = normalized.length > 0 ? normalized.join(", ") : "(empty archive)";
+    throw new Error(
+      `Unexpected prowl-macdriver release archive contents: ${shown}. Expected exactly "${HELPER_BINARY}" at the archive root.`
+    );
+  }
+}
+var dittoExtractor = async (zipPath, destDir) => {
+  await execFileAsync("ditto", ["-x", "-k", zipPath, destDir]);
+};
+function parseCodesignDetails(text) {
+  const details = { identifier: null, authorities: [], teamIdentifier: null };
+  for (const line of text.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (trimmed.startsWith("Identifier=")) {
+      details.identifier = trimmed.slice("Identifier=".length);
+    } else if (trimmed.startsWith("Authority=")) {
+      details.authorities.push(trimmed.slice("Authority=".length));
+    } else if (trimmed.startsWith("TeamIdentifier=")) {
+      details.teamIdentifier = trimmed.slice("TeamIdentifier=".length);
+    }
+  }
+  return details;
+}
+function validateCodesignDetails(details, binaryPath) {
+  if (details.identifier !== MACDRIVER_SIGNING_IDENTIFIER) {
+    throw new Error(
+      `codesign verification failed for ${binaryPath}: expected identifier "${MACDRIVER_SIGNING_IDENTIFIER}", got "${details.identifier ?? "missing"}"`
+    );
+  }
+  const developerIdAuthority = details.authorities.find(
+    (authority) => authority.startsWith(`${MACDRIVER_SIGNING_AUTHORITY_PREFIX} (`)
+  );
+  const authorityTeamId = developerIdAuthority?.match(/\(([A-Z0-9]{10})\)$/)?.[1] ?? null;
+  if (!developerIdAuthority || !authorityTeamId) {
+    const shown = details.authorities.length > 0 ? details.authorities.join(" / ") : "missing";
+    throw new Error(
+      `codesign verification failed for ${binaryPath}: expected ${MACDRIVER_SIGNING_AUTHORITY_PREFIX} signer, got ${shown}`
+    );
+  }
+  if (!details.teamIdentifier) {
+    throw new Error(`codesign verification failed for ${binaryPath}: missing TeamIdentifier`);
+  }
+  if (details.teamIdentifier !== authorityTeamId) {
+    throw new Error(
+      `codesign verification failed for ${binaryPath}: TeamIdentifier ${details.teamIdentifier} does not match Developer ID authority team ${authorityTeamId}`
+    );
+  }
+}
+async function verifyMacdriverSignature(binaryPath, run = commandRunner) {
+  await runRequiredCommand(run, binaryPath, "codesign", ["--verify", "--strict", binaryPath], "codesign verification");
+  const display = await runRequiredCommand(
+    run,
+    binaryPath,
+    "codesign",
+    ["--display", "--verbose=4", binaryPath],
+    "codesign detail inspection"
+  );
+  validateCodesignDetails(parseCodesignDetails(commandOutput(display)), binaryPath);
+  await runRequiredCommand(
+    run,
+    binaryPath,
+    "spctl",
+    ["--assess", "--type", "execute", "--verbose=4", binaryPath],
+    "spctl assessment"
+  );
+}
+var codesignVerifier = async (binaryPath) => {
+  await verifyMacdriverSignature(binaryPath);
+};
+async function downloadAndVerify(options = {}) {
+  const version = options.version ?? MACDRIVER_VERSION;
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const assetName = macdriverAssetName(version);
+  const zipUrl = macdriverAssetUrl(assetName, version);
+  const sumUrl = macdriverAssetUrl(macdriverChecksumName(version), version);
+  const [zipRes, sumRes] = await Promise.all([
+    fetchImpl(zipUrl, { redirect: "follow" }),
+    fetchImpl(sumUrl, { redirect: "follow" })
+  ]);
+  if (zipRes.status === 404 || sumRes.status === 404) {
+    throw new Error(
+      `No published prowl-macdriver release for ${macdriverReleaseTag(version)} yet.
+The signed binary is cut by the maintainer; until then build from source:
+  cd macdriver && swift build -c release`
+    );
+  }
+  if (!zipRes.ok) {
+    throw new Error(`Failed to download ${assetName} (HTTP ${zipRes.status}) from ${zipUrl}`);
+  }
+  if (!sumRes.ok) {
+    throw new Error(`Failed to download the checksum (HTTP ${sumRes.status}) from ${sumUrl}`);
+  }
+  const zipBytes = Buffer.from(await zipRes.arrayBuffer());
+  const expected = parseChecksumFile(await sumRes.text());
+  const actual = sha256Hex(zipBytes);
+  if (actual !== expected) {
+    throw new Error(
+      `Checksum mismatch for ${assetName}.
+  expected: ${expected}
+  actual:   ${actual}
+The download was rejected and discarded; re-run the install, and report it if it repeats.`
+    );
+  }
+  return zipBytes;
+}
+async function installMacdriver(options = {}) {
+  const version = validateMacdriverVersion(options.version ?? MACDRIVER_VERSION);
+  const homedir = options.homedir ?? os5.homedir();
+  const listArchiveEntries = options.listArchiveEntries ?? zipinfoArchiveLister;
+  const extract = options.extract ?? dittoExtractor;
+  const verifySignature = options.verifySignature ?? codesignVerifier;
+  const installRoot = macdriverInstallRoot(homedir);
+  const versionDir = macdriverVersionDir(version, homedir);
+  const binaryPath = macdriverInstalledBinary(version, homedir);
+  if (!options.force && fs15.existsSync(binaryPath)) {
+    return { version, binaryPath, alreadyInstalled: true };
+  }
+  const zipBytes = await downloadAndVerify({ version, fetchImpl: options.fetchImpl });
+  fs15.mkdirSync(installRoot, { recursive: true });
+  const stagingDir = fs15.mkdtempSync(path17.join(installRoot, `.tmp-${version}-`));
+  const extractDir = path17.join(stagingDir, "extract");
+  const zipPath = path17.join(stagingDir, macdriverAssetName(version));
+  try {
+    fs15.mkdirSync(extractDir);
+    fs15.writeFileSync(zipPath, zipBytes);
+    validateMacdriverArchiveEntries(await listArchiveEntries(zipPath));
+    await extract(zipPath, extractDir);
+    const stagedBinaryPath = path17.join(extractDir, HELPER_BINARY);
+    assertExtractedHelper(extractDir, stagedBinaryPath);
+    fs15.chmodSync(stagedBinaryPath, 493);
+    await verifySignature(stagedBinaryPath);
+    replaceVersionDir(versionDir, extractDir, installRoot);
+  } finally {
+    fs15.rmSync(stagingDir, { recursive: true, force: true });
+  }
+  return { version, binaryPath, alreadyInstalled: false };
+}
+function assertExtractedHelper(extractDir, binaryPath) {
+  const entries = fs15.readdirSync(extractDir);
+  if (!entries.includes(HELPER_BINARY)) {
+    throw new Error(`The release archive did not contain a "${HELPER_BINARY}" binary.`);
+  }
+  if (entries.length !== 1 || entries[0] !== HELPER_BINARY) {
+    const shown = entries.length > 0 ? entries.join(", ") : "(empty directory)";
+    throw new Error(
+      `Unexpected extracted prowl-macdriver archive contents: ${shown}. Expected exactly "${HELPER_BINARY}".`
+    );
+  }
+  let stat = null;
+  try {
+    stat = fs15.lstatSync(binaryPath);
+  } catch {
+  }
+  if (!stat?.isFile()) {
+    throw new Error(`The release archive "${HELPER_BINARY}" entry is not a regular file.`);
+  }
+}
+function replaceVersionDir(versionDir, stagedVersionDir, installRoot) {
+  const backupDir = path17.join(installRoot, `.previous-${path17.basename(versionDir)}-${process.pid}-${Date.now()}`);
+  let backedUp = false;
+  try {
+    if (fs15.existsSync(versionDir)) {
+      fs15.renameSync(versionDir, backupDir);
+      backedUp = true;
+    }
+    fs15.renameSync(stagedVersionDir, versionDir);
+    if (backedUp) {
+      fs15.rmSync(backupDir, { recursive: true, force: true });
+    }
+  } catch (error) {
+    if (backedUp && !fs15.existsSync(versionDir) && fs15.existsSync(backupDir)) {
+      fs15.renameSync(backupDir, versionDir);
+    }
+    throw error;
+  }
+}
+var runVersionProbe = async (binaryPath) => {
+  try {
+    const { stdout } = await execFileAsync(binaryPath, ["version"], { timeout: 5e3 });
+    const match = stdout.match(/prowl-macdriver\s+(\S+)/);
+    return match ? match[1] : stdout.trim() || null;
+  } catch {
+    return null;
+  }
+};
+async function collectMacdriverStatus(options = {}) {
+  const env = options.env ?? process.env;
+  const homedir = options.homedir ?? os5.homedir();
+  const probe = options.probe ?? runVersionProbe;
+  let resolved = null;
+  try {
+    const resolvedPath = resolveHelperBinary(env, { homedir });
+    resolved = { path: resolvedPath, source: classifyResolvedSource(resolvedPath, env, homedir) };
+  } catch {
+    resolved = null;
+  }
+  const installed = [];
+  const root = macdriverInstallRoot(homedir);
+  if (fs15.existsSync(root)) {
+    for (const entry of fs15.readdirSync(root, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      let binaryPath;
+      try {
+        binaryPath = macdriverInstalledBinary(entry.name, homedir);
+      } catch {
+        continue;
+      }
+      if (fs15.existsSync(binaryPath)) {
+        installed.push({ version: entry.name, binaryPath });
+      }
+    }
+    installed.sort((a, b) => a.version.localeCompare(b.version));
+  }
+  const probedVersion = resolved ? await probe(resolved.path) : null;
+  return { resolved, pinnedVersion: MACDRIVER_VERSION, installed, probedVersion };
+}
+function classifyResolvedSource(resolvedPath, env, homedir) {
+  if (env.PROWL_MACDRIVER_BIN && resolvedPath === env.PROWL_MACDRIVER_BIN) {
+    return "env";
+  }
+  if (resolvedPath.startsWith(macdriverInstallRoot(homedir) + path17.sep)) {
+    return "user-install";
+  }
+  return "source-build";
+}
+function tccGuidance() {
+  return "macOS permissions: the app that hosts Prowl (your terminal \u2014 Terminal, iTerm, VS Code, \u2026)\nmust be granted, in System Settings \u2192 Privacy & Security:\n  \u2022 Accessibility \u2014 required to drive the target app\n  \u2022 Screen Recording \u2014 required for screenshots / visual baselines\nGrant both to the terminal app, not to prowl-macdriver itself, then re-run your hunt.";
+}
+
 export {
   interpolateHunt,
   WEB_ONLY_STEP_TYPES,
@@ -6118,12 +7449,43 @@ export {
   createPlaywrightDriver,
   parseMacSelector,
   createMacDriver,
+  HELPER_BINARY,
+  MACDRIVER_VERSION,
+  MACDRIVER_REPO,
+  MACDRIVER_SIGNING_IDENTIFIER,
+  MACDRIVER_SIGNING_AUTHORITY_PREFIX,
+  MACDRIVER_VERSION_PATTERN,
+  validateMacdriverVersion,
+  macdriverReleaseTag,
+  macdriverAssetName,
+  macdriverChecksumName,
+  macdriverAssetUrl,
+  macdriverInstallRoot,
+  macdriverVersionDir,
+  macdriverInstalledBinary,
   macdriverBuildInstructions,
   resolveHelperBinary,
   DEFAULT_REQUEST_TIMEOUT_MS,
   SpawnMacHelperClient,
   launchMacSession,
   closeMacSession,
+  decodeXmlEntities,
+  parseXml,
+  unquoteSelectorValue,
+  quoteSelectorValue,
+  parseNativeSelector,
+  unwrapNativeTextSelector,
+  qualifyResourceId,
+  normalizeXcuiClassName,
+  shortIosType,
+  rankNativeSelectors,
+  NATIVE_ATTRIBUTE_MAP,
+  ANDROID_MATCH_DIALECT,
+  IOS_MATCH_DIALECT,
+  MACOS_MATCH_DIALECT,
+  nodeMatchesSelector,
+  matchNativeTree,
+  parseSnapshot,
   ANDROID_KEYCODES,
   escapeUiSelectorArg,
   parseAndroidSelector,
@@ -6150,7 +7512,6 @@ export {
   closeAndroidSession,
   IOS_PRESS_KEYS,
   escapePredicateArg,
-  normalizeXcuiClassName,
   parseIosSelector,
   iosQueryToLocator,
   unwrapIosTextSelector,
@@ -6170,11 +7531,14 @@ export {
   waitForWdaReady,
   createWdaAgentClient,
   WDA_RUNNER_BUNDLE_ID,
-  WDA_RUNNER_APP_NAME,
+  WDA_USE_PORT_ENV,
   defaultIosAgentConnector,
   resolveWdaProject,
   wdaCacheDir,
-  resolveWdaRunner,
+  resolveWdaTestRun,
+  injectUsePortIntoXctestrun,
+  defaultWdaTestRunPreparer,
+  wdaTestRunArgs,
   launchIosSession,
   closeIosSession,
   extractSelectorIntent,
@@ -6197,6 +7561,34 @@ export {
   DEFAULT_ANALYZE_TREE_DEPTH,
   rankMacSelectors,
   analyzeMacApp,
-  generateHunt
+  ANDROID_INTERACTIVE_CLASSES,
+  parseAndroidHierarchy,
+  isAndroidInteractive,
+  rankAndroidSelectors,
+  androidNodeToNative,
+  matchAndroidSelector,
+  analyzeAndroidApp,
+  IOS_INTERACTIVE_TYPES,
+  IOS_WINDOW_TYPE,
+  parseIosHierarchy,
+  rankIosSelectors,
+  iosNodeToNative,
+  matchIosSelector,
+  isIosInteractive,
+  analyzeIosApp,
+  generateHunt,
+  parseChecksumFile,
+  sha256Hex,
+  zipinfoArchiveLister,
+  validateMacdriverArchiveEntries,
+  dittoExtractor,
+  parseCodesignDetails,
+  verifyMacdriverSignature,
+  codesignVerifier,
+  downloadAndVerify,
+  installMacdriver,
+  runVersionProbe,
+  collectMacdriverStatus,
+  tccGuidance
 };
-//# sourceMappingURL=chunk-2KD2XCTH.js.map
+//# sourceMappingURL=chunk-R7NUH44M.js.map