prowl-tools 0.1.6 → 0.1.8

package/dist/index.cjs

@@ -43,18 +43,33 @@ var init_types = __esm({
 function isValidHuntName(name) {
   return HUNT_NAME_PATTERN.test(name);
 }
+function normalizeHuntName(input) {
+  let name = input.trim();
+  if (name.startsWith("./")) {
+    name = name.slice(2);
+  }
+  const isSupportedHuntPath = HUNT_FILE_EXTENSION_PATTERN.test(name);
+  if (isSupportedHuntPath && name.startsWith(".prowl/hunts/")) {
+    name = name.slice(".prowl/hunts/".length);
+  } else if (isSupportedHuntPath && name.startsWith("hunts/")) {
+    name = name.slice("hunts/".length);
+  }
+  name = name.replace(HUNT_FILE_EXTENSION_PATTERN, "");
+  return name;
+}
 function assertValidHuntName(name) {
   if (!isValidHuntName(name)) {
     throw new Error(
-      `Invalid hunt name: "${name}". Use only letters, numbers, hyphens, underscores, and forward slashes.`
+      `Invalid hunt name: "${name}". A hunt name is its file name under .prowl/hunts/ (letters, numbers, hyphens, underscores, and forward slashes for nested hunts). Accepted forms: a bare name (homepage), a nested name (admin/users), or a path (.prowl/hunts/homepage.yml or hunts/homepage.yml).`
     );
   }
 }
-var HUNT_NAME_PATTERN;
+var HUNT_NAME_PATTERN, HUNT_FILE_EXTENSION_PATTERN;
 var init_hunt_name = __esm({
   "src/config/hunt-name.ts"() {
     "use strict";
     HUNT_NAME_PATTERN = /^[A-Za-z0-9_-]+(?:\/[A-Za-z0-9_-]+)*$/;
+    HUNT_FILE_EXTENSION_PATTERN = /\.yml$/i;
   }
 });
 
@@ -383,808 +398,839 @@ var init_schema = __esm({
   }
 });
 
-// src/config/loader.ts
-var loader_exports = {};
-__export(loader_exports, {
-  CONFIG_DIR: () => CONFIG_DIR,
-  LEGACY_CONFIG_DIR: () => LEGACY_CONFIG_DIR,
-  ensureAllowedDomain: () => ensureAllowedDomain,
-  findConfigPath: () => findConfigPath,
-  listHunts: () => listHunts,
-  loadConfig: () => loadConfig,
-  loadHunt: () => loadHunt,
-  loadHuntMeta: () => loadHuntMeta,
-  loadHuntTags: () => loadHuntTags,
-  resolveViewport: () => resolveViewport,
-  warnLegacyConfigDir: () => warnLegacyConfigDir
-});
-function warnLegacyConfigDir() {
-  if (legacyDirWarned) {
+// src/config/interpolate.ts
+function collectInterpolatedValues(input, vars, values) {
+  if (typeof input === "string") {
+    for (const match of input.matchAll(VAR_PATTERN)) {
+      const varValue = vars[match[1]];
+      if (varValue) values.add(varValue);
+    }
     return;
   }
-  legacyDirWarned = true;
-  console.warn(
-    'Warning: the ".prowlqa/" config directory is deprecated; rename it to ".prowl/". Support for ".prowlqa/" will be removed in a future release.'
-  );
-}
-function findConfigPath(startDir) {
-  let current = startDir;
-  while (current) {
-    for (const dir of [CONFIG_DIR, LEGACY_CONFIG_DIR]) {
-      const candidate = import_node_path.default.join(current, dir, "config.yml");
-      if (import_node_fs.default.existsSync(candidate)) {
-        return candidate;
-      }
+  if (Array.isArray(input)) {
+    for (const item of input) {
+      collectInterpolatedValues(item, vars, values);
     }
-    const parent = import_node_path.default.dirname(current);
-    if (parent === current) {
-      break;
+    return;
+  }
+  if (input && typeof input === "object") {
+    for (const [key, value] of Object.entries(input)) {
+      collectInterpolatedValues(key, vars, values);
+      collectInterpolatedValues(value, vars, values);
     }
-    current = parent;
   }
-  return null;
 }
-function resolveViewport(value) {
-  if (value === void 0) {
-    return DEFAULT_CONFIG.browser.viewport;
-  }
-  if (typeof value === "string") {
-    const preset = VIEWPORT_PRESETS[value];
-    if (!preset) {
-      throw new Error(`Unknown viewport preset: "${value}". Use mobile, tablet, or desktop.`);
+function interpolateString(input, vars) {
+  const usedVars = [];
+  const value = input.replace(VAR_PATTERN, (_, name) => {
+    const varValue = vars[name];
+    if (varValue === void 0) {
+      throw new Error(`Missing variable: ${name}`);
     }
-    return preset;
-  }
-  return value;
+    usedVars.push(name);
+    return varValue;
+  });
+  return { value, usedVars };
 }
-function resolveTarget(target) {
-  const type = target?.type;
-  if (type === "macos") {
-    return { type: "macos", app: target.app };
+function generateRandomVars(randomSource) {
+  const random = randomSource?.random ?? Math.random;
+  const randomBytes = randomSource?.randomBytes ?? import_node_crypto.default.randomBytes;
+  const randomUUID = randomSource?.randomUUID ?? import_node_crypto.default.randomUUID;
+  const hex = randomBytes(4).toString("hex");
+  const firstIndex = Math.floor(random() * RANDOM_FIRST_NAMES.length);
+  const lastIndex = Math.floor(random() * RANDOM_LAST_NAMES.length);
+  const num2 = Math.floor(random() * 9e3) + 1e3;
+  const chars = "abcdefghijklmnopqrstuvwxyz0123456789";
+  let text = "";
+  for (let i = 0; i < 8; i++) {
+    text += chars[Math.floor(random() * chars.length)];
   }
-  if (type === "android") {
-    const androidTarget = target;
+  return {
+    RANDOM_EMAIL: `prowl_${hex}@test.com`,
+    RANDOM_NAME: `${RANDOM_FIRST_NAMES[firstIndex]} ${RANDOM_LAST_NAMES[lastIndex]}`,
+    RANDOM_NUMBER: String(num2),
+    RANDOM_UUID: randomUUID(),
+    RANDOM_TEXT: text
+  };
+}
+function interpolateStep(step, vars, stepPath2, redacted) {
+  const isExplicitFill = (value) => typeof value.selector === "string" && typeof value.value === "string";
+  const interpolateSinglePair = (record) => {
+    const entries = Object.entries(record);
+    if (entries.length !== 1) {
+      throw new Error("Shorthand step expects exactly one key-value pair");
+    }
+    const [key, value] = entries[0];
     return {
-      type: "android",
-      app: androidTarget.app,
-      ...androidTarget.deviceSerial !== void 0 ? { deviceSerial: androidTarget.deviceSerial } : {},
-      ...androidTarget.coldStart !== void 0 ? { coldStart: androidTarget.coldStart } : {}
+      [interpolateString(key, vars).value]: interpolateString(value, vars).value
     };
+  };
+  if ("navigate" in step) {
+    const result = interpolateString(step.navigate, vars);
+    return { navigate: result.value };
   }
-  if (type === "ios") {
-    const iosTarget = target;
+  if ("click" in step) {
+    if (typeof step.click === "string") {
+      return { click: interpolateString(step.click, vars).value };
+    }
+    const result = interpolateString(step.click.selector, vars);
+    return { click: { selector: result.value } };
+  }
+  if ("fill" in step) {
+    if (isExplicitFill(step.fill)) {
+      const selectorResult = interpolateString(step.fill.selector, vars);
+      const valueResult2 = interpolateString(step.fill.value, vars);
+      if (valueResult2.usedVars.length > 0) {
+        redacted.add(stepPath2);
+      }
+      return { fill: { selector: selectorResult.value, value: valueResult2.value } };
+    }
+    const [rawLabel, rawValue] = Object.entries(step.fill)[0] ?? [];
+    if (rawLabel === void 0 || rawValue === void 0) {
+      throw new Error("Shorthand fill expects exactly one key-value pair");
+    }
+    const labelResult = interpolateString(rawLabel, vars);
+    const valueResult = interpolateString(rawValue, vars);
+    if (valueResult.usedVars.length > 0) {
+      redacted.add(stepPath2);
+    }
     return {
-      type: "ios",
-      app: iosTarget.app,
-      ...iosTarget.udid !== void 0 ? { udid: iosTarget.udid } : {},
-      ...iosTarget.coldStart !== void 0 ? { coldStart: iosTarget.coldStart } : {}
+      fill: {
+        [labelResult.value]: valueResult.value
+      }
     };
   }
-  return {
-    type: "web",
-    url: target?.url ?? DEFAULT_WEB_URL
-  };
-}
-function mergeConfig(partial) {
-  return {
-    target: resolveTarget(partial.target),
-    browser: {
-      headless: partial.browser?.headless ?? DEFAULT_CONFIG.browser.headless,
-      slowMo: partial.browser?.slowMo ?? DEFAULT_CONFIG.browser.slowMo,
-      timeout: partial.browser?.timeout ?? DEFAULT_CONFIG.browser.timeout,
-      engine: partial.browser?.engine ?? DEFAULT_CONFIG.browser.engine,
-      channel: partial.browser?.channel,
-      viewport: resolveViewport(partial.browser?.viewport)
-    },
-    artifacts: {
-      screenshots: partial.artifacts?.screenshots ?? DEFAULT_CONFIG.artifacts.screenshots,
-      networkHar: partial.artifacts?.networkHar ?? DEFAULT_CONFIG.artifacts.networkHar,
-      console: partial.artifacts?.console ?? DEFAULT_CONFIG.artifacts.console,
-      junit: partial.artifacts?.junit ?? DEFAULT_CONFIG.artifacts.junit
-    },
-    assertions: {
-      noConsoleErrors: partial.assertions?.noConsoleErrors ?? DEFAULT_CONFIG.assertions.noConsoleErrors,
-      noNetworkErrors: partial.assertions?.noNetworkErrors ?? DEFAULT_CONFIG.assertions.noNetworkErrors,
-      maxTotalTimeMs: partial.assertions?.maxTotalTimeMs ?? DEFAULT_CONFIG.assertions.maxTotalTimeMs,
-      networkIgnorePatterns: partial.assertions?.networkIgnorePatterns ?? DEFAULT_CONFIG.assertions.networkIgnorePatterns
-    },
-    guardrails: {
-      maxSteps: partial.guardrails?.maxSteps ?? DEFAULT_CONFIG.guardrails.maxSteps,
-      allowedDomains: partial.guardrails?.allowedDomains ?? DEFAULT_CONFIG.guardrails.allowedDomains,
-      allowedApps: partial.guardrails?.allowedApps ?? DEFAULT_CONFIG.guardrails.allowedApps,
-      forbiddenSelectors: partial.guardrails?.forbiddenSelectors ?? DEFAULT_CONFIG.guardrails.forbiddenSelectors,
-      selfHealing: partial.guardrails?.selfHealing ?? DEFAULT_CONFIG.guardrails.selfHealing
-    },
-    auth: {
-      storageStatePath: partial.auth?.storageStatePath ?? (partial.auth !== void 0 ? DEFAULT_CONFIG.auth.storageStatePath : void 0)
-    },
-    history: {
-      maxRuns: partial.history?.maxRuns ?? DEFAULT_CONFIG.history.maxRuns
-    },
-    bugLog: partial.bugLog,
-    tracing: partial.tracing,
-    reliability: partial.reliability
-  };
-}
-function ensureAllowedDomain(allowed, urlValue) {
-  try {
-    const host = new URL(urlValue).hostname;
-    if (!allowed.includes(host)) {
-      return [...allowed, host];
+  if ("type" in step) {
+    const valueResult = interpolateString(step.type, vars);
+    if (valueResult.usedVars.length > 0) {
+      redacted.add(stepPath2);
     }
-  } catch {
-    return allowed;
+    return { type: valueResult.value };
   }
-  return allowed;
-}
-function loadConfig(configPath) {
-  const resolvedPath = configPath ? import_node_path.default.resolve(configPath) : findConfigPath(process.cwd());
-  if (!resolvedPath) {
-    throw new Error("Could not find .prowl/config.yml. Run `prowl init` first.");
+  if ("selectOption" in step) {
+    const selectorResult = interpolateString(step.selectOption.selector, vars);
+    const valueResult = interpolateString(step.selectOption.value, vars);
+    return { selectOption: { selector: selectorResult.value, value: valueResult.value } };
   }
-  if (!import_node_fs.default.existsSync(resolvedPath)) {
-    throw new Error(`Config file not found at ${resolvedPath}`);
+  if ("select" in step) {
+    return { select: interpolateSinglePair(step.select) };
   }
-  const configDir = import_node_path.default.dirname(resolvedPath);
-  if (import_node_path.default.basename(configDir) === LEGACY_CONFIG_DIR) {
-    warnLegacyConfigDir();
+  if ("press" in step) {
+    const selectorResult = interpolateString(step.press.selector, vars);
+    const keyResult = interpolateString(step.press.key, vars);
+    return { press: { selector: selectorResult.value, key: keyResult.value } };
   }
-  import_dotenv.default.config({ path: import_node_path.default.join(configDir, ".env"), override: false });
-  const raw = import_node_fs.default.readFileSync(resolvedPath, "utf-8");
-  const parsed = import_yaml.default.parse(raw) ?? {};
-  const validated = configSchema.parse(parsed);
-  const config = mergeConfig(validated);
-  if (config.target.type === "web") {
-    config.guardrails.allowedDomains = ensureAllowedDomain(
-      config.guardrails.allowedDomains,
-      config.target.url
-    );
+  if ("onDialog" in step) {
+    return { onDialog: { action: step.onDialog.action } };
   }
-  return { config, configPath: resolvedPath, configDir };
-}
-function loadHunt(huntName, configDir) {
-  assertValidHuntName(huntName);
-  const huntPath = import_node_path.default.join(configDir, "hunts", `${huntName}.yml`);
-  if (!import_node_fs.default.existsSync(huntPath)) {
-    throw new Error(`Hunt file not found: ${huntPath}`);
+  if ("setInputFiles" in step) {
+    const selectorResult = interpolateString(step.setInputFiles.selector, vars);
+    const rawFiles = step.setInputFiles.files;
+    const files = Array.isArray(rawFiles) ? rawFiles.map((f) => interpolateString(f, vars).value) : interpolateString(rawFiles, vars).value;
+    return { setInputFiles: { selector: selectorResult.value, files } };
   }
-  const raw = import_node_fs.default.readFileSync(huntPath, "utf-8");
-  const parsed = import_yaml.default.parse(raw) ?? {};
-  const validated = huntSchema.parse(parsed);
-  return validated;
-}
-function loadHuntTags(huntName, configDir) {
-  assertValidHuntName(huntName);
-  const huntPath = import_node_path.default.join(configDir, "hunts", `${huntName}.yml`);
-  if (!import_node_fs.default.existsSync(huntPath)) {
-    return [];
-  }
-  const raw = import_node_fs.default.readFileSync(huntPath, "utf-8");
-  const parsed = import_yaml.default.parse(raw) ?? {};
-  return Array.isArray(parsed.tags) ? parsed.tags : [];
-}
-function loadHuntMeta(huntName, configDir) {
-  assertValidHuntName(huntName);
-  const huntPath = import_node_path.default.join(configDir, "hunts", `${huntName}.yml`);
-  if (!import_node_fs.default.existsSync(huntPath)) {
-    return { tags: [] };
-  }
-  const raw = import_node_fs.default.readFileSync(huntPath, "utf-8");
-  const parsed = import_yaml.default.parse(raw) ?? {};
-  return {
-    description: typeof parsed.description === "string" ? parsed.description : void 0,
-    tags: Array.isArray(parsed.tags) ? parsed.tags : []
-  };
-}
-function listHunts(configDir) {
-  const huntsDir = import_node_path.default.join(configDir, "hunts");
-  if (!import_node_fs.default.existsSync(huntsDir)) {
-    return [];
-  }
-  const stats = import_node_fs.default.statSync(huntsDir);
-  if (!stats.isDirectory()) {
-    throw new Error(`Hunts path is not a directory: ${huntsDir}`);
-  }
-  const results = [];
-  function scanDir(dir) {
-    const entries = import_node_fs.default.readdirSync(dir, { withFileTypes: true });
-    for (const entry of entries) {
-      if (entry.isFile() && entry.name.endsWith(".yml")) {
-        const fullPath = import_node_path.default.join(dir, entry.name);
-        const relative = import_node_path.default.relative(huntsDir, fullPath);
-        results.push(relative.replace(/\.yml$/, ""));
-      } else if (entry.isDirectory()) {
-        scanDir(import_node_path.default.join(dir, entry.name));
+  if ("runHunt" in step) {
+    if (typeof step.runHunt === "string") {
+      return { runHunt: interpolateString(step.runHunt, vars).value };
+    }
+    const nameResult = interpolateString(step.runHunt.name, vars);
+    const interpolatedVars = {};
+    for (const [key, value] of Object.entries(step.runHunt.vars ?? {})) {
+      interpolatedVars[key] = interpolateString(value, vars).value;
+    }
+    return {
+      runHunt: {
+        name: nameResult.value,
+        ...Object.keys(interpolatedVars).length > 0 ? { vars: interpolatedVars } : {}
       }
+    };
+  }
+  if ("assert" in step) {
+    if (step.assert.visible !== void 0) {
+      return { assert: { visible: interpolateString(step.assert.visible, vars).value } };
+    }
+    if (step.assert.notVisible !== void 0) {
+      return { assert: { notVisible: interpolateString(step.assert.notVisible, vars).value } };
+    }
+    if (step.assert.urlIncludes !== void 0) {
+      return { assert: { urlIncludes: interpolateString(step.assert.urlIncludes, vars).value } };
+    }
+    if (step.assert.urlEquals !== void 0) {
+      return { assert: { urlEquals: interpolateString(step.assert.urlEquals, vars).value } };
     }
+    return step;
   }
-  scanDir(huntsDir);
-  return results.sort((a, b) => a.localeCompare(b));
-}
-var import_node_fs, import_node_path, import_yaml, import_dotenv, DEFAULT_WEB_URL, DEFAULT_CONFIG, CONFIG_DIR, LEGACY_CONFIG_DIR, legacyDirWarned, VIEWPORT_PRESETS;
-var init_loader = __esm({
-  "src/config/loader.ts"() {
-    "use strict";
-    import_node_fs = __toESM(require("fs"), 1);
-    import_node_path = __toESM(require("path"), 1);
-    import_yaml = __toESM(require("yaml"), 1);
-    import_dotenv = __toESM(require("dotenv"), 1);
-    init_schema();
-    init_hunt_name();
-    DEFAULT_WEB_URL = "http://localhost:3000";
-    DEFAULT_CONFIG = {
-      target: {
-        type: "web",
-        url: DEFAULT_WEB_URL
-      },
-      browser: {
-        headless: true,
-        slowMo: 0,
-        timeout: 3e4,
-        engine: "chromium",
-        viewport: { width: 1280, height: 720 }
-      },
-      artifacts: {
-        screenshots: "on-failure",
-        networkHar: false,
-        console: true,
-        junit: false
-      },
-      assertions: {
-        noConsoleErrors: true,
-        noNetworkErrors: true,
-        maxTotalTimeMs: 3e4,
-        networkIgnorePatterns: []
-      },
-      guardrails: {
-        maxSteps: 50,
-        allowedDomains: ["localhost", "127.0.0.1", "0.0.0.0"],
-        allowedApps: [],
-        forbiddenSelectors: ["[data-danger]", ".delete-btn"],
-        selfHealing: false
-      },
-      auth: {
-        storageStatePath: ".prowl/auth-state.json"
-      },
-      history: {
-        maxRuns: 100
+  if ("wait" in step) {
+    if (typeof step.wait === "string") {
+      return { wait: interpolateString(step.wait, vars).value };
+    }
+    return {
+      wait: {
+        for: interpolateString(step.wait.for, vars).value,
+        timeout: step.wait.timeout
       }
     };
-    CONFIG_DIR = ".prowl";
-    LEGACY_CONFIG_DIR = ".prowlqa";
-    legacyDirWarned = false;
-    VIEWPORT_PRESETS = {
-      mobile: { width: 375, height: 812 },
-      tablet: { width: 768, height: 1024 },
-      desktop: { width: 1280, height: 720 }
-    };
   }
-});
-
-// src/runner/visual.ts
-var visual_exports = {};
-__export(visual_exports, {
-  compareScreenshots: () => compareScreenshots,
-  ensureBaselineDir: () => ensureBaselineDir
-});
-async function compareScreenshots(baselinePath, currentPath, diffPath, threshold) {
-  const baselineData = import_pngjs.PNG.sync.read(import_node_fs8.default.readFileSync(baselinePath));
-  const currentData = import_pngjs.PNG.sync.read(import_node_fs8.default.readFileSync(currentPath));
-  const { width, height } = baselineData;
-  if (currentData.width !== width || currentData.height !== height) {
-    const diff2 = new import_pngjs.PNG({ width, height });
-    import_node_fs8.default.writeFileSync(diffPath, import_pngjs.PNG.sync.write(diff2));
+  if ("waitForSelector" in step) {
+    const selectorResult = interpolateString(step.waitForSelector.selector, vars);
     return {
-      match: false,
-      diffPercentage: 1,
-      diffImagePath: diffPath
+      waitForSelector: {
+        selector: selectorResult.value,
+        timeout: step.waitForSelector.timeout
+      }
     };
   }
-  const diff = new import_pngjs.PNG({ width, height });
-  const diffPixels = (0, import_pixelmatch.default)(
-    baselineData.data,
-    currentData.data,
-    diff.data,
-    width,
-    height,
-    { threshold: 0.1 }
-  );
-  const totalPixels = width * height;
-  const diffPercentage = diffPixels / totalPixels;
-  import_node_fs8.default.writeFileSync(diffPath, import_pngjs.PNG.sync.write(diff));
-  return {
-    match: diffPercentage <= threshold,
-    diffPercentage,
-    diffImagePath: diffPath
-  };
-}
-function ensureBaselineDir(configDir) {
-  const baselineDir = import_node_path8.default.join(configDir, "baselines");
-  import_node_fs8.default.mkdirSync(baselineDir, { recursive: true });
-  return baselineDir;
-}
-var import_node_fs8, import_node_path8, import_pngjs, import_pixelmatch;
-var init_visual = __esm({
-  "src/runner/visual.ts"() {
-    "use strict";
-    import_node_fs8 = __toESM(require("fs"), 1);
-    import_node_path8 = __toESM(require("path"), 1);
-    import_pngjs = require("pngjs");
-    import_pixelmatch = __toESM(require("pixelmatch"), 1);
-  }
-});
-
-// src/cli/program.ts
-var import_commander13 = require("commander");
-
-// package.json
-var package_default = {
-  name: "prowl-tools",
-  version: "0.1.6",
-  description: "CLI-first QA testing tool for deterministic Playwright flows.",
-  type: "module",
-  license: "Apache-2.0",
-  author: "Prowl Tools",
-  repository: {
-    type: "git",
-    url: "https://github.com/prowl-tools/prowl.git"
-  },
-  homepage: "https://prowl.tools",
-  bugs: {
-    url: "https://github.com/prowl-tools/prowl/issues"
-  },
-  keywords: [
-    "testing",
-    "qa",
-    "playwright",
-    "yaml",
-    "e2e",
-    "browser-testing",
-    "automation",
-    "web-testing",
-    "cli"
-  ],
-  main: "dist/lib.cjs",
-  module: "dist/lib.js",
-  types: "dist/lib.d.ts",
-  exports: {
-    ".": {
-      import: {
-        types: "./dist/lib.d.ts",
-        default: "./dist/lib.js"
-      },
-      require: {
-        types: "./dist/lib.d.cts",
-        default: "./dist/lib.cjs"
+  if ("waitForUrl" in step) {
+    const valueResult = interpolateString(step.waitForUrl.value, vars);
+    return {
+      waitForUrl: {
+        value: valueResult.value,
+        timeout: step.waitForUrl.timeout
       }
-    }
-  },
-  bin: {
-    prowl: "dist/index.js"
-  },
-  files: [
-    "dist",
-    "examples",
-    "LICENSE",
-    "README.md",
-    "NOTICE"
-  ],
-  engines: {
-    node: ">=20.0.0"
-  },
-  scripts: {
-    build: "tsup",
-    lint: "eslint .",
-    test: "vitest run",
-    "test:watch": "vitest"
-  },
-  dependencies: {
-    "@modelcontextprotocol/sdk": "^1.29.0",
-    chalk: "^5.3.0",
-    commander: "^12.1.0",
-    dotenv: "^16.6.1",
-    ora: "^8.1.1",
-    pixelmatch: "^7.1.0",
-    playwright: "^1.50.1",
-    pngjs: "^7.0.0",
-    yaml: "^2.6.1",
-    zod: "^3.23.8"
-  },
-  optionalDependencies: {
-    "appium-uiautomator2-server": "10.6.2",
-    "appium-webdriveragent": "16.4.0"
-  },
-  devDependencies: {
-    "@types/node": "^22.13.1",
-    "@types/pngjs": "^6.0.5",
-    "@typescript-eslint/eslint-plugin": "^7.18.0",
-    "@typescript-eslint/parser": "^7.18.0",
-    eslint: "^8.57.1",
-    tsup: "^8.3.5",
-    typescript: "^5.7.3",
-    vitest: "^2.1.8"
+    };
   }
-};
-
-// src/cli/commands/run.ts
-var import_commander = require("commander");
-var import_chalk3 = __toESM(require("chalk"), 1);
-
-// src/runner/index.ts
-var import_node_fs14 = __toESM(require("fs"), 1);
-var import_node_path14 = __toESM(require("path"), 1);
-init_loader();
-
-// src/config/interpolate.ts
-var import_node_crypto = __toESM(require("crypto"), 1);
-var VAR_PATTERN = /\{\{([A-Z0-9_]+)\}\}/g;
-function collectInterpolatedValues(input, vars, values) {
-  if (typeof input === "string") {
-    for (const match of input.matchAll(VAR_PATTERN)) {
-      const varValue = vars[match[1]];
-      if (varValue) values.add(varValue);
-    }
-    return;
+  if ("waitForNetworkIdle" in step) {
+    return { waitForNetworkIdle: { timeout: step.waitForNetworkIdle.timeout } };
   }
-  if (Array.isArray(input)) {
-    for (const item of input) {
-      collectInterpolatedValues(item, vars, values);
-    }
-    return;
+  if ("hover" in step) {
+    const selectorResult = interpolateString(step.hover.selector, vars);
+    return { hover: { selector: selectorResult.value } };
   }
-  if (input && typeof input === "object") {
-    for (const [key, value] of Object.entries(input)) {
-      collectInterpolatedValues(key, vars, values);
-      collectInterpolatedValues(value, vars, values);
-    }
+  if ("scroll" in step) {
+    return { scroll: { direction: step.scroll.direction, amount: step.scroll.amount } };
   }
-}
-function interpolateString(input, vars) {
-  const usedVars = [];
-  const value = input.replace(VAR_PATTERN, (_, name) => {
-    const varValue = vars[name];
-    if (varValue === void 0) {
-      throw new Error(`Missing variable: ${name}`);
-    }
-    usedVars.push(name);
-    return varValue;
-  });
-  return { value, usedVars };
-}
-var RANDOM_FIRST_NAMES = ["Alex", "Jordan", "Morgan", "Taylor", "Casey", "Riley", "Quinn", "Avery"];
-var RANDOM_LAST_NAMES = ["Smith", "Johnson", "Brown", "Davis", "Wilson", "Clark", "Hall", "Young"];
-function generateRandomVars(randomSource) {
-  const random = randomSource?.random ?? Math.random;
-  const randomBytes = randomSource?.randomBytes ?? import_node_crypto.default.randomBytes;
-  const randomUUID = randomSource?.randomUUID ?? import_node_crypto.default.randomUUID;
-  const hex = randomBytes(4).toString("hex");
-  const firstIndex = Math.floor(random() * RANDOM_FIRST_NAMES.length);
-  const lastIndex = Math.floor(random() * RANDOM_LAST_NAMES.length);
-  const num2 = Math.floor(random() * 9e3) + 1e3;
-  const chars = "abcdefghijklmnopqrstuvwxyz0123456789";
-  let text = "";
-  for (let i = 0; i < 8; i++) {
-    text += chars[Math.floor(random() * chars.length)];
+  if ("scrollTo" in step) {
+    const selectorResult = interpolateString(step.scrollTo.selector, vars);
+    return { scrollTo: { selector: selectorResult.value } };
   }
-  return {
-    RANDOM_EMAIL: `prowl_${hex}@test.com`,
-    RANDOM_NAME: `${RANDOM_FIRST_NAMES[firstIndex]} ${RANDOM_LAST_NAMES[lastIndex]}`,
-    RANDOM_NUMBER: String(num2),
-    RANDOM_UUID: randomUUID(),
-    RANDOM_TEXT: text
-  };
-}
-function interpolateStep(step, vars, stepPath2, redacted) {
-  const isExplicitFill = (value) => typeof value.selector === "string" && typeof value.value === "string";
-  const interpolateSinglePair = (record) => {
-    const entries = Object.entries(record);
-    if (entries.length !== 1) {
-      throw new Error("Shorthand step expects exactly one key-value pair");
-    }
-    const [key, value] = entries[0];
+  if ("screenshot" in step) {
+    return { screenshot: { name: step.screenshot.name } };
+  }
+  if ("if" in step) {
+    const condition = step.if;
+    const thenSteps = condition.then.map(
+      (s, i) => interpolateStep(s, vars, `${stepPath2}.if.then.${i}`, redacted)
+    );
+    const elseSteps = condition.else?.map(
+      (s, i) => interpolateStep(s, vars, `${stepPath2}.if.else.${i}`, redacted)
+    );
     return {
-      [interpolateString(key, vars).value]: interpolateString(value, vars).value
+      if: {
+        ...condition.visible !== void 0 ? { visible: interpolateString(condition.visible, vars).value } : {},
+        ...condition.notVisible !== void 0 ? { notVisible: interpolateString(condition.notVisible, vars).value } : {},
+        then: thenSteps,
+        ...elseSteps !== void 0 ? { else: elseSteps } : {}
+      }
     };
-  };
-  if ("navigate" in step) {
-    const result = interpolateString(step.navigate, vars);
-    return { navigate: result.value };
   }
-  if ("click" in step) {
-    if (typeof step.click === "string") {
-      return { click: interpolateString(step.click, vars).value };
-    }
-    const result = interpolateString(step.click.selector, vars);
-    return { click: { selector: result.value } };
+  if ("repeat" in step) {
+    const repeat = step.repeat;
+    const subSteps = repeat.steps.map(
+      (s, i) => interpolateStep(s, vars, `${stepPath2}.repeat.steps.${i}`, redacted)
+    );
+    return {
+      repeat: {
+        ...repeat.times !== void 0 ? { times: repeat.times } : {},
+        ...repeat.while !== void 0 ? {
+          while: {
+            ...repeat.while.visible !== void 0 ? { visible: interpolateString(repeat.while.visible, vars).value } : {},
+            ...repeat.while.notVisible !== void 0 ? { notVisible: interpolateString(repeat.while.notVisible, vars).value } : {}
+          }
+        } : {},
+        ...repeat.maxIterations !== void 0 ? { maxIterations: repeat.maxIterations } : {},
+        steps: subSteps
+      }
+    };
   }
-  if ("fill" in step) {
-    if (isExplicitFill(step.fill)) {
-      const selectorResult = interpolateString(step.fill.selector, vars);
-      const valueResult2 = interpolateString(step.fill.value, vars);
-      if (valueResult2.usedVars.length > 0) {
-        redacted.add(stepPath2);
+  if ("mockRoute" in step) {
+    const mock = step.mockRoute;
+    return {
+      mockRoute: {
+        url: interpolateString(mock.url, vars).value,
+        response: {
+          status: mock.response.status,
+          ...mock.response.contentType !== void 0 ? { contentType: interpolateString(mock.response.contentType, vars).value } : {},
+          ...mock.response.body !== void 0 ? { body: interpolateString(mock.response.body, vars).value } : {},
+          ...mock.response.file !== void 0 ? { file: interpolateString(mock.response.file, vars).value } : {}
+        }
       }
-      return { fill: { selector: selectorResult.value, value: valueResult2.value } };
-    }
-    const [rawLabel, rawValue] = Object.entries(step.fill)[0] ?? [];
-    if (rawLabel === void 0 || rawValue === void 0) {
-      throw new Error("Shorthand fill expects exactly one key-value pair");
+    };
+  }
+  if ("unmockRoute" in step) {
+    if (typeof step.unmockRoute === "string") {
+      return { unmockRoute: interpolateString(step.unmockRoute, vars).value };
     }
-    const labelResult = interpolateString(rawLabel, vars);
-    const valueResult = interpolateString(rawValue, vars);
-    if (valueResult.usedVars.length > 0) {
-      redacted.add(stepPath2);
+    return {
+      unmockRoute: { url: interpolateString(step.unmockRoute.url, vars).value }
+    };
+  }
+  if ("evalScript" in step) {
+    if (typeof step.evalScript === "string") {
+      return { evalScript: interpolateString(step.evalScript, vars).value };
     }
     return {
-      fill: {
-        [labelResult.value]: valueResult.value
+      evalScript: {
+        expression: interpolateString(step.evalScript.expression, vars).value,
+        ...step.evalScript.as !== void 0 ? { as: step.evalScript.as } : {}
       }
     };
   }
-  if ("type" in step) {
-    const valueResult = interpolateString(step.type, vars);
-    if (valueResult.usedVars.length > 0) {
-      redacted.add(stepPath2);
-    }
-    return { type: valueResult.value };
-  }
-  if ("selectOption" in step) {
-    const selectorResult = interpolateString(step.selectOption.selector, vars);
-    const valueResult = interpolateString(step.selectOption.value, vars);
-    return { selectOption: { selector: selectorResult.value, value: valueResult.value } };
-  }
-  if ("select" in step) {
-    return { select: interpolateSinglePair(step.select) };
+  if ("runScript" in step) {
+    return {
+      runScript: { file: interpolateString(step.runScript.file, vars).value }
+    };
   }
-  if ("press" in step) {
-    const selectorResult = interpolateString(step.press.selector, vars);
-    const keyResult = interpolateString(step.press.key, vars);
-    return { press: { selector: selectorResult.value, key: keyResult.value } };
+  if ("assertScreenshot" in step) {
+    return {
+      assertScreenshot: {
+        name: interpolateString(step.assertScreenshot.name, vars).value,
+        ...step.assertScreenshot.threshold !== void 0 ? { threshold: step.assertScreenshot.threshold } : {}
+      }
+    };
   }
-  if ("onDialog" in step) {
-    return { onDialog: { action: step.onDialog.action } };
+  if ("assertWithAI" in step) {
+    return {
+      assertWithAI: interpolateString(step.assertWithAI, vars).value
+    };
   }
-  if ("setInputFiles" in step) {
-    const selectorResult = interpolateString(step.setInputFiles.selector, vars);
-    const rawFiles = step.setInputFiles.files;
-    const files = Array.isArray(rawFiles) ? rawFiles.map((f) => interpolateString(f, vars).value) : interpolateString(rawFiles, vars).value;
-    return { setInputFiles: { selector: selectorResult.value, files } };
+  if ("copyText" in step) {
+    return {
+      copyText: {
+        selector: interpolateString(step.copyText.selector, vars).value,
+        as: step.copyText.as
+      }
+    };
   }
-  if ("runHunt" in step) {
-    if (typeof step.runHunt === "string") {
-      return { runHunt: interpolateString(step.runHunt, vars).value };
-    }
-    const nameResult = interpolateString(step.runHunt.name, vars);
-    const interpolatedVars = {};
-    for (const [key, value] of Object.entries(step.runHunt.vars ?? {})) {
-      interpolatedVars[key] = interpolateString(value, vars).value;
+  if ("waitForDownload" in step) {
+    if (step.waitForDownload === null) {
+      return { waitForDownload: null };
     }
     return {
-      runHunt: {
-        name: nameResult.value,
-        ...Object.keys(interpolatedVars).length > 0 ? { vars: interpolatedVars } : {}
+      waitForDownload: {
+        ...step.waitForDownload.filename !== void 0 ? { filename: interpolateString(step.waitForDownload.filename, vars).value } : {},
+        ...step.waitForDownload.timeout !== void 0 ? { timeout: step.waitForDownload.timeout } : {}
       }
     };
   }
-  if ("assert" in step) {
-    if (step.assert.visible !== void 0) {
-      return { assert: { visible: interpolateString(step.assert.visible, vars).value } };
-    }
-    if (step.assert.notVisible !== void 0) {
-      return { assert: { notVisible: interpolateString(step.assert.notVisible, vars).value } };
-    }
-    if (step.assert.urlIncludes !== void 0) {
-      return { assert: { urlIncludes: interpolateString(step.assert.urlIncludes, vars).value } };
+  return step;
+}
+function interpolateAssertion(assertion, vars) {
+  if ("selectorExists" in assertion) {
+    return { selectorExists: interpolateString(assertion.selectorExists, vars).value };
+  }
+  if ("selectorNotExists" in assertion) {
+    return { selectorNotExists: interpolateString(assertion.selectorNotExists, vars).value };
+  }
+  if ("urlIncludes" in assertion) {
+    return { urlIncludes: interpolateString(assertion.urlIncludes, vars).value };
+  }
+  if ("urlEquals" in assertion) {
+    return { urlEquals: interpolateString(assertion.urlEquals, vars).value };
+  }
+  if ("noConsoleErrors" in assertion) {
+    return { noConsoleErrors: assertion.noConsoleErrors };
+  }
+  if ("noNetworkErrors" in assertion) {
+    return { noNetworkErrors: assertion.noNetworkErrors };
+  }
+  return assertion;
+}
+function interpolateHunt(hunt, env, randomVars = generateRandomVars()) {
+  const redactedFillSteps = /* @__PURE__ */ new Set();
+  const envVars = Object.fromEntries(
+    Object.entries(env).filter(([, value]) => value !== void 0)
+  );
+  const baseVars = { ...randomVars, ...envVars };
+  const resolvedHuntVars = {};
+  for (const [key, value] of Object.entries(hunt.vars ?? {})) {
+    resolvedHuntVars[key] = interpolateString(value, baseVars).value;
+  }
+  const vars = { ...baseVars, ...resolvedHuntVars };
+  const redactionValues = /* @__PURE__ */ new Set();
+  collectInterpolatedValues(hunt.steps, vars, redactionValues);
+  collectInterpolatedValues(hunt.assertions, vars, redactionValues);
+  const steps = hunt.steps.map(
+    (step, index) => interpolateStep(step, vars, `${index}`, redactedFillSteps)
+  );
+  const assertions = hunt.assertions?.map((assertion) => interpolateAssertion(assertion, vars));
+  return {
+    hunt: {
+      ...hunt,
+      steps,
+      assertions
+    },
+    redactedFillSteps,
+    randomVars,
+    redactionValues: [...redactionValues]
+  };
+}
+var import_node_crypto, VAR_PATTERN, RANDOM_FIRST_NAMES, RANDOM_LAST_NAMES;
+var init_interpolate = __esm({
+  "src/config/interpolate.ts"() {
+    "use strict";
+    import_node_crypto = __toESM(require("crypto"), 1);
+    VAR_PATTERN = /\{\{([A-Z0-9_]+)\}\}/g;
+    RANDOM_FIRST_NAMES = ["Alex", "Jordan", "Morgan", "Taylor", "Casey", "Riley", "Quinn", "Avery"];
+    RANDOM_LAST_NAMES = ["Smith", "Johnson", "Brown", "Davis", "Wilson", "Clark", "Hall", "Young"];
+  }
+});
+
+// src/config/loader.ts
+var loader_exports = {};
+__export(loader_exports, {
+  CONFIG_DIR: () => CONFIG_DIR,
+  LEGACY_CONFIG_DIR: () => LEGACY_CONFIG_DIR,
+  ensureAllowedDomain: () => ensureAllowedDomain,
+  findConfigPath: () => findConfigPath,
+  listHunts: () => listHunts,
+  loadConfig: () => loadConfig,
+  loadHunt: () => loadHunt,
+  loadHuntMeta: () => loadHuntMeta,
+  loadHuntTags: () => loadHuntTags,
+  resolveViewport: () => resolveViewport,
+  warnLegacyConfigDir: () => warnLegacyConfigDir
+});
+function warnLegacyConfigDir() {
+  if (legacyDirWarned) {
+    return;
+  }
+  legacyDirWarned = true;
+  console.warn(
+    'Warning: the ".prowlqa/" config directory is deprecated; rename it to ".prowl/". Support for ".prowlqa/" will be removed in a future release.'
+  );
+}
+function findConfigPath(startDir) {
+  let current = startDir;
+  while (current) {
+    for (const dir of [CONFIG_DIR, LEGACY_CONFIG_DIR]) {
+      const candidate = import_node_path.default.join(current, dir, "config.yml");
+      if (import_node_fs.default.existsSync(candidate)) {
+        return candidate;
+      }
     }
-    if (step.assert.urlEquals !== void 0) {
-      return { assert: { urlEquals: interpolateString(step.assert.urlEquals, vars).value } };
+    const parent = import_node_path.default.dirname(current);
+    if (parent === current) {
+      break;
     }
-    return step;
+    current = parent;
   }
-  if ("wait" in step) {
-    if (typeof step.wait === "string") {
-      return { wait: interpolateString(step.wait, vars).value };
+  return null;
+}
+function resolveViewport(value) {
+  if (value === void 0) {
+    return DEFAULT_CONFIG.browser.viewport;
+  }
+  if (typeof value === "string") {
+    const preset = VIEWPORT_PRESETS[value];
+    if (!preset) {
+      throw new Error(`Unknown viewport preset: "${value}". Use mobile, tablet, or desktop.`);
     }
+    return preset;
+  }
+  return value;
+}
+function resolveTarget(target) {
+  const type = target?.type;
+  if (type === "macos") {
+    return { type: "macos", app: target.app };
+  }
+  if (type === "android") {
+    const androidTarget = target;
     return {
-      wait: {
-        for: interpolateString(step.wait.for, vars).value,
-        timeout: step.wait.timeout
-      }
+      type: "android",
+      app: androidTarget.app,
+      ...androidTarget.deviceSerial !== void 0 ? { deviceSerial: androidTarget.deviceSerial } : {},
+      ...androidTarget.coldStart !== void 0 ? { coldStart: androidTarget.coldStart } : {}
     };
   }
-  if ("waitForSelector" in step) {
-    const selectorResult = interpolateString(step.waitForSelector.selector, vars);
+  if (type === "ios") {
+    const iosTarget = target;
     return {
-      waitForSelector: {
-        selector: selectorResult.value,
-        timeout: step.waitForSelector.timeout
-      }
+      type: "ios",
+      app: iosTarget.app,
+      ...iosTarget.udid !== void 0 ? { udid: iosTarget.udid } : {},
+      ...iosTarget.coldStart !== void 0 ? { coldStart: iosTarget.coldStart } : {}
     };
   }
-  if ("waitForUrl" in step) {
-    const valueResult = interpolateString(step.waitForUrl.value, vars);
-    return {
-      waitForUrl: {
-        value: valueResult.value,
-        timeout: step.waitForUrl.timeout
-      }
-    };
+  return {
+    type: "web",
+    url: target?.url ?? DEFAULT_WEB_URL
+  };
+}
+function mergeConfig(partial) {
+  return {
+    target: resolveTarget(partial.target),
+    browser: {
+      headless: partial.browser?.headless ?? DEFAULT_CONFIG.browser.headless,
+      slowMo: partial.browser?.slowMo ?? DEFAULT_CONFIG.browser.slowMo,
+      timeout: partial.browser?.timeout ?? DEFAULT_CONFIG.browser.timeout,
+      engine: partial.browser?.engine ?? DEFAULT_CONFIG.browser.engine,
+      channel: partial.browser?.channel,
+      viewport: resolveViewport(partial.browser?.viewport)
+    },
+    artifacts: {
+      screenshots: partial.artifacts?.screenshots ?? DEFAULT_CONFIG.artifacts.screenshots,
+      networkHar: partial.artifacts?.networkHar ?? DEFAULT_CONFIG.artifacts.networkHar,
+      console: partial.artifacts?.console ?? DEFAULT_CONFIG.artifacts.console,
+      junit: partial.artifacts?.junit ?? DEFAULT_CONFIG.artifacts.junit
+    },
+    assertions: {
+      noConsoleErrors: partial.assertions?.noConsoleErrors ?? DEFAULT_CONFIG.assertions.noConsoleErrors,
+      noNetworkErrors: partial.assertions?.noNetworkErrors ?? DEFAULT_CONFIG.assertions.noNetworkErrors,
+      maxTotalTimeMs: partial.assertions?.maxTotalTimeMs ?? DEFAULT_CONFIG.assertions.maxTotalTimeMs,
+      networkIgnorePatterns: partial.assertions?.networkIgnorePatterns ?? DEFAULT_CONFIG.assertions.networkIgnorePatterns
+    },
+    guardrails: {
+      maxSteps: partial.guardrails?.maxSteps ?? DEFAULT_CONFIG.guardrails.maxSteps,
+      allowedDomains: partial.guardrails?.allowedDomains ?? DEFAULT_CONFIG.guardrails.allowedDomains,
+      allowedApps: partial.guardrails?.allowedApps ?? DEFAULT_CONFIG.guardrails.allowedApps,
+      forbiddenSelectors: partial.guardrails?.forbiddenSelectors ?? DEFAULT_CONFIG.guardrails.forbiddenSelectors,
+      selfHealing: partial.guardrails?.selfHealing ?? DEFAULT_CONFIG.guardrails.selfHealing
+    },
+    auth: {
+      storageStatePath: partial.auth?.storageStatePath ?? (partial.auth !== void 0 ? DEFAULT_CONFIG.auth.storageStatePath : void 0)
+    },
+    history: {
+      maxRuns: partial.history?.maxRuns ?? DEFAULT_CONFIG.history.maxRuns
+    },
+    bugLog: partial.bugLog,
+    tracing: partial.tracing,
+    reliability: partial.reliability
+  };
+}
+function envStringVars(env) {
+  return Object.fromEntries(
+    Object.entries(env).filter(([, value]) => value !== void 0)
+  );
+}
+function interpolateConfigStrings(value, vars) {
+  if (typeof value === "string") {
+    return interpolateString(value, vars).value;
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => interpolateConfigStrings(item, vars));
   }
-  if ("waitForNetworkIdle" in step) {
-    return { waitForNetworkIdle: { timeout: step.waitForNetworkIdle.timeout } };
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, item]) => [key, interpolateConfigStrings(item, vars)])
+    );
   }
-  if ("hover" in step) {
-    const selectorResult = interpolateString(step.hover.selector, vars);
-    return { hover: { selector: selectorResult.value } };
+  return value;
+}
+function ensureAllowedDomain(allowed, urlValue) {
+  try {
+    const host = new URL(urlValue).hostname;
+    if (!allowed.includes(host)) {
+      return [...allowed, host];
+    }
+  } catch {
+    return allowed;
   }
-  if ("scroll" in step) {
-    return { scroll: { direction: step.scroll.direction, amount: step.scroll.amount } };
+  return allowed;
+}
+function loadConfig(configPath) {
+  const resolvedPath = configPath ? import_node_path.default.resolve(configPath) : findConfigPath(process.cwd());
+  if (!resolvedPath) {
+    throw new Error("Could not find .prowl/config.yml. Run `prowl init` first.");
   }
-  if ("scrollTo" in step) {
-    const selectorResult = interpolateString(step.scrollTo.selector, vars);
-    return { scrollTo: { selector: selectorResult.value } };
+  if (!import_node_fs.default.existsSync(resolvedPath)) {
+    throw new Error(`Config file not found at ${resolvedPath}`);
   }
-  if ("screenshot" in step) {
-    return { screenshot: { name: step.screenshot.name } };
+  const configDir = import_node_path.default.dirname(resolvedPath);
+  if (import_node_path.default.basename(configDir) === LEGACY_CONFIG_DIR) {
+    warnLegacyConfigDir();
   }
-  if ("if" in step) {
-    const condition = step.if;
-    const thenSteps = condition.then.map(
-      (s, i) => interpolateStep(s, vars, `${stepPath2}.if.then.${i}`, redacted)
-    );
-    const elseSteps = condition.else?.map(
-      (s, i) => interpolateStep(s, vars, `${stepPath2}.if.else.${i}`, redacted)
+  import_dotenv.default.config({ path: import_node_path.default.join(configDir, ".env"), override: false });
+  const raw = import_node_fs.default.readFileSync(resolvedPath, "utf-8");
+  const parsed = import_yaml.default.parse(raw) ?? {};
+  const interpolated = interpolateConfigStrings(parsed, envStringVars(process.env));
+  const validated = configSchema.parse(interpolated);
+  const config = mergeConfig(validated);
+  if (config.target.type === "web") {
+    config.guardrails.allowedDomains = ensureAllowedDomain(
+      config.guardrails.allowedDomains,
+      config.target.url
     );
-    return {
-      if: {
-        ...condition.visible !== void 0 ? { visible: interpolateString(condition.visible, vars).value } : {},
-        ...condition.notVisible !== void 0 ? { notVisible: interpolateString(condition.notVisible, vars).value } : {},
-        then: thenSteps,
-        ...elseSteps !== void 0 ? { else: elseSteps } : {}
-      }
-    };
   }
-  if ("repeat" in step) {
-    const repeat = step.repeat;
-    const subSteps = repeat.steps.map(
-      (s, i) => interpolateStep(s, vars, `${stepPath2}.repeat.steps.${i}`, redacted)
-    );
-    return {
-      repeat: {
-        ...repeat.times !== void 0 ? { times: repeat.times } : {},
-        ...repeat.while !== void 0 ? {
-          while: {
-            ...repeat.while.visible !== void 0 ? { visible: interpolateString(repeat.while.visible, vars).value } : {},
-            ...repeat.while.notVisible !== void 0 ? { notVisible: interpolateString(repeat.while.notVisible, vars).value } : {}
-          }
-        } : {},
-        ...repeat.maxIterations !== void 0 ? { maxIterations: repeat.maxIterations } : {},
-        steps: subSteps
-      }
-    };
+  return { config, configPath: resolvedPath, configDir };
+}
+function loadHunt(huntName, configDir) {
+  assertValidHuntName(huntName);
+  const huntPath = import_node_path.default.join(configDir, "hunts", `${huntName}.yml`);
+  if (!import_node_fs.default.existsSync(huntPath)) {
+    throw new Error(`Hunt file not found: ${huntPath}`);
   }
-  if ("mockRoute" in step) {
-    const mock = step.mockRoute;
-    return {
-      mockRoute: {
-        url: interpolateString(mock.url, vars).value,
-        response: {
-          status: mock.response.status,
-          ...mock.response.contentType !== void 0 ? { contentType: interpolateString(mock.response.contentType, vars).value } : {},
-          ...mock.response.body !== void 0 ? { body: interpolateString(mock.response.body, vars).value } : {},
-          ...mock.response.file !== void 0 ? { file: interpolateString(mock.response.file, vars).value } : {}
-        }
-      }
-    };
+  const raw = import_node_fs.default.readFileSync(huntPath, "utf-8");
+  const parsed = import_yaml.default.parse(raw) ?? {};
+  const validated = huntSchema.parse(parsed);
+  return validated;
+}
+function loadHuntTags(huntName, configDir) {
+  assertValidHuntName(huntName);
+  const huntPath = import_node_path.default.join(configDir, "hunts", `${huntName}.yml`);
+  if (!import_node_fs.default.existsSync(huntPath)) {
+    return [];
   }
-  if ("unmockRoute" in step) {
-    if (typeof step.unmockRoute === "string") {
-      return { unmockRoute: interpolateString(step.unmockRoute, vars).value };
-    }
-    return {
-      unmockRoute: { url: interpolateString(step.unmockRoute.url, vars).value }
-    };
+  const raw = import_node_fs.default.readFileSync(huntPath, "utf-8");
+  const parsed = import_yaml.default.parse(raw) ?? {};
+  return Array.isArray(parsed.tags) ? parsed.tags : [];
+}
+function loadHuntMeta(huntName, configDir) {
+  assertValidHuntName(huntName);
+  const huntPath = import_node_path.default.join(configDir, "hunts", `${huntName}.yml`);
+  if (!import_node_fs.default.existsSync(huntPath)) {
+    return { tags: [] };
   }
-  if ("evalScript" in step) {
-    if (typeof step.evalScript === "string") {
-      return { evalScript: interpolateString(step.evalScript, vars).value };
-    }
-    return {
-      evalScript: {
-        expression: interpolateString(step.evalScript.expression, vars).value,
-        ...step.evalScript.as !== void 0 ? { as: step.evalScript.as } : {}
-      }
-    };
+  const raw = import_node_fs.default.readFileSync(huntPath, "utf-8");
+  const parsed = import_yaml.default.parse(raw) ?? {};
+  return {
+    description: typeof parsed.description === "string" ? parsed.description : void 0,
+    tags: Array.isArray(parsed.tags) ? parsed.tags : []
+  };
+}
+function listHunts(configDir) {
+  const huntsDir = import_node_path.default.join(configDir, "hunts");
+  if (!import_node_fs.default.existsSync(huntsDir)) {
+    return [];
   }
-  if ("runScript" in step) {
-    return {
-      runScript: { file: interpolateString(step.runScript.file, vars).value }
-    };
+  const stats = import_node_fs.default.statSync(huntsDir);
+  if (!stats.isDirectory()) {
+    throw new Error(`Hunts path is not a directory: ${huntsDir}`);
   }
-  if ("assertScreenshot" in step) {
-    return {
-      assertScreenshot: {
-        name: interpolateString(step.assertScreenshot.name, vars).value,
-        ...step.assertScreenshot.threshold !== void 0 ? { threshold: step.assertScreenshot.threshold } : {}
+  const results = [];
+  function scanDir(dir) {
+    const entries = import_node_fs.default.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isFile() && entry.name.endsWith(".yml")) {
+        const fullPath = import_node_path.default.join(dir, entry.name);
+        const relative = import_node_path.default.relative(huntsDir, fullPath);
+        results.push(relative.replace(/\.yml$/, ""));
+      } else if (entry.isDirectory()) {
+        scanDir(import_node_path.default.join(dir, entry.name));
       }
-    };
-  }
-  if ("assertWithAI" in step) {
-    return {
-      assertWithAI: interpolateString(step.assertWithAI, vars).value
-    };
+    }
   }
-  if ("copyText" in step) {
-    return {
-      copyText: {
-        selector: interpolateString(step.copyText.selector, vars).value,
-        as: step.copyText.as
+  scanDir(huntsDir);
+  return results.sort((a, b) => a.localeCompare(b));
+}
+var import_node_fs, import_node_path, import_yaml, import_dotenv, DEFAULT_WEB_URL, DEFAULT_CONFIG, CONFIG_DIR, LEGACY_CONFIG_DIR, legacyDirWarned, VIEWPORT_PRESETS;
+var init_loader = __esm({
+  "src/config/loader.ts"() {
+    "use strict";
+    import_node_fs = __toESM(require("fs"), 1);
+    import_node_path = __toESM(require("path"), 1);
+    import_yaml = __toESM(require("yaml"), 1);
+    import_dotenv = __toESM(require("dotenv"), 1);
+    init_schema();
+    init_hunt_name();
+    init_interpolate();
+    DEFAULT_WEB_URL = "http://localhost:3000";
+    DEFAULT_CONFIG = {
+      target: {
+        type: "web",
+        url: DEFAULT_WEB_URL
+      },
+      browser: {
+        headless: true,
+        slowMo: 0,
+        timeout: 3e4,
+        engine: "chromium",
+        viewport: { width: 1280, height: 720 }
+      },
+      artifacts: {
+        screenshots: "on-failure",
+        networkHar: false,
+        console: true,
+        junit: false
+      },
+      assertions: {
+        noConsoleErrors: true,
+        noNetworkErrors: true,
+        maxTotalTimeMs: 3e4,
+        networkIgnorePatterns: []
+      },
+      guardrails: {
+        maxSteps: 50,
+        allowedDomains: ["localhost", "127.0.0.1", "0.0.0.0"],
+        allowedApps: [],
+        forbiddenSelectors: ["[data-danger]", ".delete-btn"],
+        selfHealing: false
+      },
+      auth: {
+        storageStatePath: ".prowl/auth-state.json"
+      },
+      history: {
+        maxRuns: 100
       }
     };
+    CONFIG_DIR = ".prowl";
+    LEGACY_CONFIG_DIR = ".prowlqa";
+    legacyDirWarned = false;
+    VIEWPORT_PRESETS = {
+      mobile: { width: 375, height: 812 },
+      tablet: { width: 768, height: 1024 },
+      desktop: { width: 1280, height: 720 }
+    };
   }
-  if ("waitForDownload" in step) {
-    if (step.waitForDownload === null) {
-      return { waitForDownload: null };
-    }
+});
+
+// src/runner/visual.ts
+var visual_exports = {};
+__export(visual_exports, {
+  compareScreenshots: () => compareScreenshots,
+  ensureBaselineDir: () => ensureBaselineDir
+});
+async function compareScreenshots(baselinePath, currentPath, diffPath, threshold) {
+  const baselineData = import_pngjs.PNG.sync.read(import_node_fs8.default.readFileSync(baselinePath));
+  const currentData = import_pngjs.PNG.sync.read(import_node_fs8.default.readFileSync(currentPath));
+  const { width, height } = baselineData;
+  if (currentData.width !== width || currentData.height !== height) {
+    const diff2 = new import_pngjs.PNG({ width, height });
+    import_node_fs8.default.writeFileSync(diffPath, import_pngjs.PNG.sync.write(diff2));
     return {
-      waitForDownload: {
-        ...step.waitForDownload.filename !== void 0 ? { filename: interpolateString(step.waitForDownload.filename, vars).value } : {},
-        ...step.waitForDownload.timeout !== void 0 ? { timeout: step.waitForDownload.timeout } : {}
-      }
+      match: false,
+      diffPercentage: 1,
+      diffImagePath: diffPath
     };
   }
-  return step;
-}
-function interpolateAssertion(assertion, vars) {
-  if ("selectorExists" in assertion) {
-    return { selectorExists: interpolateString(assertion.selectorExists, vars).value };
-  }
-  if ("selectorNotExists" in assertion) {
-    return { selectorNotExists: interpolateString(assertion.selectorNotExists, vars).value };
-  }
-  if ("urlIncludes" in assertion) {
-    return { urlIncludes: interpolateString(assertion.urlIncludes, vars).value };
-  }
-  if ("urlEquals" in assertion) {
-    return { urlEquals: interpolateString(assertion.urlEquals, vars).value };
-  }
-  if ("noConsoleErrors" in assertion) {
-    return { noConsoleErrors: assertion.noConsoleErrors };
-  }
-  if ("noNetworkErrors" in assertion) {
-    return { noNetworkErrors: assertion.noNetworkErrors };
-  }
-  return assertion;
-}
-function interpolateHunt(hunt, env, randomVars = generateRandomVars()) {
-  const redactedFillSteps = /* @__PURE__ */ new Set();
-  const envVars = Object.fromEntries(
-    Object.entries(env).filter(([, value]) => value !== void 0)
-  );
-  const baseVars = { ...randomVars, ...envVars };
-  const resolvedHuntVars = {};
-  for (const [key, value] of Object.entries(hunt.vars ?? {})) {
-    resolvedHuntVars[key] = interpolateString(value, baseVars).value;
-  }
-  const vars = { ...baseVars, ...resolvedHuntVars };
-  const redactionValues = /* @__PURE__ */ new Set();
-  collectInterpolatedValues(hunt.steps, vars, redactionValues);
-  collectInterpolatedValues(hunt.assertions, vars, redactionValues);
-  const steps = hunt.steps.map(
-    (step, index) => interpolateStep(step, vars, `${index}`, redactedFillSteps)
+  const diff = new import_pngjs.PNG({ width, height });
+  const diffPixels = (0, import_pixelmatch.default)(
+    baselineData.data,
+    currentData.data,
+    diff.data,
+    width,
+    height,
+    { threshold: 0.1 }
   );
-  const assertions = hunt.assertions?.map((assertion) => interpolateAssertion(assertion, vars));
+  const totalPixels = width * height;
+  const diffPercentage = diffPixels / totalPixels;
+  import_node_fs8.default.writeFileSync(diffPath, import_pngjs.PNG.sync.write(diff));
   return {
-    hunt: {
-      ...hunt,
-      steps,
-      assertions
-    },
-    redactedFillSteps,
-    randomVars,
-    redactionValues: [...redactionValues]
+    match: diffPercentage <= threshold,
+    diffPercentage,
+    diffImagePath: diffPath
   };
 }
+function ensureBaselineDir(configDir) {
+  const baselineDir = import_node_path9.default.join(configDir, "baselines");
+  import_node_fs8.default.mkdirSync(baselineDir, { recursive: true });
+  return baselineDir;
+}
+var import_node_fs8, import_node_path9, import_pngjs, import_pixelmatch;
+var init_visual = __esm({
+  "src/runner/visual.ts"() {
+    "use strict";
+    import_node_fs8 = __toESM(require("fs"), 1);
+    import_node_path9 = __toESM(require("path"), 1);
+    import_pngjs = require("pngjs");
+    import_pixelmatch = __toESM(require("pixelmatch"), 1);
+  }
+});
+
+// src/cli/program.ts
+var import_commander14 = require("commander");
+
+// package.json
+var package_default = {
+  name: "prowl-tools",
+  version: "0.1.8",
+  description: "E2E testing for native macOS apps and web apps from declarative YAML hunts.",
+  type: "module",
+  license: "Apache-2.0",
+  author: "Prowl Tools",
+  repository: {
+    type: "git",
+    url: "https://github.com/prowl-tools/prowl.git"
+  },
+  homepage: "https://prowl.tools",
+  bugs: {
+    url: "https://github.com/prowl-tools/prowl/issues"
+  },
+  keywords: [
+    "testing",
+    "qa",
+    "e2e",
+    "macos",
+    "desktop-testing",
+    "accessibility",
+    "playwright",
+    "yaml",
+    "browser-testing",
+    "automation",
+    "web-testing",
+    "cli"
+  ],
+  main: "dist/lib.cjs",
+  module: "dist/lib.js",
+  types: "dist/lib.d.ts",
+  exports: {
+    ".": {
+      import: {
+        types: "./dist/lib.d.ts",
+        default: "./dist/lib.js"
+      },
+      require: {
+        types: "./dist/lib.d.cts",
+        default: "./dist/lib.cjs"
+      }
+    }
+  },
+  bin: {
+    prowl: "dist/index.js"
+  },
+  files: [
+    "dist",
+    "examples",
+    "LICENSE",
+    "README.md",
+    "NOTICE"
+  ],
+  engines: {
+    node: ">=20.0.0"
+  },
+  scripts: {
+    build: "tsup",
+    lint: "eslint .",
+    test: "vitest run",
+    "test:watch": "vitest"
+  },
+  dependencies: {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    chalk: "^5.3.0",
+    commander: "^12.1.0",
+    dotenv: "^16.6.1",
+    ora: "^8.1.1",
+    pixelmatch: "^7.1.0",
+    playwright: "^1.50.1",
+    pngjs: "^7.0.0",
+    yaml: "^2.6.1",
+    zod: "^3.23.8"
+  },
+  optionalDependencies: {
+    "appium-uiautomator2-server": "10.6.2",
+    "appium-webdriveragent": "16.4.0"
+  },
+  devDependencies: {
+    "@types/node": "^22.13.1",
+    "@types/pngjs": "^6.0.5",
+    "@typescript-eslint/eslint-plugin": "^7.18.0",
+    "@typescript-eslint/parser": "^7.18.0",
+    eslint: "^8.57.1",
+    tsup: "^8.3.5",
+    typescript: "^5.7.3",
+    vitest: "^2.1.8"
+  }
+};
+
+// src/cli/commands/run.ts
+var import_commander = require("commander");
+var import_chalk3 = __toESM(require("chalk"), 1);
+
+// src/runner/index.ts
+var import_node_fs14 = __toESM(require("fs"), 1);
+var import_node_path15 = __toESM(require("path"), 1);
+init_loader();
+init_interpolate();
 
 // src/config/target.ts
 var import_node_child_process = require("child_process");
@@ -1202,10 +1248,17 @@ var WEB_ONLY_STEP_TYPES = /* @__PURE__ */ new Set([
   "select",
   "selectOption",
   "setInputFiles",
-  "waitForDownload",
-  "scroll"
-  // directional scroll runs window.scrollBy (evaluate) — use scrollTo instead
+  "waitForDownload"
 ]);
+var MACOS_UNSUPPORTED_STEP_TYPES = /* @__PURE__ */ new Set(["scroll"]);
+function macosUnsupportedReason(step) {
+  for (const type of MACOS_UNSUPPORTED_STEP_TYPES) {
+    if (type in step) {
+      return type;
+    }
+  }
+  return null;
+}
 function webOnlyReason(step) {
   for (const type of WEB_ONLY_STEP_TYPES) {
     if (type in step) {
@@ -1241,6 +1294,14 @@ function assertStepsSupportedByTarget(steps, target) {
         `Step "${reason}" is not supported by the ${label} target. It is web-only; use a portable step (click, fill, type, press, wait, assert visible, screenshot, etc.).`
       );
     }
+    if (target === "macos") {
+      const macReason = macosUnsupportedReason(step);
+      if (macReason) {
+        throw new Error(
+          `Step "${macReason}" is not supported by the macOS target. Directional scroll is a touch swipe available on the iOS and Android targets; there is no macOS accessibility equivalent (use scrollTo to bring a specific element into view instead).`
+        );
+      }
+    }
     if ("if" in step) {
       assertStepsSupportedByTarget(step.if.then, target);
       if (step.if.else) {
@@ -1524,6 +1585,16 @@ function createPlaywrightDriver(page) {
     async hover(selector) {
       await page.locator(selector).hover();
     },
+    async scroll(direction, amount = 500) {
+      const deltas = {
+        up: [0, -amount],
+        down: [0, amount],
+        left: [-amount, 0],
+        right: [amount, 0]
+      };
+      const [x, y] = deltas[direction];
+      await page.evaluate(([sx, sy]) => window.scrollBy(sx, sy), [x, y]);
+    },
     async scrollIntoView(selector) {
       await page.locator(selector).scrollIntoViewIfNeeded();
     },
@@ -1606,7 +1677,8 @@ function createPlaywrightDriver(page) {
 // src/browser/mac-helper.ts
 var import_node_child_process2 = require("child_process");
 var import_node_fs4 = __toESM(require("fs"), 1);
-var import_node_path4 = __toESM(require("path"), 1);
+var import_node_os2 = __toESM(require("os"), 1);
+var import_node_path5 = __toESM(require("path"), 1);
 var import_node_url = require("url");
 
 // src/browser/mac-driver.ts
@@ -1717,6 +1789,9 @@ function createMacDriver(client, options = {}) {
     async hover(selector) {
       await query("hover", selector);
     },
+    scroll() {
+      return rejectUnsupported("scroll");
+    },
     async scrollIntoView(selector) {
       await query("scrollTo", selector);
     },
@@ -1785,24 +1860,67 @@ function createMacDriver(client, options = {}) {
   };
 }
 
+// src/browser/macdriver-release.ts
+var import_node_os = __toESM(require("os"), 1);
+var import_node_path4 = __toESM(require("path"), 1);
+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 = import_node_os.default.homedir()) {
+  return import_node_path4.default.join(homedir, ".prowl", "macdriver");
+}
+function macdriverVersionDir(version = MACDRIVER_VERSION, homedir = import_node_os.default.homedir()) {
+  const root = import_node_path4.default.resolve(macdriverInstallRoot(homedir));
+  const versionDir = import_node_path4.default.resolve(root, validateMacdriverVersion(version));
+  if (!versionDir.startsWith(root + import_node_path4.default.sep)) {
+    throw new Error(`Resolved prowl-macdriver version directory escaped install root: ${versionDir}`);
+  }
+  return versionDir;
+}
+function macdriverInstalledBinary(version = MACDRIVER_VERSION, homedir = import_node_os.default.homedir()) {
+  return import_node_path4.default.join(macdriverVersionDir(version, homedir), HELPER_BINARY);
+}
+
 // src/browser/mac-helper.ts
 var import_meta = {};
-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 = import_node_path4.default.dirname((0, import_node_url.fileURLToPath)(import_meta.url));
-  const root = import_node_path4.default.parse(dir).root;
+  let dir = import_node_path5.default.dirname((0, import_node_url.fileURLToPath)(import_meta.url));
+  const root = import_node_path5.default.parse(dir).root;
   while (dir !== root) {
-    if (import_node_fs4.default.existsSync(import_node_path4.default.join(dir, "package.json"))) {
+    if (import_node_fs4.default.existsSync(import_node_path5.default.join(dir, "package.json"))) {
       return dir;
     }
-    dir = import_node_path4.default.dirname(dir);
+    dir = import_node_path5.default.dirname(dir);
   }
   return root;
 }
-function resolveHelperBinary(env = process.env) {
+function resolveHelperBinary(env = process.env, options = {}) {
   const override = env.PROWL_MACDRIVER_BIN;
   if (override) {
     if (!import_node_fs4.default.existsSync(override)) {
@@ -1813,10 +1931,15 @@ ${macdriverBuildInstructions()}`
     }
     return override;
   }
+  const homedir = options.homedir ?? import_node_os2.default.homedir();
+  const userBinary = macdriverInstalledBinary(MACDRIVER_VERSION, homedir);
+  if (import_node_fs4.default.existsSync(userBinary)) {
+    return userBinary;
+  }
   const root = getPackageRoot();
   const candidates = [
-    import_node_path4.default.join(root, "macdriver", ".build", "release", HELPER_BINARY),
-    import_node_path4.default.join(root, "macdriver", ".build", "debug", HELPER_BINARY)
+    import_node_path5.default.join(root, "macdriver", ".build", "release", HELPER_BINARY),
+    import_node_path5.default.join(root, "macdriver", ".build", "debug", HELPER_BINARY)
   ];
   for (const candidate of candidates) {
     if (import_node_fs4.default.existsSync(candidate)) {
@@ -1992,7 +2115,7 @@ async function closeMacSession(session) {
 var import_node_module = require("module");
 var import_node_child_process4 = require("child_process");
 var import_node_fs6 = __toESM(require("fs"), 1);
-var import_node_path5 = __toESM(require("path"), 1);
+var import_node_path6 = __toESM(require("path"), 1);
 
 // src/browser/android-driver.ts
 var import_node_fs5 = __toESM(require("fs"), 1);
@@ -2202,6 +2325,101 @@ function rankNativeSelectors(fields) {
   return selectors;
 }
 
+// src/browser/touch-gestures.ts
+var DEFAULT_SWIPE_FRACTION = 0.75;
+var SCROLL_TO_PROBE_SWIPE_FRACTION = 0.6;
+var MAX_SWIPE_FRACTION = 0.9;
+var SWIPE_HOLD_MS = 100;
+var SWIPE_MOVE_DURATION_MS = 300;
+var SCROLL_TO_SWEEP_DEPTH = 10;
+var SCROLL_TO_PROBE_DIRECTIONS = [
+  ...Array.from({ length: SCROLL_TO_SWEEP_DEPTH }, () => "down"),
+  ...Array.from({ length: SCROLL_TO_SWEEP_DEPTH * 2 }, () => "up")
+];
+var MAX_SCROLL_TO_SWIPES = SCROLL_TO_PROBE_DIRECTIONS.length;
+var OPPOSITE_SWIPE_DIRECTIONS = {
+  up: "down",
+  down: "up",
+  left: "right",
+  right: "left"
+};
+async function probeScrollIntoView({
+  isVisible,
+  swipe,
+  directions = SCROLL_TO_PROBE_DIRECTIONS
+}) {
+  if (await isVisible()) {
+    return true;
+  }
+  for (const direction of directions) {
+    await swipe(direction);
+    if (await isVisible()) {
+      return true;
+    }
+  }
+  return false;
+}
+function toScreenSize(value, source) {
+  const record = value ?? {};
+  const width = Number(record.width);
+  const height = Number(record.height);
+  if (!Number.isFinite(width) || !Number.isFinite(height) || width <= 0 || height <= 0) {
+    throw new Error(`${source} did not return a usable screen size`);
+  }
+  return { width, height };
+}
+function isVertical(direction) {
+  return direction === "up" || direction === "down";
+}
+function swipeDistanceFor(direction, size, amount) {
+  if (amount !== void 0 && !Number.isFinite(amount)) {
+    throw new Error("scroll amount must be a finite number");
+  }
+  const axis = isVertical(direction) ? size.height : size.width;
+  const requested = amount === void 0 ? axis * DEFAULT_SWIPE_FRACTION : Math.abs(amount);
+  const max = axis * MAX_SWIPE_FRACTION;
+  return Math.max(1, Math.round(Math.min(requested, max)));
+}
+function scrollToProbeDistanceFor(direction, size) {
+  const axis = isVertical(direction) ? size.height : size.width;
+  return Math.max(1, Math.round(axis * SCROLL_TO_PROBE_SWIPE_FRACTION));
+}
+function swipeEndpoints(direction, size, distance) {
+  const cx = Math.round(size.width / 2);
+  const cy = Math.round(size.height / 2);
+  const half = Math.round(distance / 2);
+  switch (direction) {
+    case "down":
+      return { start: { x: cx, y: cy + half }, end: { x: cx, y: cy - half } };
+    case "up":
+      return { start: { x: cx, y: cy - half }, end: { x: cx, y: cy + half } };
+    case "right":
+      return { start: { x: cx + half, y: cy }, end: { x: cx - half, y: cy } };
+    case "left":
+      return { start: { x: cx - half, y: cy }, end: { x: cx + half, y: cy } };
+  }
+}
+function buildSwipeActions(start, end) {
+  return {
+    type: "pointer",
+    id: "finger1",
+    parameters: { pointerType: "touch" },
+    actions: [
+      { type: "pointerMove", duration: 0, x: start.x, y: start.y, origin: "viewport" },
+      { type: "pointerDown", button: 0 },
+      { type: "pause", duration: SWIPE_HOLD_MS },
+      { type: "pointerMove", duration: SWIPE_MOVE_DURATION_MS, x: end.x, y: end.y, origin: "viewport" },
+      { type: "pointerUp", button: 0 }
+    ]
+  };
+}
+function buildDirectionalSwipe(direction, size, amount) {
+  const normalizedDirection = amount !== void 0 && amount < 0 ? OPPOSITE_SWIPE_DIRECTIONS[direction] : direction;
+  const distance = swipeDistanceFor(normalizedDirection, size, amount);
+  const { start, end } = swipeEndpoints(normalizedDirection, size, distance);
+  return { actions: buildSwipeActions(start, end), distance, start, end };
+}
+
 // src/browser/android-driver.ts
 var ANDROID_CAPABILITIES = /* @__PURE__ */ new Set([
   "query",
@@ -2317,6 +2535,11 @@ function createAndroidDriver(client, options = {}) {
   async function fillSelector(selector, value) {
     await client.setValue(await resolveOne(selector), value);
   }
+  async function swipe(direction, amount, size) {
+    const actualSize = size ?? await client.windowSize();
+    const { actions } = buildDirectionalSwipe(direction, actualSize, amount);
+    await client.performActions(actions);
+  }
   return {
     capabilities: ANDROID_CAPABILITIES,
     // navigation -----------------------------------------------------------
@@ -2354,8 +2577,31 @@ function createAndroidDriver(client, options = {}) {
     hover() {
       return rejectUnsupported("hover");
     },
-    scrollIntoView() {
-      return rejectUnsupported("scrollTo");
+    // Screen-centred swipe via the W3C actions endpoint (PROWL-080). Direction
+    // semantics match the web step: scrolling "down" reveals lower content, so
+    // the finger drags up. See ./touch-gestures.ts.
+    async scroll(direction, amount) {
+      await swipe(direction, amount);
+    },
+    // Resolve the element, short-circuiting if it is already present in the
+    // hierarchy; otherwise use the shared bounded down/up mobile probe before
+    // failing with a message naming the selector and attempts.
+    async scrollIntoView(selector) {
+      const query = parseAndroidSelector(selector);
+      let probeSize;
+      const found = await probeScrollIntoView({
+        isVisible: async () => (await client.findElements(query)).length > 0,
+        swipe: async (direction) => {
+          probeSize ??= await client.windowSize();
+          await swipe(direction, scrollToProbeDistanceFor(direction, probeSize), probeSize);
+        }
+      });
+      if (found) {
+        return;
+      }
+      throw new Error(
+        `scrollTo: element "${selector}" not visible after ${MAX_SCROLL_TO_SWIPES} scroll attempts on the Android target`
+      );
     },
     setInputFiles() {
       return rejectUnsupported("setInputFiles");
@@ -2678,12 +2924,12 @@ var Uia2Transport = class {
    * {@link Uia2HttpError} on a non-2xx response, or a timeout error when the
    * per-request deadline elapses.
    */
-  async request(method, path25, body, timeoutMs) {
+  async request(method, path27, body, timeoutMs) {
     const requestTimeoutMs = timeoutMs ?? this.requestTimeoutMs;
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), requestTimeoutMs);
     timer.unref?.();
-    const url = `${this.baseUrl}${path25}`;
+    const url = `${this.baseUrl}${path27}`;
     let response;
     try {
       response = await this.fetchImpl(url, {
@@ -2695,7 +2941,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} ${path25} timed out after ${shown}`);
+        throw new Error(`uiautomator2 request ${method} ${path27} timed out after ${shown}`);
       }
       throw error instanceof Error ? error : new Error(String(error));
     } finally {
@@ -2706,7 +2952,7 @@ var Uia2Transport = class {
     if (!response.ok) {
       const wdError = extractWebdriverError(parsed);
       throw new Uia2HttpError(
-        `uiautomator2 ${method} ${path25} failed (${response.status})${wdError ? `: ${wdError}` : ""}`,
+        `uiautomator2 ${method} ${path27} failed (${response.status})${wdError ? `: ${wdError}` : ""}`,
         response.status,
         wdError
       );
@@ -2789,10 +3035,10 @@ function sleep(ms) {
 }
 function createUia2AgentClient(transport, sessionId, options = {}) {
   const base = `/session/${sessionId}`;
-  async function locate(query, path25) {
+  async function locate(query, path27) {
     return transport.request(
       "POST",
-      `${base}${path25}`,
+      `${base}${path27}`,
       androidQueryToLocator(query, { appPackage: options.appPackage })
     );
   }
@@ -2827,6 +3073,13 @@ function createUia2AgentClient(transport, sessionId, options = {}) {
     async pressKeyCode(keyCode) {
       await transport.request("POST", `${base}/appium/device/press_keycode`, { keycode: keyCode });
     },
+    async windowSize() {
+      const value = await transport.request("GET", `${base}/window/current/size`);
+      return toScreenSize(value, "uiautomator2 /window/current/size");
+    },
+    async performActions(actions) {
+      await transport.request("POST", `${base}/actions`, { actions: [actions] });
+    },
     async screenshotPng() {
       const value = await transport.request("GET", `${base}/screenshot`);
       if (typeof value !== "string") {
@@ -2859,10 +3112,10 @@ function resolveAgentApks(requireFn = (0, import_node_module.createRequire)(impo
       "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 = import_node_path5.default.dirname(pkgJsonPath);
+  const pkgDir = import_node_path6.default.dirname(pkgJsonPath);
   const version = requireFn(pkgJsonPath).version;
-  const serverApk = import_node_path5.default.join(pkgDir, "apks", `appium-uiautomator2-server-v${version}.apk`);
-  const testApk = import_node_path5.default.join(pkgDir, "apks", "appium-uiautomator2-server-debug-androidTest.apk");
+  const serverApk = import_node_path6.default.join(pkgDir, "apks", `appium-uiautomator2-server-v${version}.apk`);
+  const testApk = import_node_path6.default.join(pkgDir, "apks", "appium-uiautomator2-server-debug-androidTest.apk");
   for (const apk of [serverApk, testApk]) {
     if (!import_node_fs6.default.existsSync(apk)) {
       throw new Error(`Expected uiautomator2 agent APK is missing: ${apk}. Reinstall dependencies.`);
@@ -2910,7 +3163,7 @@ async function resolvePackage(app, runner, serial, aaptResolver, allowedApps) {
     assertAndroidAppAllowed(allowedApps, app);
     return app;
   }
-  const apkPath = import_node_path5.default.resolve(app);
+  const apkPath = import_node_path6.default.resolve(app);
   if (!import_node_fs6.default.existsSync(apkPath)) {
     throw new Error(`APK not found: ${apkPath}`);
   }
@@ -2971,6 +3224,7 @@ async function launchAndroidSession(options) {
       readyDeadlineMs,
       appPackage: pkg
     });
+    await launchPackage(runner, serial, pkg);
     const driver = createAndroidDriver(client, { appLabel: pkg });
     return { client, driver, package: pkg, serial, teardown };
   } catch (error) {
@@ -2986,8 +3240,8 @@ async function closeAndroidSession(session) {
 var import_node_module2 = require("module");
 var import_node_child_process6 = require("child_process");
 var import_node_fs7 = __toESM(require("fs"), 1);
-var import_node_os2 = __toESM(require("os"), 1);
-var import_node_path7 = __toESM(require("path"), 1);
+var import_node_os4 = __toESM(require("os"), 1);
+var import_node_path8 = __toESM(require("path"), 1);
 
 // src/browser/ios-driver.ts
 var IOS_CAPABILITIES = /* @__PURE__ */ new Set([
@@ -2998,6 +3252,7 @@ var IOS_CAPABILITIES = /* @__PURE__ */ new Set([
 ]);
 var WAIT_POLL_INTERVAL_MS2 = 250;
 var DEFAULT_WAIT_TIMEOUT_MS2 = 5e3;
+var DISPLAYED_CHECK_CONCURRENCY = 4;
 var IOS_PRESS_KEYS = ["backspace", "del", "delete", "enter", "home", "return"];
 function escapePredicateArg(value) {
   return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
@@ -3072,6 +3327,64 @@ function createIosDriver(client, options) {
   async function fillSelector(selector, value) {
     await client.setValue(await resolveOne(selector), value);
   }
+  async function swipe(direction, amount, size) {
+    const actualSize = size ?? await client.windowSize();
+    const { actions } = buildDirectionalSwipe(direction, actualSize, amount);
+    await client.performActions(actions);
+  }
+  async function visibleElementIds(query) {
+    const ids = await client.findElements(query);
+    const visible = Array.from({ length: ids.length }, () => null);
+    let nextIndex = 0;
+    const workerCount = Math.min(DISPLAYED_CHECK_CONCURRENCY, ids.length);
+    await Promise.all(
+      Array.from({ length: workerCount }, async () => {
+        for (; ; ) {
+          const index = nextIndex;
+          nextIndex += 1;
+          if (index >= ids.length) {
+            return;
+          }
+          const id = ids[index];
+          if (await client.isDisplayed(id)) {
+            visible[index] = id;
+          }
+        }
+      })
+    );
+    return visible.filter((id) => id !== null);
+  }
+  async function hasVisibleElement(query) {
+    const ids = await client.findElements(query);
+    if (ids.length === 0) {
+      return false;
+    }
+    if (await client.isDisplayed(ids[0])) {
+      return true;
+    }
+    let found = false;
+    let nextIndex = 1;
+    const workerCount = Math.min(DISPLAYED_CHECK_CONCURRENCY, ids.length - 1);
+    await Promise.all(
+      Array.from({ length: workerCount }, async () => {
+        for (; ; ) {
+          if (found) {
+            return;
+          }
+          const index = nextIndex;
+          nextIndex += 1;
+          if (index >= ids.length) {
+            return;
+          }
+          if (await client.isDisplayed(ids[index])) {
+            found = true;
+            return;
+          }
+        }
+      })
+    );
+    return found;
+  }
   async function pressKey(key) {
     const name = key.trim().toLowerCase();
     if (name === "enter" || name === "return") {
@@ -3103,6 +3416,9 @@ function createIosDriver(client, options) {
     async count(selector) {
       return (await client.findElements(parseIosSelector(selector))).length;
     },
+    async visibleCount(selector) {
+      return (await visibleElementIds(parseIosSelector(selector))).length;
+    },
     async textContent(selector) {
       const id = await client.findElement(parseIosSelector(selector));
       if (id === null) {
@@ -3127,15 +3443,38 @@ function createIosDriver(client, options) {
     hover() {
       return rejectUnsupported("hover");
     },
-    scrollIntoView() {
-      return rejectUnsupported("scrollTo");
+    // Screen-centred swipe via the W3C actions endpoint (PROWL-080). Direction
+    // semantics match the web step: scrolling "down" reveals lower content, so
+    // the finger drags up. See ./touch-gestures.ts.
+    async scroll(direction, amount) {
+      await swipe(direction, amount);
+    },
+    // Resolve the element, short-circuiting only if WDA reports a matching
+    // element displayed in the viewport; hierarchy-only matches can be offscreen.
+    // Otherwise use the shared bounded down/up mobile probe before failing.
+    async scrollIntoView(selector) {
+      const query = parseIosSelector(selector);
+      let probeSize;
+      const found = await probeScrollIntoView({
+        isVisible: () => hasVisibleElement(query),
+        swipe: async (direction) => {
+          probeSize ??= await client.windowSize();
+          await swipe(direction, scrollToProbeDistanceFor(direction, probeSize), probeSize);
+        }
+      });
+      if (found) {
+        return;
+      }
+      throw new Error(
+        `scrollTo: element "${selector}" not visible after ${MAX_SCROLL_TO_SWIPES} scroll attempts on the iOS target`
+      );
     },
     setInputFiles() {
       return rejectUnsupported("setInputFiles");
     },
     // semantic locators ----------------------------------------------------
     async countByRole(role, name) {
-      return (await client.findElements({ by: "role", role, name })).length;
+      return (await visibleElementIds({ by: "role", role, name })).length;
     },
     async clickFirstByRole(role, name) {
       const id = await client.findElement({ by: "role", role, name });
@@ -3145,7 +3484,7 @@ function createIosDriver(client, options) {
       await client.click(id);
     },
     async countByLabel(label) {
-      return (await client.findElements({ by: "label", value: label })).length;
+      return (await visibleElementIds({ by: "label", value: label })).length;
     },
     async fillFirstByLabel(label, value) {
       const id = await client.findElement({ by: "label", value: label });
@@ -3163,7 +3502,7 @@ function createIosDriver(client, options) {
       const timeoutMs = waitOptions?.timeout ?? DEFAULT_WAIT_TIMEOUT_MS2;
       const deadline = Date.now() + timeoutMs;
       for (; ; ) {
-        if ((await client.findElements(query)).length > 0) {
+        if (await hasVisibleElement(query)) {
           return;
         }
         if (Date.now() >= deadline) {
@@ -3211,8 +3550,8 @@ function createIosDriver(client, options) {
 var import_node_child_process5 = require("child_process");
 var import_promises = require("fs/promises");
 var import_node_net = __toESM(require("net"), 1);
-var import_node_os = __toESM(require("os"), 1);
-var import_node_path6 = __toESM(require("path"), 1);
+var import_node_os3 = __toESM(require("os"), 1);
+var import_node_path7 = __toESM(require("path"), 1);
 var spawnXcrunProcess = (args, options) => {
   const child = (0, import_node_child_process5.spawn)("xcrun", args, {
     stdio: "ignore",
@@ -3226,7 +3565,7 @@ var spawnXcrunProcess = (args, options) => {
     }
   };
 };
-var DEFAULT_SIMULATOR_LOCK_ROOT = import_node_path6.default.join(import_node_os.default.tmpdir(), "prowl-ios-simulator-locks");
+var DEFAULT_SIMULATOR_LOCK_ROOT = import_node_path7.default.join(import_node_os3.default.tmpdir(), "prowl-ios-simulator-locks");
 var SIMULATOR_LOCK_OWNER_FILE = "owner.json";
 var execFileXcrunRunner = (args, options) => new Promise((resolve) => {
   (0, import_node_child_process5.execFile)(
@@ -3266,7 +3605,7 @@ function isProcessAlive(pid) {
 }
 async function removeStaleSimulatorLock(lockPath) {
   try {
-    const ownerText = await (0, import_promises.readFile)(import_node_path6.default.join(lockPath, SIMULATOR_LOCK_OWNER_FILE), "utf8");
+    const ownerText = await (0, import_promises.readFile)(import_node_path7.default.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 (0, import_promises.rm)(lockPath, { recursive: true, force: true });
@@ -3284,7 +3623,7 @@ function simulatorReservedError(udid) {
 }
 async function reserveSimulatorUdid(udid, options = {}) {
   const lockRoot = options.lockRoot ?? DEFAULT_SIMULATOR_LOCK_ROOT;
-  const lockPath = import_node_path6.default.join(lockRoot, simulatorLockName(udid));
+  const lockPath = import_node_path7.default.join(lockRoot, simulatorLockName(udid));
   await (0, import_promises.mkdir)(lockRoot, { recursive: true });
   for (let attempt = 0; attempt < 2; attempt += 1) {
     try {
@@ -3308,7 +3647,7 @@ async function reserveSimulatorUdid(udid, options = {}) {
     };
     try {
       await (0, import_promises.writeFile)(
-        import_node_path6.default.join(lockPath, SIMULATOR_LOCK_OWNER_FILE),
+        import_node_path7.default.join(lockPath, SIMULATOR_LOCK_OWNER_FILE),
         `${JSON.stringify({ pid: process.pid, udid, createdAt: (/* @__PURE__ */ new Date()).toISOString() })}
 `,
         { flag: "wx" }
@@ -3500,15 +3839,15 @@ var WdaTransport = class {
    * {@link WdaHttpError} on a non-2xx response, or a timeout error when the
    * per-request deadline elapses.
    */
-  async requestFull(method, path25, body, timeoutMs) {
+  async requestFull(method, path27, body, timeoutMs) {
     const requestTimeoutMs = timeoutMs ?? this.requestTimeoutMs;
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), requestTimeoutMs);
     timer.unref?.();
-    const url = `${this.baseUrl}${path25}`;
+    const url = `${this.baseUrl}${path27}`;
     const timeoutError = () => {
       const shown = requestTimeoutMs >= 1e3 ? `${Math.round(requestTimeoutMs / 1e3)}s` : `${requestTimeoutMs}ms`;
-      return new Error(`WebDriverAgent request ${method} ${path25} timed out after ${shown}`);
+      return new Error(`WebDriverAgent request ${method} ${path27} timed out after ${shown}`);
     };
     let response;
     try {
@@ -3540,7 +3879,7 @@ var WdaTransport = class {
     if (!response.ok) {
       const wdError = extractWebdriverError2(parsed);
       throw new WdaHttpError(
-        `WebDriverAgent ${method} ${path25} failed (${response.status})${wdError ? `: ${wdError}` : ""}`,
+        `WebDriverAgent ${method} ${path27} failed (${response.status})${wdError ? `: ${wdError}` : ""}`,
         response.status,
         wdError
       );
@@ -3548,8 +3887,8 @@ var WdaTransport = class {
     return parsed;
   }
   /** Like {@link requestFull} but returns just the `value` field. */
-  async request(method, path25, body, timeoutMs) {
-    const parsed = await this.requestFull(method, path25, body, timeoutMs);
+  async request(method, path27, body, timeoutMs) {
+    const parsed = await this.requestFull(method, path27, body, timeoutMs);
     return parsed?.value;
   }
 };
@@ -3625,8 +3964,8 @@ function sleep2(ms) {
 }
 function createWdaAgentClient(transport, sessionId) {
   const base = `/session/${sessionId}`;
-  async function locate(query, path25) {
-    return transport.request("POST", `${base}${path25}`, iosQueryToLocator(query));
+  async function locate(query, path27) {
+    return transport.request("POST", `${base}${path27}`, iosQueryToLocator(query));
   }
   return {
     async findElement(query) {
@@ -3656,12 +3995,29 @@ function createWdaAgentClient(transport, sessionId) {
       const value = await transport.request("GET", `${base}/element/${elementId}/text`);
       return typeof value === "string" ? value : value == null ? null : String(value);
     },
+    async isDisplayed(elementId) {
+      try {
+        return await transport.request("GET", `${base}/element/${elementId}/displayed`) === true;
+      } catch (error) {
+        if (isNoSuchElement2(error)) {
+          return false;
+        }
+        throw error;
+      }
+    },
     async sendKeys(keys) {
       await transport.request("POST", `${base}/wda/keys`, { value: keys });
     },
     async homescreen() {
       await transport.request("POST", "/wda/homescreen", {});
     },
+    async windowSize() {
+      const value = await transport.request("GET", `${base}/window/size`);
+      return toScreenSize(value, "WebDriverAgent /window/size");
+    },
+    async performActions(actions) {
+      await transport.request("POST", `${base}/actions`, { actions: [actions] });
+    },
     async source() {
       const value = await transport.request("GET", "/source");
       if (typeof value !== "string") {
@@ -3702,19 +4058,19 @@ function resolveWdaProject(requireFn = (0, import_node_module2.createRequire)(im
       "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 = import_node_path7.default.dirname(pkgJsonPath);
+  const pkgDir = import_node_path8.default.dirname(pkgJsonPath);
   const version = requireFn(pkgJsonPath).version;
-  const projectPath = import_node_path7.default.join(pkgDir, "WebDriverAgent.xcodeproj");
+  const projectPath = import_node_path8.default.join(pkgDir, "WebDriverAgent.xcodeproj");
   if (!import_node_fs7.default.existsSync(projectPath)) {
     throw new Error(`Expected WebDriverAgent project is missing: ${projectPath}. Reinstall dependencies.`);
   }
   return { projectPath, version };
 }
-function wdaCacheDir(wdaVersion, xcode, homeDir = import_node_os2.default.homedir()) {
-  return import_node_path7.default.join(homeDir, ".prowl", "wda", `${wdaVersion}-xcode${xcode}`);
+function wdaCacheDir(wdaVersion, xcode, homeDir = import_node_os4.default.homedir()) {
+  return import_node_path8.default.join(homeDir, ".prowl", "wda", `${wdaVersion}-xcode${xcode}`);
 }
 function productsDir(derivedDataPath) {
-  return import_node_path7.default.join(derivedDataPath, "Build", "Products");
+  return import_node_path8.default.join(derivedDataPath, "Build", "Products");
 }
 function findXctestrunIn(dir) {
   let entries;
@@ -3724,7 +4080,7 @@ function findXctestrunIn(dir) {
     return null;
   }
   const match = entries.filter((name) => name.endsWith(".xctestrun") && !name.startsWith(PREPARED_XCTESTRUN_PREFIX)).sort()[0];
-  return match ? import_node_path7.default.join(dir, match) : null;
+  return match ? import_node_path8.default.join(dir, match) : null;
 }
 function resolveOverrideXctestrun(override) {
   if (!import_node_fs7.default.existsSync(override)) {
@@ -3736,7 +4092,7 @@ function resolveOverrideXctestrun(override) {
   const candidates = [];
   const stat = import_node_fs7.default.statSync(override);
   if (override.endsWith(".app")) {
-    candidates.push(import_node_path7.default.dirname(import_node_path7.default.dirname(override)));
+    candidates.push(import_node_path8.default.dirname(import_node_path8.default.dirname(override)));
   } else if (stat.isDirectory()) {
     candidates.push(override, productsDir(override));
   }
@@ -3753,7 +4109,7 @@ function resolveOverrideXctestrun(override) {
 async function resolveWdaTestRun(options = {}) {
   const runner = options.runner ?? execFileXcrunRunner;
   const env = options.env ?? process.env;
-  const homeDir = options.homeDir ?? import_node_os2.default.homedir();
+  const homeDir = options.homeDir ?? import_node_os4.default.homedir();
   const log = options.logger ?? ((message) => process.stderr.write(`${message}
 `));
   const override = env.PROWL_WDA_RUNNER;
@@ -3869,8 +4225,8 @@ var defaultWdaTestRunPreparer = async ({ xctestrunPath, port }) => {
   }
   const injected = injectUsePortIntoXctestrun(parsed, port);
   const stem = `${PREPARED_XCTESTRUN_PREFIX}${port}-${process.pid}`;
-  const outPath = import_node_path7.default.join(import_node_path7.default.dirname(xctestrunPath), `${stem}.xctestrun`);
-  const jsonPath = import_node_path7.default.join(import_node_os2.default.tmpdir(), `${stem}.json`);
+  const outPath = import_node_path8.default.join(import_node_path8.default.dirname(xctestrunPath), `${stem}.xctestrun`);
+  const jsonPath = import_node_path8.default.join(import_node_os4.default.tmpdir(), `${stem}.json`);
   import_node_fs7.default.writeFileSync(jsonPath, JSON.stringify(injected));
   try {
     await runPlutil(["-convert", "xml1", jsonPath, "-o", outPath]);
@@ -3883,7 +4239,7 @@ function cleanupPreparedTestRun(preparedPath) {
   if (!preparedPath) {
     return;
   }
-  if (!import_node_path7.default.basename(preparedPath).startsWith(PREPARED_XCTESTRUN_PREFIX)) {
+  if (!import_node_path8.default.basename(preparedPath).startsWith(PREPARED_XCTESTRUN_PREFIX)) {
     return;
   }
   import_node_fs7.default.rmSync(preparedPath, { force: true });
@@ -3908,7 +4264,7 @@ async function resolveBundleId(app, runner, udid, coldStart, allowedApps) {
     }
     return app;
   }
-  const appPath = import_node_path7.default.resolve(app);
+  const appPath = import_node_path8.default.resolve(app);
   if (!import_node_fs7.default.existsSync(appPath)) {
     throw new Error(`.app bundle not found: ${appPath}`);
   }
@@ -4013,8 +4369,9 @@ async function closeIosSession(session) {
 
 // src/runner/steps.ts
 var import_node_fs9 = __toESM(require("fs"), 1);
-var import_node_path9 = __toESM(require("path"), 1);
+var import_node_path10 = __toESM(require("path"), 1);
 init_loader();
+init_interpolate();
 
 // src/runner/healing.ts
 var INTERACTIVE_TAGS = ["button", "a", "input", "select", "textarea"];
@@ -4712,11 +5069,14 @@ function toVisibilitySelector(value) {
   if (looksLikeSelector(value)) return value;
   return textContainsSelector(value);
 }
+function countVisible(driver, selector) {
+  return driver.visibleCount?.(selector) ?? driver.count(selector);
+}
 async function runInlineAssert(driver, policy, assertion) {
   if (assertion.visible !== void 0) {
     const selector = toVisibilitySelector(assertion.visible);
     policy.assertAllowedSelector(selector);
-    const count = await driver.count(selector);
+    const count = await countVisible(driver, selector);
     if (count === 0) {
       throw new Error(`Expected visible: ${assertion.visible}`);
     }
@@ -4725,7 +5085,7 @@ async function runInlineAssert(driver, policy, assertion) {
   if (assertion.notVisible !== void 0) {
     const selector = toVisibilitySelector(assertion.notVisible);
     policy.assertAllowedSelector(selector);
-    const count = await driver.count(selector);
+    const count = await countVisible(driver, selector);
     if (count > 0) {
       throw new Error(`Expected not visible: ${assertion.notVisible}`);
     }
@@ -4748,7 +5108,7 @@ async function runInlineAssert(driver, policy, assertion) {
   throw new Error("assert step is missing an assertion type");
 }
 function screenshotPath(screenshotsDir, fileName) {
-  return import_node_path9.default.join(screenshotsDir, fileName);
+  return import_node_path10.default.join(screenshotsDir, fileName);
 }
 function stepPath(prefix, index) {
   return prefix ? `${prefix}.${index}` : `${index}`;
@@ -4765,7 +5125,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 !== import_node_path9.default.basename(safeFilename) || safeFilename.includes("..") || /[/\\]/.test(safeFilename) || hasControlCharacter || !allowedFilenamePattern.test(safeFilename)) {
+  if (safeFilename.length === 0 || safeFilename !== suggestedFilename || safeFilename !== import_node_path10.default.basename(safeFilename) || safeFilename.includes("..") || /[/\\]/.test(safeFilename) || hasControlCharacter || !allowedFilenamePattern.test(safeFilename)) {
     throw new Error(`Invalid download filename: "${suggestedFilename}"`);
   }
   return safeFilename;
@@ -4945,7 +5305,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) => import_node_path9.default.isAbsolute(f) ? f : import_node_path9.default.join(h.context.configDir, f);
+      const resolveFile = (f) => import_node_path10.default.isAbsolute(f) ? f : import_node_path10.default.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);
@@ -5115,25 +5475,21 @@ var STEP_HANDLERS = {
     }
   },
   scroll: {
-    capabilities: ["evaluate"],
+    // Dispatched through the driver's `scroll` verb (interact), so native mobile
+    // targets synthesize a touch swipe while web keeps its `window.scrollBy`
+    // behavior. The per-target step gate rejects `scroll` on macOS before here.
+    capabilities: ["interact"],
     run: async (h) => {
       if (!("scroll" in h.step)) unknownStep();
-      const amount = h.step.scroll.amount ?? 500;
-      const scrollMap = {
-        up: [0, -amount],
-        down: [0, amount],
-        left: [-amount, 0],
-        right: [amount, 0]
-      };
-      const [x, y] = scrollMap[h.step.scroll.direction];
-      await h.driver.evaluate(([sx, sy]) => window.scrollBy(sx, sy), [x, y]);
+      const { direction, amount } = h.step.scroll;
+      await h.driver.scroll(direction, amount);
       return {
         kind: "result",
         result: {
           type: "scroll",
           status: "pass",
           durationMs: Date.now() - h.stepStart,
-          value: `${h.step.scroll.direction} ${amount}px`
+          value: amount === void 0 ? direction : `${direction} ${amount}px`
         }
       };
     }
@@ -5179,7 +5535,7 @@ var STEP_HANDLERS = {
       const condition = h.step.if;
       const selector = condition.visible ?? condition.notVisible;
       h.policy.assertAllowedSelector(selector);
-      const count = await h.driver.count(selector);
+      const count = await countVisible(h.driver, selector);
       const conditionMet = condition.visible !== void 0 ? count > 0 : count === 0;
       if (conditionMet) {
         const subResult = await h.executeNested({
@@ -5266,7 +5622,7 @@ var STEP_HANDLERS = {
         const whileSelector = repeat.while.visible ?? repeat.while.notVisible;
         h.policy.assertAllowedSelector(whileSelector);
         for (let i = 0; i < maxIter; i++) {
-          const whileCount = await h.driver.count(whileSelector);
+          const whileCount = await countVisible(h.driver, whileSelector);
           const shouldContinue = repeat.while.visible !== void 0 ? whileCount > 0 : whileCount === 0;
           if (!shouldContinue) break;
           totalSubSteps += repeat.steps.length;
@@ -5307,11 +5663,11 @@ var STEP_HANDLERS = {
         if (!responseFile) {
           throw new Error("mock.response must include either body or file");
         }
-        const candidateFilePath = import_node_path9.default.isAbsolute(responseFile) ? responseFile : import_node_path9.default.join(h.context.configDir, responseFile);
-        const resolvedConfigDir = import_node_path9.default.resolve(h.context.configDir);
-        const resolvedFilePath = import_node_path9.default.resolve(candidateFilePath);
-        const relativePath = import_node_path9.default.relative(resolvedConfigDir, resolvedFilePath);
-        const isWithinConfigDir = relativePath === "" || relativePath !== ".." && !relativePath.startsWith(`..${import_node_path9.default.sep}`) && !import_node_path9.default.isAbsolute(relativePath);
+        const candidateFilePath = import_node_path10.default.isAbsolute(responseFile) ? responseFile : import_node_path10.default.join(h.context.configDir, responseFile);
+        const resolvedConfigDir = import_node_path10.default.resolve(h.context.configDir);
+        const resolvedFilePath = import_node_path10.default.resolve(candidateFilePath);
+        const relativePath = import_node_path10.default.relative(resolvedConfigDir, resolvedFilePath);
+        const isWithinConfigDir = relativePath === "" || relativePath !== ".." && !relativePath.startsWith(`..${import_node_path10.default.sep}`) && !import_node_path10.default.isAbsolute(relativePath);
         if (!isWithinConfigDir) {
           throw new Error("mock.response.file must resolve within config directory");
         }
@@ -5378,7 +5734,7 @@ var STEP_HANDLERS = {
     capabilities: ["evaluate"],
     run: async (h) => {
       if (!("runScript" in h.step)) unknownStep();
-      const filePath = import_node_path9.default.isAbsolute(h.step.runScript.file) ? h.step.runScript.file : import_node_path9.default.join(h.context.configDir, h.step.runScript.file);
+      const filePath = import_node_path10.default.isAbsolute(h.step.runScript.file) ? h.step.runScript.file : import_node_path10.default.join(h.context.configDir, h.step.runScript.file);
       const fileContents = import_node_fs9.default.readFileSync(filePath, "utf-8");
       await h.driver.evaluate(fileContents);
       return {
@@ -5400,11 +5756,11 @@ var STEP_HANDLERS = {
       const name = h.step.assertScreenshot.name;
       const threshold = h.step.assertScreenshot.threshold ?? 0.1;
       const baselineDir = ensureBaselineDir2(h.context.configDir);
-      const baselinePath = import_node_path9.default.join(baselineDir, `${name}.png`);
-      const currentScreenshotPath = import_node_path9.default.join(h.context.runDir, "screenshots", `${name}-current.png`);
-      import_node_fs9.default.mkdirSync(import_node_path9.default.dirname(currentScreenshotPath), { recursive: true });
+      const baselinePath = import_node_path10.default.join(baselineDir, `${name}.png`);
+      const currentScreenshotPath = import_node_path10.default.join(h.context.runDir, "screenshots", `${name}-current.png`);
+      import_node_fs9.default.mkdirSync(import_node_path10.default.dirname(currentScreenshotPath), { recursive: true });
       await h.driver.screenshot({ path: currentScreenshotPath, fullPage: true });
-      h.screenshots.push(import_node_path9.default.join("screenshots", `${name}-current.png`));
+      h.screenshots.push(import_node_path10.default.join("screenshots", `${name}-current.png`));
       if (!import_node_fs9.default.existsSync(baselinePath)) {
         import_node_fs9.default.copyFileSync(currentScreenshotPath, baselinePath);
         return {
@@ -5412,7 +5768,7 @@ var STEP_HANDLERS = {
           result: { type: "assertScreenshot", status: "pass", durationMs: Date.now() - h.stepStart, value: "baseline created" }
         };
       }
-      const diffPath = import_node_path9.default.join(h.context.runDir, "screenshots", `${name}-diff.png`);
+      const diffPath = import_node_path10.default.join(h.context.runDir, "screenshots", `${name}-diff.png`);
       const comparison = await compareScreenshots2(baselinePath, currentScreenshotPath, diffPath, threshold);
       if (comparison.match) {
         return {
@@ -5425,7 +5781,7 @@ var STEP_HANDLERS = {
           }
         };
       }
-      h.screenshots.push(import_node_path9.default.join("screenshots", `${name}-diff.png`));
+      h.screenshots.push(import_node_path10.default.join("screenshots", `${name}-diff.png`));
       throw new Error(
         `Visual regression: ${(comparison.diffPercentage * 100).toFixed(2)}% diff exceeds threshold ${(threshold * 100).toFixed(0)}%`
       );
@@ -5451,7 +5807,7 @@ var STEP_HANDLERS = {
       }
       const fileName = `assertWithAI_step_${h.index + 1}.png`;
       const relative = await h.addScreenshot(fileName);
-      const screenshotFullPath = import_node_path9.default.join(h.context.runDir, relative);
+      const screenshotFullPath = import_node_path10.default.join(h.context.runDir, relative);
       const imageBase64 = import_node_fs9.default.readFileSync(screenshotFullPath).toString("base64");
       const assertVision = h.context.assertVision ?? assertWithAiVision;
       const verdict = await assertVision(
@@ -5509,7 +5865,7 @@ var STEP_HANDLERS = {
           `Download filename mismatch: expected "${opts.filename}", got "${suggestedFilename}"`
         );
       }
-      const savePath = import_node_path9.default.join(h.context.runDir, suggestedFilename);
+      const savePath = import_node_path10.default.join(h.context.runDir, suggestedFilename);
       await download.saveAs(savePath);
       return {
         kind: "result",
@@ -5538,7 +5894,7 @@ async function executeSteps(context) {
     maxSteps: context.maxSteps,
     selfHealing: context.selfHealing
   });
-  const screenshotsDir = import_node_path9.default.join(context.runDir, "screenshots");
+  const screenshotsDir = import_node_path10.default.join(context.runDir, "screenshots");
   import_node_fs9.default.mkdirSync(screenshotsDir, { recursive: true });
   const currentHuntName = context.huntStack?.[context.huntStack.length - 1];
   policy.assertWithinMaxSteps(context.steps.length, currentHuntName);
@@ -5549,7 +5905,7 @@ async function executeSteps(context) {
   const addScreenshot = async (fileName) => {
     const fullPath = screenshotPath(screenshotsDir, fileName);
     await captureScreenshot2(driver, fullPath);
-    const relative = import_node_path9.default.join("screenshots", fileName);
+    const relative = import_node_path10.default.join("screenshots", fileName);
     screenshots.push(relative);
     return relative;
   };
@@ -5637,12 +5993,12 @@ async function executeSteps(context) {
   return { results, screenshots, failed: false };
 }
 async function captureFinalScreenshot(page, runDir) {
-  const screenshotsDir = import_node_path9.default.join(runDir, "screenshots");
+  const screenshotsDir = import_node_path10.default.join(runDir, "screenshots");
   import_node_fs9.default.mkdirSync(screenshotsDir, { recursive: true });
   const fileName = "final.png";
   const filePath = screenshotPath(screenshotsDir, fileName);
   await captureScreenshot2(page, filePath);
-  return import_node_path9.default.join("screenshots", fileName);
+  return import_node_path10.default.join("screenshots", fileName);
 }
 
 // src/runner/assertions.ts
@@ -5764,6 +6120,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";
@@ -5803,17 +6212,17 @@ function captureTraceCorrelation(response, headerName, sink, redactionValues = [
 
 // src/reporter/result.ts
 var import_node_fs10 = __toESM(require("fs"), 1);
-var import_node_path10 = __toESM(require("path"), 1);
+var import_node_path11 = __toESM(require("path"), 1);
 function writeResult(runDir, result) {
   const fileName = "result.json";
-  const fullPath = import_node_path10.default.join(runDir, fileName);
+  const fullPath = import_node_path11.default.join(runDir, fileName);
   import_node_fs10.default.writeFileSync(fullPath, JSON.stringify(result, null, 2));
   return fileName;
 }
 
 // src/reporter/summary.ts
 var import_node_fs11 = __toESM(require("fs"), 1);
-var import_node_path11 = __toESM(require("path"), 1);
+var import_node_path12 = __toESM(require("path"), 1);
 function escapeMd(text) {
   return text.replace(/([|`*_{}[\]()#+\-!\\])/g, "\\$1");
 }
@@ -5891,7 +6300,7 @@ function writeSummary(runDir, result) {
     }
   }
   const fileName = "summary.md";
-  const fullPath = import_node_path11.default.join(runDir, fileName);
+  const fullPath = import_node_path12.default.join(runDir, fileName);
   import_node_fs11.default.writeFileSync(fullPath, `${lines.join("\n")}
 `);
   return fileName;
@@ -5899,20 +6308,21 @@ function writeSummary(runDir, result) {
 
 // src/reporter/junit.ts
 var import_node_fs12 = __toESM(require("fs"), 1);
-var import_node_path12 = __toESM(require("path"), 1);
+var import_node_path13 = __toESM(require("path"), 1);
 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];
@@ -5936,6 +6346,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"/>`);
     }
@@ -5943,7 +6358,7 @@ function writeJunit(runDir, result) {
   lines.push("  </testsuite>");
   lines.push("</testsuites>");
   const fileName = "junit.xml";
-  const fullPath = import_node_path12.default.join(runDir, fileName);
+  const fullPath = import_node_path13.default.join(runDir, fileName);
   import_node_fs12.default.writeFileSync(fullPath, `${lines.join("\n")}
 `);
   return fileName;
@@ -5979,14 +6394,14 @@ function timestamp(prefix) {
 
 // src/runner/history.ts
 var import_node_fs13 = __toESM(require("fs"), 1);
-var import_node_path13 = __toESM(require("path"), 1);
+var import_node_path14 = __toESM(require("path"), 1);
 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 import_node_path13.default.join(configDir, HISTORY_FILE);
+  return import_node_path14.default.join(configDir, HISTORY_FILE);
 }
 function isHistoryEntry(value) {
   if (!value || typeof value !== "object") {
@@ -6040,7 +6455,7 @@ function sleepSync(ms) {
 function withHistoryLock(configDir, fn) {
   const filePath = historyPath(configDir);
   const lockPath = `${filePath}${LOCK_FILE_SUFFIX}`;
-  import_node_fs13.default.mkdirSync(import_node_path13.default.dirname(filePath), { recursive: true });
+  import_node_fs13.default.mkdirSync(import_node_path14.default.dirname(filePath), { recursive: true });
   const startedAt = Date.now();
   while (Date.now() - startedAt < LOCK_TIMEOUT_MS) {
     let fd;
@@ -6088,11 +6503,11 @@ function parseViewportFlag(value) {
   return value;
 }
 function resolvePath(configDir, inputPath) {
-  if (import_node_path14.default.isAbsolute(inputPath)) {
+  if (import_node_path15.default.isAbsolute(inputPath)) {
     return inputPath;
   }
-  const projectRoot = import_node_path14.default.dirname(configDir);
-  return import_node_path14.default.join(projectRoot, inputPath);
+  const projectRoot = import_node_path15.default.dirname(configDir);
+  return import_node_path15.default.join(projectRoot, inputPath);
 }
 function buildRunResult(options) {
   return {
@@ -6111,7 +6526,7 @@ function buildRunResult(options) {
 }
 function writeConsoleLog(runDir, entries) {
   const fileName = "console.log";
-  const filePath = import_node_path14.default.join(runDir, fileName);
+  const filePath = import_node_path15.default.join(runDir, fileName);
   const lines = entries.map((entry) => {
     const location = entry.location ? ` (${entry.location})` : "";
     return `[${entry.type}] ${entry.text}${location}`;
@@ -6124,7 +6539,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 = import_node_path14.default.join(configDir, "runs", timestamp());
+  const runDir = import_node_path15.default.join(configDir, "runs", timestamp());
   import_node_fs14.default.mkdirSync(runDir, { recursive: true });
   const storageStatePath = config.auth.storageStatePath ? resolvePath(configDir, config.auth.storageStatePath) : void 0;
   const engine = options.browser ?? config.browser.engine;
@@ -6308,7 +6723,7 @@ async function runHunt(options) {
 }
 async function executeNativeHuntAttempt(options, config, configDir, interpolatedHunt, redactedFillSteps, randomVars, allowedApps, native) {
   const maxSteps = config.guardrails.maxSteps;
-  const runDir = import_node_path14.default.join(configDir, "runs", timestamp());
+  const runDir = import_node_path15.default.join(configDir, "runs", timestamp());
   import_node_fs14.default.mkdirSync(runDir, { recursive: true });
   const session = await native.launchSession();
   let result;
@@ -6317,6 +6732,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 = [];
@@ -6356,8 +6778,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
     };
@@ -6368,7 +6801,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 });
@@ -6481,7 +6914,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) {
@@ -6522,7 +6954,7 @@ async function runNativeHunt(options, config, configDir, target, native) {
 }
 function recordHistory(configDir, outcome, maxRuns) {
   try {
-    const relativeRunDir = import_node_path14.default.relative(configDir, outcome.runDir);
+    const relativeRunDir = import_node_path15.default.relative(configDir, outcome.runDir);
     appendEntry(
       configDir,
       {
@@ -6540,6 +6972,7 @@ function recordHistory(configDir, outcome, maxRuns) {
 
 // src/cli/commands/run.ts
 init_loader();
+init_hunt_name();
 
 // src/cli/output.ts
 var import_chalk = __toESM(require("chalk"), 1);
@@ -6685,7 +7118,11 @@ ${bot}`);
 
 // src/cli/commands/run.ts
 function buildRunCommand() {
-  const command = new import_commander.Command("run").argument("<hunt-name>", "Hunt name or path (e.g. homepage or admin/users-crud)").option("--url <target>", "Override target URL").option("--headed", "Show browser window").option("--slow-mo <ms>", "Slow down Playwright actions", (value) => Number(value)).option("--trace", "Capture Playwright trace").option("--browser <engine>", "Browser engine: chromium, firefox, or webkit").option("--channel <name>", "Browser channel: chrome, msedge, chrome-beta, etc.").option("--viewport <size>", "Viewport size: WxH (e.g. 1920x1080) or preset (mobile, tablet, desktop)").option("--include-tags <tags>", "Only run hunts matching these tags (comma-separated)").option("--exclude-tags <tags>", "Skip hunts matching these tags (comma-separated)").option("--junit", "Generate JUnit XML report").option("--config <path>", "Custom config path").option("--json", "Output results as JSON").action(async (huntName, options) => {
+  const command = new import_commander.Command("run").argument(
+    "<hunt-name>",
+    "Hunt name or path (e.g. homepage, admin/users-crud, or .prowl/hunts/homepage.yml)"
+  ).option("--url <target>", "Override target URL").option("--headed", "Show browser window").option("--slow-mo <ms>", "Slow down Playwright actions", (value) => Number(value)).option("--trace", "Capture Playwright trace").option("--browser <engine>", "Browser engine: chromium, firefox, or webkit").option("--channel <name>", "Browser channel: chrome, msedge, chrome-beta, etc.").option("--viewport <size>", "Viewport size: WxH (e.g. 1920x1080) or preset (mobile, tablet, desktop)").option("--include-tags <tags>", "Only run hunts matching these tags (comma-separated)").option("--exclude-tags <tags>", "Skip hunts matching these tags (comma-separated)").option("--junit", "Generate JUnit XML report").option("--config <path>", "Custom config path").option("--json", "Output results as JSON").action(async (huntArg, options) => {
+    const huntName = normalizeHuntName(huntArg);
     try {
       if (options.includeTags || options.excludeTags) {
         const { configDir } = loadConfig(options.config);
@@ -6752,7 +7189,7 @@ function buildRunCommand() {
 
 // src/cli/commands/init.ts
 var import_node_fs15 = __toESM(require("fs"), 1);
-var import_node_path15 = __toESM(require("path"), 1);
+var import_node_path16 = __toESM(require("path"), 1);
 var import_node_url2 = require("url");
 var import_commander2 = require("commander");
 var import_chalk4 = __toESM(require("chalk"), 1);
@@ -6760,27 +7197,27 @@ init_loader();
 var import_meta4 = {};
 function getPackageRoot2() {
   const currentFile = (0, import_node_url2.fileURLToPath)(import_meta4.url);
-  let dir = import_node_path15.default.dirname(currentFile);
-  const root = import_node_path15.default.parse(dir).root;
+  let dir = import_node_path16.default.dirname(currentFile);
+  const root = import_node_path16.default.parse(dir).root;
   while (dir !== root) {
-    if (import_node_fs15.default.existsSync(import_node_path15.default.join(dir, "package.json"))) {
+    if (import_node_fs15.default.existsSync(import_node_path16.default.join(dir, "package.json"))) {
       return dir;
     }
-    dir = import_node_path15.default.dirname(dir);
+    dir = import_node_path16.default.dirname(dir);
   }
-  if (import_node_fs15.default.existsSync(import_node_path15.default.join(root, "package.json"))) {
+  if (import_node_fs15.default.existsSync(import_node_path16.default.join(root, "package.json"))) {
     return root;
   }
   throw new Error("Cannot find package root. Reinstall prowl-tools.");
 }
 function copyFile(source, destination) {
-  import_node_fs15.default.mkdirSync(import_node_path15.default.dirname(destination), { recursive: true });
+  import_node_fs15.default.mkdirSync(import_node_path16.default.dirname(destination), { recursive: true });
   import_node_fs15.default.copyFileSync(source, destination);
 }
 function buildInitCommand() {
   const command = new import_commander2.Command("init").option("--force", `Overwrite existing ${CONFIG_DIR} directory`).action((options) => {
     const root = process.cwd();
-    const prowlDir = import_node_path15.default.join(root, CONFIG_DIR);
+    const prowlDir = import_node_path16.default.join(root, CONFIG_DIR);
     if (import_node_fs15.default.existsSync(prowlDir) && !options.force) {
       console.error(
         import_chalk4.default.red(
@@ -6791,20 +7228,20 @@ function buildInitCommand() {
       return;
     }
     const packageRoot = getPackageRoot2();
-    const examplesDir = import_node_path15.default.join(packageRoot, "examples");
-    const exampleConfig = import_node_path15.default.join(examplesDir, "config.yml");
-    const exampleHuntsDir = import_node_path15.default.join(examplesDir, "hunts");
+    const examplesDir = import_node_path16.default.join(packageRoot, "examples");
+    const exampleConfig = import_node_path16.default.join(examplesDir, "config.yml");
+    const exampleHuntsDir = import_node_path16.default.join(examplesDir, "hunts");
     if (!import_node_fs15.default.existsSync(exampleConfig) || !import_node_fs15.default.existsSync(exampleHuntsDir)) {
       console.error(import_chalk4.default.red("Examples not found in package. Reinstall prowl-tools."));
       process.exitCode = 1;
       return;
     }
-    copyFile(exampleConfig, import_node_path15.default.join(prowlDir, "config.yml"));
+    copyFile(exampleConfig, import_node_path16.default.join(prowlDir, "config.yml"));
     const huntFiles = import_node_fs15.default.readdirSync(exampleHuntsDir).filter((f) => f.endsWith(".yml"));
     for (const huntFile of huntFiles) {
       copyFile(
-        import_node_path15.default.join(exampleHuntsDir, huntFile),
-        import_node_path15.default.join(prowlDir, "hunts", huntFile)
+        import_node_path16.default.join(exampleHuntsDir, huntFile),
+        import_node_path16.default.join(prowlDir, "hunts", huntFile)
       );
     }
     const gitignore = [
@@ -6818,27 +7255,27 @@ function buildInitCommand() {
       ".env",
       ""
     ].join("\n");
-    import_node_fs15.default.writeFileSync(import_node_path15.default.join(prowlDir, ".gitignore"), gitignore);
+    import_node_fs15.default.writeFileSync(import_node_path16.default.join(prowlDir, ".gitignore"), gitignore);
     console.log(welcomeBanner());
     console.log(import_chalk4.default.green(`  Initialized ${CONFIG_DIR} directory.`));
     console.log(import_chalk4.default.gray("  Run ") + import_chalk4.default.bold("prowl run hello") + import_chalk4.default.gray(" to get started."));
-    console.log(import_chalk4.default.gray("  Browse hunt templates at ") + import_chalk4.default.cyan("https://hub.prowl.tools") + "\n");
+    console.log(import_chalk4.default.gray("  See ") + import_chalk4.default.cyan(`${CONFIG_DIR}/hunts/login-flow.yml`) + import_chalk4.default.gray(" for a fuller example.") + "\n");
   });
   return command;
 }
 
 // src/cli/commands/login.ts
-var import_node_path16 = __toESM(require("path"), 1);
+var import_node_path17 = __toESM(require("path"), 1);
 var import_node_readline = __toESM(require("readline"), 1);
 var import_chalk5 = __toESM(require("chalk"), 1);
 var import_commander3 = require("commander");
 init_loader();
 function resolvePath2(configDir, inputPath) {
-  if (import_node_path16.default.isAbsolute(inputPath)) {
+  if (import_node_path17.default.isAbsolute(inputPath)) {
     return inputPath;
   }
-  const projectRoot = import_node_path16.default.dirname(configDir);
-  return import_node_path16.default.join(projectRoot, inputPath);
+  const projectRoot = import_node_path17.default.dirname(configDir);
+  return import_node_path17.default.join(projectRoot, inputPath);
 }
 function waitForEnter(prompt) {
   return new Promise((resolve) => {
@@ -6929,14 +7366,15 @@ var import_node_fs16 = __toESM(require("fs"), 1);
 var import_chalk7 = __toESM(require("chalk"), 1);
 var import_commander5 = require("commander");
 init_loader();
+init_hunt_name();
 
 // src/cli/watch-utils.ts
-var import_node_path17 = __toESM(require("path"), 1);
+var import_node_path18 = __toESM(require("path"), 1);
 function getWatchTargets(configDir, huntName) {
   return [
-    import_node_path17.default.join(configDir, "hunts", `${huntName}.yml`),
-    import_node_path17.default.join(configDir, "config.yml"),
-    import_node_path17.default.join(configDir, ".env")
+    import_node_path18.default.join(configDir, "hunts", `${huntName}.yml`),
+    import_node_path18.default.join(configDir, "config.yml"),
+    import_node_path18.default.join(configDir, ".env")
   ];
 }
 function createDebouncer(delayMs, fn) {
@@ -6962,7 +7400,11 @@ function createDebouncer(delayMs, fn) {
 
 // src/cli/commands/watch.ts
 function buildWatchCommand() {
-  const command = new import_commander5.Command("watch").argument("<hunt-name>", "Hunt name or path (e.g. homepage or admin/users-crud)").option("--url <target>", "Override target URL").option("--headed", "Show browser window").option("--slow-mo <ms>", "Slow down Playwright actions", (value) => Number(value)).option("--trace", "Capture Playwright trace").option("--config <path>", "Custom config path").action(async (huntName, options) => {
+  const command = new import_commander5.Command("watch").argument(
+    "<hunt-name>",
+    "Hunt name or path (e.g. homepage, admin/users-crud, or .prowl/hunts/homepage.yml)"
+  ).option("--url <target>", "Override target URL").option("--headed", "Show browser window").option("--slow-mo <ms>", "Slow down Playwright actions", (value) => Number(value)).option("--trace", "Capture Playwright trace").option("--config <path>", "Custom config path").action(async (huntArg, options) => {
+    const huntName = normalizeHuntName(huntArg);
     const { configDir } = loadConfig(options.config);
     const watchTargets = getWatchTargets(configDir, huntName);
     let running = false;
@@ -7038,12 +7480,12 @@ var import_commander6 = require("commander");
 var import_chalk9 = __toESM(require("chalk"), 1);
 
 // src/runner/suite.ts
-var import_node_path20 = __toESM(require("path"), 1);
+var import_node_path21 = __toESM(require("path"), 1);
 init_loader();
 
 // src/reporter/ci-summary.ts
 var import_node_fs17 = __toESM(require("fs"), 1);
-var import_node_path18 = __toESM(require("path"), 1);
+var import_node_path19 = __toESM(require("path"), 1);
 var import_chalk8 = __toESM(require("chalk"), 1);
 function countCiResults(results) {
   return {
@@ -7108,7 +7550,7 @@ function writeCiResult(ciRunDir, results, startedAt, totalDurationMs, flaky = []
     ...clusters.length > 0 ? { clusters } : {}
   };
   import_node_fs17.default.mkdirSync(ciRunDir, { recursive: true });
-  const filePath = import_node_path18.default.join(ciRunDir, "ci-result.json");
+  const filePath = import_node_path19.default.join(ciRunDir, "ci-result.json");
   import_node_fs17.default.writeFileSync(filePath, JSON.stringify(ciResult, null, 2) + "\n");
   return filePath;
 }
@@ -7244,7 +7686,7 @@ function clusterFailures(failures) {
 
 // src/backlog/index.ts
 var import_node_fs18 = __toESM(require("fs"), 1);
-var import_node_path19 = __toESM(require("path"), 1);
+var import_node_path20 = __toESM(require("path"), 1);
 
 // src/backlog/parse.ts
 var MARKER_FP = /<!--\s*prowl:fp=([0-9a-f]+)/;
@@ -7350,7 +7792,7 @@ function buildFailure(hunt) {
   if (!hunt.runDir) return failure;
   let run;
   try {
-    const resultJson = readFileOrEmpty(import_node_path19.default.join(hunt.runDir, "result.json"));
+    const resultJson = readFileOrEmpty(import_node_path20.default.join(hunt.runDir, "result.json"));
     if (!resultJson) return failure;
     run = JSON.parse(resultJson);
   } catch (error) {
@@ -7379,8 +7821,8 @@ function extractFailures(suiteResult) {
 }
 function updateBacklogFromSuite(suiteResult, options = {}) {
   const projectRoot = options.projectRoot ?? process.cwd();
-  const backlogPath = options.backlogPath ?? import_node_path19.default.join(projectRoot, "docs", "backlog.md");
-  const resolvedPath = options.resolvedPath ?? import_node_path19.default.join(projectRoot, "docs", "resolved.md");
+  const backlogPath = options.backlogPath ?? import_node_path20.default.join(projectRoot, "docs", "backlog.md");
+  const resolvedPath = options.resolvedPath ?? import_node_path20.default.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);
@@ -7412,7 +7854,7 @@ function updateBacklogFromSuite(suiteResult, options = {}) {
     }
   }
   if (ticketsToAdd.length > 0) {
-    import_node_fs18.default.mkdirSync(import_node_path19.default.dirname(backlogPath), { recursive: true });
+    import_node_fs18.default.mkdirSync(import_node_path20.default.dirname(backlogPath), { recursive: true });
     import_node_fs18.default.writeFileSync(backlogPath, insertTickets(backlogContent, ticketsToAdd));
   }
   return summary;
@@ -7574,7 +8016,7 @@ async function runSuite(options = {}) {
   const clusters = clusterFailures(
     extractFailures({ result: { hunts: results }, resultPath: null })
   ).filter((cluster) => cluster.count > 1);
-  const ciRunDir = import_node_path20.default.join(configDir, "runs", timestamp("ci"));
+  const ciRunDir = import_node_path21.default.join(configDir, "runs", timestamp("ci"));
   const resultPath = writeCiResult(ciRunDir, results, startedAt, totalDurationMs, flaky, clusters);
   const { passed, failed, skipped } = countCiResults(results);
   return {
@@ -7693,7 +8135,7 @@ function buildCiCommand() {
 
 // src/cli/commands/update-baselines.ts
 var import_node_fs19 = __toESM(require("fs"), 1);
-var import_node_path21 = __toESM(require("path"), 1);
+var import_node_path22 = __toESM(require("path"), 1);
 var import_commander7 = require("commander");
 var import_chalk10 = __toESM(require("chalk"), 1);
 init_loader();
@@ -7701,27 +8143,27 @@ function buildUpdateBaselinesCommand() {
   const command = new import_commander7.Command("update-baselines").description("Accept current screenshots as new visual regression baselines").option("--run <dir>", "Specific run directory to use").option("--name <name>", "Update only a specific baseline by name").option("--config <path>", "Custom config path").option("-y, --yes", "Skip confirmation prompt").action(async (options) => {
     try {
       const { configDir } = loadConfig(options.config);
-      const baselinesDir = import_node_path21.default.join(configDir, "baselines");
+      const baselinesDir = import_node_path22.default.join(configDir, "baselines");
       import_node_fs19.default.mkdirSync(baselinesDir, { recursive: true });
       let runDir;
       if (options.run) {
-        runDir = import_node_path21.default.isAbsolute(options.run) ? options.run : import_node_path21.default.resolve(options.run);
+        runDir = import_node_path22.default.isAbsolute(options.run) ? options.run : import_node_path22.default.resolve(options.run);
       } else {
-        const runsDir = import_node_path21.default.join(configDir, "runs");
+        const runsDir = import_node_path22.default.join(configDir, "runs");
         if (!import_node_fs19.default.existsSync(runsDir)) {
           console.error(import_chalk10.default.red("  No runs directory found. Run a hunt first."));
           process.exitCode = 1;
           return;
         }
-        const entries = import_node_fs19.default.readdirSync(runsDir).filter((e) => import_node_fs19.default.statSync(import_node_path21.default.join(runsDir, e)).isDirectory()).sort().reverse();
+        const entries = import_node_fs19.default.readdirSync(runsDir).filter((e) => import_node_fs19.default.statSync(import_node_path22.default.join(runsDir, e)).isDirectory()).sort().reverse();
         if (entries.length === 0) {
           console.error(import_chalk10.default.red("  No run directories found. Run a hunt first."));
           process.exitCode = 1;
           return;
         }
-        runDir = import_node_path21.default.join(runsDir, entries[0]);
+        runDir = import_node_path22.default.join(runsDir, entries[0]);
       }
-      const screenshotsDir = import_node_path21.default.join(runDir, "screenshots");
+      const screenshotsDir = import_node_path22.default.join(runDir, "screenshots");
       if (!import_node_fs19.default.existsSync(screenshotsDir)) {
         console.error(import_chalk10.default.red(`  No screenshots found in ${runDir}`));
         process.exitCode = 1;
@@ -7741,8 +8183,8 @@ function buildUpdateBaselinesCommand() {
       let updated = 0;
       for (const file of filtered) {
         const baselineName = file.replace("-current.png", ".png");
-        const sourcePath = import_node_path21.default.join(screenshotsDir, file);
-        const destPath = import_node_path21.default.join(baselinesDir, baselineName);
+        const sourcePath = import_node_path22.default.join(screenshotsDir, file);
+        const destPath = import_node_path22.default.join(baselinesDir, baselineName);
         const exists = import_node_fs19.default.existsSync(destPath);
         import_node_fs19.default.copyFileSync(sourcePath, destPath);
         updated++;
@@ -8572,7 +9014,7 @@ function buildAnalyzeCommand() {
 
 // src/cli/commands/generate.ts
 var import_node_fs20 = __toESM(require("fs"), 1);
-var import_node_path22 = __toESM(require("path"), 1);
+var import_node_path23 = __toESM(require("path"), 1);
 var import_commander9 = require("commander");
 var import_chalk12 = __toESM(require("chalk"), 1);
 var import_ora = __toESM(require("ora"), 1);
@@ -8767,12 +9209,12 @@ function buildGenerateCommand() {
             const result = loadConfig2(options.config);
             configDir = result.configDir;
           } catch {
-            configDir = import_node_path22.default.join(process.cwd(), ".prowl");
+            configDir = import_node_path23.default.join(process.cwd(), ".prowl");
           }
-          const huntsDir = import_node_path22.default.join(configDir, "hunts");
+          const huntsDir = import_node_path23.default.join(configDir, "hunts");
           import_node_fs20.default.mkdirSync(huntsDir, { recursive: true });
           const fileName = options.output.endsWith(".yml") ? options.output : `${options.output}.yml`;
-          const filePath = import_node_path22.default.join(huntsDir, fileName);
+          const filePath = import_node_path23.default.join(huntsDir, fileName);
           import_node_fs20.default.writeFileSync(filePath, yamlStr + "\n", "utf-8");
           console.log(import_chalk12.default.green(`  Saved to ${filePath}`));
         } else {
@@ -8797,14 +9239,19 @@ function buildGenerateCommand() {
 var import_commander10 = require("commander");
 var import_chalk13 = __toESM(require("chalk"), 1);
 init_loader();
+init_hunt_name();
 function buildHistoryCommand() {
-  const command = new import_commander10.Command("history").argument("<hunt-name>", "Hunt name or path (e.g. homepage or admin/users-crud)").description("Show run history for a hunt").option("--config <path>", "Custom config path").option("--limit <n>", "Show the last N runs (default: 20)", (value) => {
+  const command = new import_commander10.Command("history").argument(
+    "<hunt-name>",
+    "Hunt name or path (e.g. homepage, admin/users-crud, or .prowl/hunts/homepage.yml)"
+  ).description("Show run history for a hunt").option("--config <path>", "Custom config path").option("--limit <n>", "Show the last N runs (default: 20)", (value) => {
     const n = Number(value);
     if (!Number.isInteger(n) || n < 1) {
       throw new Error("--limit must be a positive integer");
     }
     return n;
-  }).option("--json", "Output as JSON").action((huntName, options) => {
+  }).option("--json", "Output as JSON").action((huntArg, options) => {
+    const huntName = normalizeHuntName(huntArg);
     try {
       const { configDir } = loadConfig(options.config);
       const entries = readHuntHistory(configDir, huntName);
@@ -8970,7 +9417,7 @@ var import_mcp = require("@modelcontextprotocol/sdk/server/mcp.js");
 var import_stdio = require("@modelcontextprotocol/sdk/server/stdio.js");
 
 // src/mcp/tools.ts
-var import_node_path23 = __toESM(require("path"), 1);
+var import_node_path24 = __toESM(require("path"), 1);
 init_loader();
 function listHuntsTool(configPath) {
   const { configDir } = loadConfig(configPath);
@@ -8978,7 +9425,7 @@ function listHuntsTool(configPath) {
 }
 async function runSuiteTool(args = {}, options = {}) {
   const { configPath: resolvedConfigPath, configDir, config } = loadConfig(options.configPath);
-  const projectRoot = options.projectRoot ?? import_node_path23.default.dirname(configDir);
+  const projectRoot = options.projectRoot ?? import_node_path24.default.dirname(configDir);
   const suite = await runSuite({
     configPath: resolvedConfigPath,
     includeTags: args.includeTags,
@@ -8987,8 +9434,8 @@ async function runSuiteTool(args = {}, options = {}) {
   });
   const bugLogCfg = config.bugLog ?? {};
   const logBugs = args.logBugs ?? bugLogCfg.enabled ?? true;
-  const backlogPath = bugLogCfg.backlogPath ? import_node_path23.default.resolve(projectRoot, bugLogCfg.backlogPath) : void 0;
-  const resolvedPath = bugLogCfg.resolvedPath ? import_node_path23.default.resolve(projectRoot, bugLogCfg.resolvedPath) : backlogPath ? import_node_path23.default.join(import_node_path23.default.dirname(backlogPath), "resolved.md") : void 0;
+  const backlogPath = bugLogCfg.backlogPath ? import_node_path24.default.resolve(projectRoot, bugLogCfg.backlogPath) : void 0;
+  const resolvedPath = bugLogCfg.resolvedPath ? import_node_path24.default.resolve(projectRoot, bugLogCfg.resolvedPath) : backlogPath ? import_node_path24.default.join(import_node_path24.default.dirname(backlogPath), "resolved.md") : void 0;
   const bugs = logBugs ? updateBacklogFromSuite(suite, { projectRoot, backlogPath, resolvedPath }) : { created: [], regressions: [], skipped: [], backlogPath: null };
   const { status, totalHunts, passed, failed, skipped } = suite.result;
   return {
@@ -9016,8 +9463,8 @@ async function runHuntTool(args, configPath) {
 
 // src/mcp/projects.ts
 var import_node_fs21 = __toESM(require("fs"), 1);
-var import_node_os3 = __toESM(require("os"), 1);
-var import_node_path24 = __toESM(require("path"), 1);
+var import_node_os5 = __toESM(require("os"), 1);
+var import_node_path25 = __toESM(require("path"), 1);
 var import_yaml3 = __toESM(require("yaml"), 1);
 var import_zod2 = require("zod");
 var projectEntrySchema = import_zod2.z.object({
@@ -9029,25 +9476,25 @@ var projectRegistrySchema = import_zod2.z.object({
   projects: import_zod2.z.record(import_zod2.z.string().min(1), projectEntrySchema)
 }).strict();
 function defaultRegistryPath() {
-  return import_node_path24.default.join(import_node_os3.default.homedir(), ".prowl", "projects.yml");
+  return import_node_path25.default.join(import_node_os5.default.homedir(), ".prowl", "projects.yml");
 }
 function legacyRegistryPath() {
-  return import_node_path24.default.join(import_node_os3.default.homedir(), ".prowlqa", "projects.yml");
+  return import_node_path25.default.join(import_node_os5.default.homedir(), ".prowlqa", "projects.yml");
 }
 function resolveProjectConfigPath(root) {
-  const preferred = import_node_path24.default.join(root, ".prowl", "config.yml");
+  const preferred = import_node_path25.default.join(root, ".prowl", "config.yml");
   if (import_node_fs21.default.existsSync(preferred)) return preferred;
-  const legacy = import_node_path24.default.join(root, ".prowlqa", "config.yml");
+  const legacy = import_node_path25.default.join(root, ".prowlqa", "config.yml");
   if (import_node_fs21.default.existsSync(legacy)) return legacy;
   return preferred;
 }
 function resolveRegistryRelativePath(registry, inputPath) {
-  return import_node_path24.default.isAbsolute(inputPath) ? inputPath : import_node_path24.default.resolve(import_node_path24.default.dirname(registry.registryPath), inputPath);
+  return import_node_path25.default.isAbsolute(inputPath) ? inputPath : import_node_path25.default.resolve(import_node_path25.default.dirname(registry.registryPath), inputPath);
 }
 function resolveRegistryPath(explicitPath) {
-  if (explicitPath) return import_node_path24.default.resolve(explicitPath);
+  if (explicitPath) return import_node_path25.default.resolve(explicitPath);
   const envPath = process.env.PROWL_PROJECTS ?? process.env.PROWLQA_PROJECTS;
-  if (envPath) return import_node_path24.default.resolve(envPath);
+  if (envPath) return import_node_path25.default.resolve(envPath);
   const fallback = defaultRegistryPath();
   if (import_node_fs21.default.existsSync(fallback)) return fallback;
   const legacy = legacyRegistryPath();
@@ -9194,10 +9641,377 @@ function buildMcpCommand() {
   });
 }
 
+// src/cli/commands/macdriver.ts
+var import_chalk15 = __toESM(require("chalk"), 1);
+var import_commander13 = require("commander");
+
+// src/browser/macdriver-install.ts
+var import_node_child_process7 = require("child_process");
+var import_node_crypto3 = require("crypto");
+var import_node_fs22 = __toESM(require("fs"), 1);
+var import_node_os6 = __toESM(require("os"), 1);
+var import_node_path26 = __toESM(require("path"), 1);
+var import_node_util = require("util");
+var execFileAsync = (0, import_node_util.promisify)(import_node_child_process7.execFile);
+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 (0, import_node_crypto3.createHash)("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 (import_node_path26.default.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 ?? import_node_os6.default.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 && import_node_fs22.default.existsSync(binaryPath)) {
+    return { version, binaryPath, alreadyInstalled: true };
+  }
+  const zipBytes = await downloadAndVerify({ version, fetchImpl: options.fetchImpl });
+  import_node_fs22.default.mkdirSync(installRoot, { recursive: true });
+  const stagingDir = import_node_fs22.default.mkdtempSync(import_node_path26.default.join(installRoot, `.tmp-${version}-`));
+  const extractDir = import_node_path26.default.join(stagingDir, "extract");
+  const zipPath = import_node_path26.default.join(stagingDir, macdriverAssetName(version));
+  try {
+    import_node_fs22.default.mkdirSync(extractDir);
+    import_node_fs22.default.writeFileSync(zipPath, zipBytes);
+    validateMacdriverArchiveEntries(await listArchiveEntries(zipPath));
+    await extract(zipPath, extractDir);
+    const stagedBinaryPath = import_node_path26.default.join(extractDir, HELPER_BINARY);
+    assertExtractedHelper(extractDir, stagedBinaryPath);
+    import_node_fs22.default.chmodSync(stagedBinaryPath, 493);
+    await verifySignature(stagedBinaryPath);
+    replaceVersionDir(versionDir, extractDir, installRoot);
+  } finally {
+    import_node_fs22.default.rmSync(stagingDir, { recursive: true, force: true });
+  }
+  return { version, binaryPath, alreadyInstalled: false };
+}
+function assertExtractedHelper(extractDir, binaryPath) {
+  const entries = import_node_fs22.default.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 = import_node_fs22.default.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 = import_node_path26.default.join(installRoot, `.previous-${import_node_path26.default.basename(versionDir)}-${process.pid}-${Date.now()}`);
+  let backedUp = false;
+  try {
+    if (import_node_fs22.default.existsSync(versionDir)) {
+      import_node_fs22.default.renameSync(versionDir, backupDir);
+      backedUp = true;
+    }
+    import_node_fs22.default.renameSync(stagedVersionDir, versionDir);
+    if (backedUp) {
+      import_node_fs22.default.rmSync(backupDir, { recursive: true, force: true });
+    }
+  } catch (error) {
+    if (backedUp && !import_node_fs22.default.existsSync(versionDir) && import_node_fs22.default.existsSync(backupDir)) {
+      import_node_fs22.default.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 ?? import_node_os6.default.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 (import_node_fs22.default.existsSync(root)) {
+    for (const entry of import_node_fs22.default.readdirSync(root, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      let binaryPath;
+      try {
+        binaryPath = macdriverInstalledBinary(entry.name, homedir);
+      } catch {
+        continue;
+      }
+      if (import_node_fs22.default.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) + import_node_path26.default.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.";
+}
+
+// src/cli/commands/macdriver.ts
+function buildInstallCommand() {
+  return new import_commander13.Command("install").description("Download and install the prebuilt, signed prowl-macdriver helper").option("--force", "Reinstall even if the pinned version is already present").action(async (options) => {
+    try {
+      console.log(
+        import_chalk15.default.cyan(
+          `Installing prowl-macdriver ${MACDRIVER_VERSION} (${macdriverReleaseTag(MACDRIVER_VERSION)})\u2026`
+        )
+      );
+      const result = await installMacdriver({ force: options.force });
+      if (result.alreadyInstalled) {
+        console.log(
+          import_chalk15.default.green(`Already installed at ${result.binaryPath}`) + import_chalk15.default.dim(" (use --force to reinstall)")
+        );
+      } else {
+        console.log(import_chalk15.default.green(`Installed prowl-macdriver ${result.version} \u2192 ${result.binaryPath}`));
+      }
+      console.log("");
+      console.log(tccGuidance());
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Install failed";
+      console.error(import_chalk15.default.red(`Error: ${message}`));
+      process.exitCode = 1;
+    }
+  });
+}
+function buildStatusCommand() {
+  return new import_commander13.Command("status").description("Report the resolved prowl-macdriver binary, installed versions, and permissions guidance").action(async () => {
+    try {
+      const status = await collectMacdriverStatus();
+      console.log(import_chalk15.default.bold("prowl-macdriver status"));
+      console.log(`  pinned version:   ${status.pinnedVersion}`);
+      if (status.resolved) {
+        const label = status.resolved.source === "env" ? "PROWL_MACDRIVER_BIN override" : status.resolved.source === "user-install" ? "user install (~/.prowl/macdriver)" : "repo source build (macdriver/.build)";
+        console.log(`  resolved binary:  ${status.resolved.path}`);
+        console.log(`  resolved via:     ${label}`);
+        console.log(
+          `  runs:             ${status.probedVersion ? import_chalk15.default.green(`yes (reports ${status.probedVersion})`) : import_chalk15.default.yellow("no (binary did not respond to `version`)")}`
+        );
+      } else {
+        console.log(`  resolved binary:  ${import_chalk15.default.yellow("none")}`);
+        console.log(import_chalk15.default.dim("  search order: PROWL_MACDRIVER_BIN \u2192 ~/.prowl/macdriver \u2192 macdriver/.build"));
+        console.log(import_chalk15.default.cyan("  Run `prowl macdriver install` to install the prebuilt helper."));
+      }
+      if (status.installed.length > 0) {
+        console.log("  installed versions:");
+        for (const entry of status.installed) {
+          const marker = entry.version === status.pinnedVersion ? import_chalk15.default.green(" (pinned)") : "";
+          console.log(`    - ${entry.version}${marker}  ${import_chalk15.default.dim(entry.binaryPath)}`);
+        }
+      } else {
+        console.log("  installed versions: none");
+      }
+      console.log("");
+      console.log(tccGuidance());
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Status failed";
+      console.error(import_chalk15.default.red(`Error: ${message}`));
+      process.exitCode = 1;
+    }
+  });
+}
+function buildMacdriverCommand() {
+  const command = new import_commander13.Command("macdriver").description(
+    "Manage the macOS helper binary (prowl-macdriver) for the macOS target"
+  );
+  command.addCommand(buildInstallCommand());
+  command.addCommand(buildStatusCommand());
+  return command;
+}
+
 // src/cli/program.ts
 var CLI_VERSION = package_default.version;
 function buildProgram() {
-  const program2 = new import_commander13.Command();
+  const program2 = new import_commander14.Command();
   program2.name("prowl").description("CLI-first QA testing tool for deterministic Playwright flows").version(CLI_VERSION);
   program2.addCommand(buildRunCommand());
   program2.addCommand(buildCiCommand());
@@ -9211,6 +10025,7 @@ function buildProgram() {
   program2.addCommand(buildHistoryCommand());
   program2.addCommand(buildFlakyCommand());
   program2.addCommand(buildMcpCommand());
+  program2.addCommand(buildMacdriverCommand());
   return program2;
 }