prowl-tools 0.1.7 → 0.1.8

package/dist/index.cjs

@@ -398,575 +398,136 @@ 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}`);
-  }
-  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));
-      }
-    }
-  }
-  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
-      }
-    };
-    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));
-    return {
-      match: false,
-      diffPercentage: 1,
-      diffImagePath: diffPath
-    };
-  }
-  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_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.7",
-  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();
-
-// 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 (Array.isArray(input)) {
-    for (const item of input) {
-      collectInterpolatedValues(item, vars, values);
-    }
-    return;
-  }
-  if (input && typeof input === "object") {
-    for (const [key, value] of Object.entries(input)) {
-      collectInterpolatedValues(key, vars, values);
-      collectInterpolatedValues(value, vars, values);
-    }
-  }
-}
-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)];
-  }
-  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 {
-      [interpolateString(key, vars).value]: interpolateString(value, vars).value
-    };
-  };
-  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 ("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 {
-      fill: {
-        [labelResult.value]: valueResult.value
-      }
-    };
-  }
-  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 ("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 ("onDialog" in step) {
-    return { onDialog: { action: step.onDialog.action } };
-  }
-  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 ("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 ("runHunt" in step) {
     if (typeof step.runHunt === "string") {
@@ -1114,95 +675,562 @@ function interpolateStep(step, vars, stepPath2, redacted) {
       }
     };
   }
-  if ("runScript" in step) {
+  if ("runScript" in step) {
+    return {
+      runScript: { file: interpolateString(step.runScript.file, vars).value }
+    };
+  }
+  if ("assertScreenshot" in step) {
+    return {
+      assertScreenshot: {
+        name: interpolateString(step.assertScreenshot.name, vars).value,
+        ...step.assertScreenshot.threshold !== void 0 ? { threshold: step.assertScreenshot.threshold } : {}
+      }
+    };
+  }
+  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
+      }
+    };
+  }
+  if ("waitForDownload" in step) {
+    if (step.waitForDownload === null) {
+      return { waitForDownload: null };
+    }
+    return {
+      waitForDownload: {
+        ...step.waitForDownload.filename !== void 0 ? { filename: interpolateString(step.waitForDownload.filename, vars).value } : {},
+        ...step.waitForDownload.timeout !== void 0 ? { timeout: step.waitForDownload.timeout } : {}
+      }
+    };
+  }
+  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;
+      }
+    }
+    const parent = import_node_path.default.dirname(current);
+    if (parent === current) {
+      break;
+    }
+    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.`);
+    }
+    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 {
+      type: "android",
+      app: androidTarget.app,
+      ...androidTarget.deviceSerial !== void 0 ? { deviceSerial: androidTarget.deviceSerial } : {},
+      ...androidTarget.coldStart !== void 0 ? { coldStart: androidTarget.coldStart } : {}
+    };
+  }
+  if (type === "ios") {
+    const iosTarget = target;
     return {
-      runScript: { file: interpolateString(step.runScript.file, vars).value }
+      type: "ios",
+      app: iosTarget.app,
+      ...iosTarget.udid !== void 0 ? { udid: iosTarget.udid } : {},
+      ...iosTarget.coldStart !== void 0 ? { coldStart: iosTarget.coldStart } : {}
     };
   }
-  if ("assertScreenshot" in step) {
-    return {
-      assertScreenshot: {
-        name: interpolateString(step.assertScreenshot.name, vars).value,
-        ...step.assertScreenshot.threshold !== void 0 ? { threshold: step.assertScreenshot.threshold } : {}
-      }
-    };
+  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 ("assertWithAI" in step) {
-    return {
-      assertWithAI: interpolateString(step.assertWithAI, vars).value
-    };
+  if (Array.isArray(value)) {
+    return value.map((item) => interpolateConfigStrings(item, vars));
   }
-  if ("copyText" in step) {
-    return {
-      copyText: {
-        selector: interpolateString(step.copyText.selector, vars).value,
-        as: step.copyText.as
-      }
-    };
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, item]) => [key, interpolateConfigStrings(item, vars)])
+    );
   }
-  if ("waitForDownload" in step) {
-    if (step.waitForDownload === null) {
-      return { waitForDownload: null };
+  return value;
+}
+function ensureAllowedDomain(allowed, urlValue) {
+  try {
+    const host = new URL(urlValue).hostname;
+    if (!allowed.includes(host)) {
+      return [...allowed, host];
     }
-    return {
-      waitForDownload: {
-        ...step.waitForDownload.filename !== void 0 ? { filename: interpolateString(step.waitForDownload.filename, vars).value } : {},
-        ...step.waitForDownload.timeout !== void 0 ? { timeout: step.waitForDownload.timeout } : {}
-      }
-    };
+  } catch {
+    return allowed;
   }
-  return step;
+  return allowed;
 }
-function interpolateAssertion(assertion, vars) {
-  if ("selectorExists" in assertion) {
-    return { selectorExists: interpolateString(assertion.selectorExists, vars).value };
+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 ("selectorNotExists" in assertion) {
-    return { selectorNotExists: interpolateString(assertion.selectorNotExists, vars).value };
+  if (!import_node_fs.default.existsSync(resolvedPath)) {
+    throw new Error(`Config file not found at ${resolvedPath}`);
   }
-  if ("urlIncludes" in assertion) {
-    return { urlIncludes: interpolateString(assertion.urlIncludes, vars).value };
+  const configDir = import_node_path.default.dirname(resolvedPath);
+  if (import_node_path.default.basename(configDir) === LEGACY_CONFIG_DIR) {
+    warnLegacyConfigDir();
   }
-  if ("urlEquals" in assertion) {
-    return { urlEquals: interpolateString(assertion.urlEquals, vars).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 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
+    );
   }
-  if ("noConsoleErrors" in assertion) {
-    return { noConsoleErrors: assertion.noConsoleErrors };
+  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 ("noNetworkErrors" in assertion) {
-    return { noNetworkErrors: assertion.noNetworkErrors };
+  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 [];
   }
-  return assertion;
+  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 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;
+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));
+      }
+    }
+  }
+  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 }
+    };
+  }
+});
+
+// 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 {
+      match: false,
+      diffPercentage: 1,
+      diffImagePath: diffPath
+    };
   }
-  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");
@@ -1220,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) {
@@ -1259,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) {
@@ -1542,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();
     },
@@ -1736,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);
     },
@@ -2269,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",
@@ -2384,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 -----------------------------------------------------------
@@ -2421,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");
@@ -2894,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") {
@@ -3038,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) {
@@ -3065,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, '\\"');
@@ -3139,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") {
@@ -3170,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) {
@@ -3194,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 });
@@ -3212,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 });
@@ -3230,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) {
@@ -3723,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") {
@@ -4082,6 +4371,7 @@ async function closeIosSession(session) {
 var import_node_fs9 = __toESM(require("fs"), 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"];
@@ -4779,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}`);
     }
@@ -4792,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}`);
     }
@@ -5182,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`
         }
       };
     }
@@ -5246,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({
@@ -5333,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;