prowl-tools 0.1.7 → 0.1.9

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

@@ -2,383 +2,13 @@ import {
   SUPPORTED_BROWSER_ENGINES,
   ensureAllowedDomain,
   huntSchema,
+  interpolateHunt,
   listHunts,
   loadConfig,
   loadHunt,
   loadHuntTags,
   resolveViewport
-} from "./chunk-O3OUTZ2P.js";
-
-// src/config/interpolate.ts
-import crypto from "crypto";
-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 ?? crypto.randomBytes;
-  const randomUUID = randomSource?.randomUUID ?? crypto.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 ("runHunt" in step) {
-    if (typeof step.runHunt === "string") {
-      return { runHunt: interpolateString(step.runHunt, vars).value };
-    }
-    const nameResult = interpolateString(step.runHunt.name, vars);
-    const interpolatedVars = {};
-    for (const [key, value] of Object.entries(step.runHunt.vars ?? {})) {
-      interpolatedVars[key] = interpolateString(value, vars).value;
-    }
-    return {
-      runHunt: {
-        name: nameResult.value,
-        ...Object.keys(interpolatedVars).length > 0 ? { vars: interpolatedVars } : {}
-      }
-    };
-  }
-  if ("assert" in step) {
-    if (step.assert.visible !== void 0) {
-      return { assert: { visible: interpolateString(step.assert.visible, vars).value } };
-    }
-    if (step.assert.notVisible !== void 0) {
-      return { assert: { notVisible: interpolateString(step.assert.notVisible, vars).value } };
-    }
-    if (step.assert.urlIncludes !== void 0) {
-      return { assert: { urlIncludes: interpolateString(step.assert.urlIncludes, vars).value } };
-    }
-    if (step.assert.urlEquals !== void 0) {
-      return { assert: { urlEquals: interpolateString(step.assert.urlEquals, vars).value } };
-    }
-    return step;
-  }
-  if ("wait" in step) {
-    if (typeof step.wait === "string") {
-      return { wait: interpolateString(step.wait, vars).value };
-    }
-    return {
-      wait: {
-        for: interpolateString(step.wait.for, vars).value,
-        timeout: step.wait.timeout
-      }
-    };
-  }
-  if ("waitForSelector" in step) {
-    const selectorResult = interpolateString(step.waitForSelector.selector, vars);
-    return {
-      waitForSelector: {
-        selector: selectorResult.value,
-        timeout: step.waitForSelector.timeout
-      }
-    };
-  }
-  if ("waitForUrl" in step) {
-    const valueResult = interpolateString(step.waitForUrl.value, vars);
-    return {
-      waitForUrl: {
-        value: valueResult.value,
-        timeout: step.waitForUrl.timeout
-      }
-    };
-  }
-  if ("waitForNetworkIdle" in step) {
-    return { waitForNetworkIdle: { timeout: step.waitForNetworkIdle.timeout } };
-  }
-  if ("hover" in step) {
-    const selectorResult = interpolateString(step.hover.selector, vars);
-    return { hover: { selector: selectorResult.value } };
-  }
-  if ("scroll" in step) {
-    return { scroll: { direction: step.scroll.direction, amount: step.scroll.amount } };
-  }
-  if ("scrollTo" in step) {
-    const selectorResult = interpolateString(step.scrollTo.selector, vars);
-    return { scrollTo: { selector: selectorResult.value } };
-  }
-  if ("screenshot" in step) {
-    return { screenshot: { name: step.screenshot.name } };
-  }
-  if ("if" in step) {
-    const condition = step.if;
-    const thenSteps = condition.then.map(
-      (s, i) => interpolateStep(s, vars, `${stepPath2}.if.then.${i}`, redacted)
-    );
-    const elseSteps = condition.else?.map(
-      (s, i) => interpolateStep(s, vars, `${stepPath2}.if.else.${i}`, redacted)
-    );
-    return {
-      if: {
-        ...condition.visible !== void 0 ? { visible: interpolateString(condition.visible, vars).value } : {},
-        ...condition.notVisible !== void 0 ? { notVisible: interpolateString(condition.notVisible, vars).value } : {},
-        then: thenSteps,
-        ...elseSteps !== void 0 ? { else: elseSteps } : {}
-      }
-    };
-  }
-  if ("repeat" in step) {
-    const repeat = step.repeat;
-    const subSteps = repeat.steps.map(
-      (s, i) => interpolateStep(s, vars, `${stepPath2}.repeat.steps.${i}`, redacted)
-    );
-    return {
-      repeat: {
-        ...repeat.times !== void 0 ? { times: repeat.times } : {},
-        ...repeat.while !== void 0 ? {
-          while: {
-            ...repeat.while.visible !== void 0 ? { visible: interpolateString(repeat.while.visible, vars).value } : {},
-            ...repeat.while.notVisible !== void 0 ? { notVisible: interpolateString(repeat.while.notVisible, vars).value } : {}
-          }
-        } : {},
-        ...repeat.maxIterations !== void 0 ? { maxIterations: repeat.maxIterations } : {},
-        steps: subSteps
-      }
-    };
-  }
-  if ("mockRoute" in step) {
-    const mock = step.mockRoute;
-    return {
-      mockRoute: {
-        url: interpolateString(mock.url, vars).value,
-        response: {
-          status: mock.response.status,
-          ...mock.response.contentType !== void 0 ? { contentType: interpolateString(mock.response.contentType, vars).value } : {},
-          ...mock.response.body !== void 0 ? { body: interpolateString(mock.response.body, vars).value } : {},
-          ...mock.response.file !== void 0 ? { file: interpolateString(mock.response.file, vars).value } : {}
-        }
-      }
-    };
-  }
-  if ("unmockRoute" in step) {
-    if (typeof step.unmockRoute === "string") {
-      return { unmockRoute: interpolateString(step.unmockRoute, vars).value };
-    }
-    return {
-      unmockRoute: { url: interpolateString(step.unmockRoute.url, vars).value }
-    };
-  }
-  if ("evalScript" in step) {
-    if (typeof step.evalScript === "string") {
-      return { evalScript: interpolateString(step.evalScript, vars).value };
-    }
-    return {
-      evalScript: {
-        expression: interpolateString(step.evalScript.expression, vars).value,
-        ...step.evalScript.as !== void 0 ? { as: step.evalScript.as } : {}
-      }
-    };
-  }
-  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]
-  };
-}
+} from "./chunk-JFJQNJSJ.js";
 
 // src/config/target.ts
 import { execFileSync } from "child_process";
@@ -396,10 +26,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) {
@@ -435,6 +72,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) {
@@ -689,6 +334,9 @@ function createMacDriver(client, options = {}) {
     async hover(selector) {
       await query("hover", selector);
     },
+    scroll() {
+      return rejectUnsupported("scroll");
+    },
     async scrollIntoView(selector) {
       await query("scrollTo", selector);
     },
@@ -851,10 +499,15 @@ ${macdriverBuildInstructions()}`
 ${macdriverBuildInstructions()}`);
 }
 var DEFAULT_REQUEST_TIMEOUT_MS = 3e4;
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
 var SpawnMacHelperClient = class {
   child;
   pending = /* @__PURE__ */ new Map();
   requestTimeoutMs;
+  onEvent;
+  onEventError;
   stdoutBuffer = "";
   stderrBuffer = "";
   nextId = 1;
@@ -862,6 +515,9 @@ var SpawnMacHelperClient = class {
   terminalError;
   constructor(binaryPath, options = {}) {
     this.requestTimeoutMs = options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+    this.onEvent = options.onEvent;
+    this.onEventError = options.onEventError ?? ((message) => process.stderr.write(`${message}
+`));
     this.child = spawn(binaryPath, ["serve"], { stdio: ["pipe", "pipe", "pipe"] });
     this.child.stdout?.setEncoding("utf-8");
     this.child.stderr?.setEncoding("utf-8");
@@ -898,6 +554,10 @@ var SpawnMacHelperClient = class {
     } catch {
       return;
     }
+    if (typeof message.event === "string" && typeof message.id !== "number") {
+      this.handleEvent(message);
+      return;
+    }
     const id = typeof message.id === "number" ? message.id : void 0;
     if (id === void 0) {
       return;
@@ -914,6 +574,18 @@ var SpawnMacHelperClient = class {
       pending.reject(new Error(typeof message.error === "string" ? message.error : "prowl-macdriver error"));
     }
   }
+  handleEvent(event) {
+    try {
+      this.onEvent?.(event);
+    } catch (error) {
+      try {
+        this.onEventError(
+          `prowl-macdriver event sink failed for event "${event.event}": ${errorMessage(error)}`
+        );
+      } catch {
+      }
+    }
+  }
   failAll(error) {
     for (const pending of this.pending.values()) {
       clearTimeout(pending.timer);
@@ -1295,6 +967,103 @@ function parseSnapshot(xml) {
 
 // src/browser/android-driver.ts
 import fs3 from "fs";
+
+// 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",
   "interact",
@@ -1409,6 +1178,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 -----------------------------------------------------------
@@ -1446,8 +1220,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");
@@ -1919,6 +1716,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") {
@@ -2066,6 +1870,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) {
@@ -2086,6 +1891,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, '\\"');
@@ -2160,6 +1966,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") {
@@ -2191,6 +2055,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) {
@@ -2215,15 +2082,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 });
@@ -2233,7 +2123,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 });
@@ -2251,7 +2141,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) {
@@ -2744,12 +2634,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") {
@@ -3404,6 +3311,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();
     },
@@ -4129,11 +4046,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}`);
     }
@@ -4142,7 +4062,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}`);
     }
@@ -4532,25 +4452,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`
         }
       };
     }
@@ -4596,7 +4512,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({
@@ -4683,7 +4599,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;
@@ -7433,7 +7349,6 @@ function tccGuidance() {
 }
 
 export {
-  interpolateHunt,
   WEB_ONLY_STEP_TYPES,
   webOnlyReason,
   assertStepsSupportedByTarget,
@@ -7591,4 +7506,4 @@ export {
   collectMacdriverStatus,
   tccGuidance
 };
-//# sourceMappingURL=chunk-R7NUH44M.js.map
+//# sourceMappingURL=chunk-2RNOK64Y.js.map