prowl-tools 0.1.7 → 0.1.8

package/dist/lib.cjs

@@ -356,6 +356,9 @@ function createMacDriver(client, options = {}) {
     async hover(selector) {
       await query("hover", selector);
     },
+    scroll() {
+      return rejectUnsupported("scroll");
+    },
     async scrollIntoView(selector) {
       await query("scrollTo", selector);
     },
@@ -1258,6 +1261,101 @@ function parseSnapshot(xml) {
   return parseXml(xml);
 }
 
+// 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",
@@ -1373,6 +1471,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 -----------------------------------------------------------
@@ -1410,8 +1513,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");
@@ -1889,6 +2015,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") {
@@ -1925,10 +2058,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) {
@@ -1964,6 +2104,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) {
@@ -2234,6 +2382,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) {
@@ -2254,6 +2403,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, '\\"');
@@ -2328,6 +2478,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") {
@@ -2359,6 +2567,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) {
@@ -2383,15 +2594,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 });
@@ -2401,7 +2635,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 });
@@ -2419,7 +2653,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) {
@@ -2919,12 +3153,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") {
@@ -3619,339 +3870,87 @@ var huntSchema = import_zod.z.object({
   }).strict().optional()
 }).strict();
 
-// src/config/loader.ts
-var DEFAULT_WEB_URL = "http://localhost:3000";
-var 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
-  }
-};
-var CONFIG_DIR = ".prowl";
-var LEGACY_CONFIG_DIR = ".prowlqa";
-var legacyDirWarned = false;
-function warnLegacyConfigDir() {
-  if (legacyDirWarned) {
+// src/config/interpolate.ts
+var import_node_crypto2 = __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;
   }
-  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_path8.default.join(current, dir, "config.yml");
-      if (import_node_fs7.default.existsSync(candidate)) {
-        return candidate;
-      }
+  if (Array.isArray(input)) {
+    for (const item of input) {
+      collectInterpolatedValues(item, vars, values);
     }
-    const parent = import_node_path8.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;
 }
-var VIEWPORT_PRESETS = {
-  mobile: { width: 375, height: 812 },
-  tablet: { width: 768, height: 1024 },
-  desktop: { width: 1280, height: 720 }
-};
-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 };
+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_crypto2.default.randomBytes;
+  const randomUUID = randomSource?.randomUUID ?? import_node_crypto2.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;
-    return {
-      type: "ios",
-      app: iosTarget.app,
-      ...iosTarget.udid !== void 0 ? { udid: iosTarget.udid } : {},
-      ...iosTarget.coldStart !== void 0 ? { coldStart: iosTarget.coldStart } : {}
-    };
-  }
-  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];
-    }
-  } catch {
-    return allowed;
-  }
-  return allowed;
-}
-function loadConfig(configPath) {
-  const resolvedPath = configPath ? import_node_path8.default.resolve(configPath) : findConfigPath(process.cwd());
-  if (!resolvedPath) {
-    throw new Error("Could not find .prowl/config.yml. Run `prowl init` first.");
-  }
-  if (!import_node_fs7.default.existsSync(resolvedPath)) {
-    throw new Error(`Config file not found at ${resolvedPath}`);
-  }
-  const configDir = import_node_path8.default.dirname(resolvedPath);
-  if (import_node_path8.default.basename(configDir) === LEGACY_CONFIG_DIR) {
-    warnLegacyConfigDir();
-  }
-  import_dotenv.default.config({ path: import_node_path8.default.join(configDir, ".env"), override: false });
-  const raw = import_node_fs7.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
-    );
-  }
-  return { config, configPath: resolvedPath, configDir };
-}
-function loadHunt(huntName, configDir) {
-  assertValidHuntName(huntName);
-  const huntPath = import_node_path8.default.join(configDir, "hunts", `${huntName}.yml`);
-  if (!import_node_fs7.default.existsSync(huntPath)) {
-    throw new Error(`Hunt file not found: ${huntPath}`);
-  }
-  const raw = import_node_fs7.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_path8.default.join(configDir, "hunts", `${huntName}.yml`);
-  if (!import_node_fs7.default.existsSync(huntPath)) {
-    return [];
-  }
-  const raw = import_node_fs7.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_path8.default.join(configDir, "hunts", `${huntName}.yml`);
-  if (!import_node_fs7.default.existsSync(huntPath)) {
-    return { tags: [] };
-  }
-  const raw = import_node_fs7.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_path8.default.join(configDir, "hunts");
-  if (!import_node_fs7.default.existsSync(huntsDir)) {
-    return [];
-  }
-  const stats = import_node_fs7.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_fs7.default.readdirSync(dir, { withFileTypes: true });
-    for (const entry of entries) {
-      if (entry.isFile() && entry.name.endsWith(".yml")) {
-        const fullPath = import_node_path8.default.join(dir, entry.name);
-        const relative = import_node_path8.default.relative(huntsDir, fullPath);
-        results.push(relative.replace(/\.yml$/, ""));
-      } else if (entry.isDirectory()) {
-        scanDir(import_node_path8.default.join(dir, entry.name));
-      }
-    }
-  }
-  scanDir(huntsDir);
-  return results.sort((a, b) => a.localeCompare(b));
-}
-
-// src/config/interpolate.ts
-var import_node_crypto2 = __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_crypto2.default.randomBytes;
-  const randomUUID = randomSource?.randomUUID ?? import_node_crypto2.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 ("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)) {
@@ -4242,6 +4241,278 @@ function interpolateHunt(hunt, env, randomVars = generateRandomVars()) {
   };
 }
 
+// src/config/loader.ts
+var DEFAULT_WEB_URL = "http://localhost:3000";
+var 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
+  }
+};
+var CONFIG_DIR = ".prowl";
+var LEGACY_CONFIG_DIR = ".prowlqa";
+var legacyDirWarned = false;
+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_path8.default.join(current, dir, "config.yml");
+      if (import_node_fs7.default.existsSync(candidate)) {
+        return candidate;
+      }
+    }
+    const parent = import_node_path8.default.dirname(current);
+    if (parent === current) {
+      break;
+    }
+    current = parent;
+  }
+  return null;
+}
+var VIEWPORT_PRESETS = {
+  mobile: { width: 375, height: 812 },
+  tablet: { width: 768, height: 1024 },
+  desktop: { width: 1280, height: 720 }
+};
+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 {
+      type: "ios",
+      app: iosTarget.app,
+      ...iosTarget.udid !== void 0 ? { udid: iosTarget.udid } : {},
+      ...iosTarget.coldStart !== void 0 ? { coldStart: iosTarget.coldStart } : {}
+    };
+  }
+  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 (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, item]) => [key, interpolateConfigStrings(item, vars)])
+    );
+  }
+  return value;
+}
+function ensureAllowedDomain(allowed, urlValue) {
+  try {
+    const host = new URL(urlValue).hostname;
+    if (!allowed.includes(host)) {
+      return [...allowed, host];
+    }
+  } catch {
+    return allowed;
+  }
+  return allowed;
+}
+function loadConfig(configPath) {
+  const resolvedPath = configPath ? import_node_path8.default.resolve(configPath) : findConfigPath(process.cwd());
+  if (!resolvedPath) {
+    throw new Error("Could not find .prowl/config.yml. Run `prowl init` first.");
+  }
+  if (!import_node_fs7.default.existsSync(resolvedPath)) {
+    throw new Error(`Config file not found at ${resolvedPath}`);
+  }
+  const configDir = import_node_path8.default.dirname(resolvedPath);
+  if (import_node_path8.default.basename(configDir) === LEGACY_CONFIG_DIR) {
+    warnLegacyConfigDir();
+  }
+  import_dotenv.default.config({ path: import_node_path8.default.join(configDir, ".env"), override: false });
+  const raw = import_node_fs7.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 { config, configPath: resolvedPath, configDir };
+}
+function loadHunt(huntName, configDir) {
+  assertValidHuntName(huntName);
+  const huntPath = import_node_path8.default.join(configDir, "hunts", `${huntName}.yml`);
+  if (!import_node_fs7.default.existsSync(huntPath)) {
+    throw new Error(`Hunt file not found: ${huntPath}`);
+  }
+  const raw = import_node_fs7.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_path8.default.join(configDir, "hunts", `${huntName}.yml`);
+  if (!import_node_fs7.default.existsSync(huntPath)) {
+    return [];
+  }
+  const raw = import_node_fs7.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_path8.default.join(configDir, "hunts", `${huntName}.yml`);
+  if (!import_node_fs7.default.existsSync(huntPath)) {
+    return { tags: [] };
+  }
+  const raw = import_node_fs7.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_path8.default.join(configDir, "hunts");
+  if (!import_node_fs7.default.existsSync(huntsDir)) {
+    return [];
+  }
+  const stats = import_node_fs7.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_fs7.default.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isFile() && entry.name.endsWith(".yml")) {
+        const fullPath = import_node_path8.default.join(dir, entry.name);
+        const relative = import_node_path8.default.relative(huntsDir, fullPath);
+        results.push(relative.replace(/\.yml$/, ""));
+      } else if (entry.isDirectory()) {
+        scanDir(import_node_path8.default.join(dir, entry.name));
+      }
+    }
+  }
+  scanDir(huntsDir);
+  return results.sort((a, b) => a.localeCompare(b));
+}
+
 // src/browser/playwright-driver.ts
 var import_node_fs8 = __toESM(require("fs"), 1);
 var import_node_path9 = __toESM(require("path"), 1);
@@ -4376,6 +4647,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();
     },
@@ -5155,11 +5436,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}`);
     }
@@ -5168,7 +5452,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}`);
     }
@@ -5558,25 +5842,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`
         }
       };
     }
@@ -5622,7 +5902,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({
@@ -5709,7 +5989,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;