@vostride/agent-qa-web 0.0.1 → 0.1.1

package/dist/index.cjs

@@ -0,0 +1,2049 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  ActionValidationError: () => ActionValidationError,
+  ElementResolver: () => ElementResolver,
+  FarmWebAdapter: () => FarmWebAdapter,
+  WebPlatformAdapter: () => WebPlatformAdapter,
+  extractDom: () => extractDom,
+  observePage: () => observePage,
+  parseAriaSnapshot: () => parseAriaSnapshot,
+  runAccessibilityCheck: () => runAccessibilityCheck,
+  validateAction: () => validateAction,
+  waitForPageReady: () => waitForPageReady
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/adapter.ts
+var import_agent_qa_core = require("@vostride/agent-qa-core");
+
+// src/dom-extractor.ts
+var SKIP_TAGS = /* @__PURE__ */ new Set([
+  "SCRIPT",
+  "STYLE",
+  "SVG",
+  "NOSCRIPT",
+  "LINK",
+  "META",
+  "TEMPLATE",
+  "IFRAME"
+]);
+function extractDomTree(opts) {
+  const { maxDepth, maxTextLen } = opts;
+  const doc = globalThis.document;
+  const win = globalThis.window;
+  const lines = [];
+  function isHidden(el) {
+    if (!el.offsetParent && el.tagName !== "BODY" && el.tagName !== "HTML") {
+      const style = win.getComputedStyle(el);
+      if (style.display === "none" || style.visibility === "hidden") return true;
+    }
+    return false;
+  }
+  function walk(node, depth, indent) {
+    if (depth > maxDepth) {
+      lines.push(indent + "[... deeper content truncated]");
+      return;
+    }
+    for (let child = node.firstChild; child; child = child.nextSibling) {
+      if (child.nodeType === 3) {
+        const text = child.textContent.trim();
+        if (text) {
+          const truncated = text.length > maxTextLen ? text.slice(0, maxTextLen) + "..." : text;
+          lines.push(indent + truncated);
+        }
+        continue;
+      }
+      if (child.nodeType !== 1) continue;
+      const tag = child.tagName;
+      if (SKIP_TAGS.has(tag)) continue;
+      if (isHidden(child)) continue;
+      const isCustom = tag.toLowerCase().includes("-");
+      const annotation = child.getAttribute("aria-label") || child.getAttribute("role") || "";
+      let label = tag.toLowerCase();
+      if (isCustom) {
+        if (!child.shadowRoot && !child.firstChild) {
+          label += " (custom element, closed shadow root)";
+        } else {
+          label += " (custom element)";
+        }
+      }
+      if (annotation) label += ` [${annotation}]`;
+      lines.push(indent + label);
+      if (child.shadowRoot) {
+        lines.push(indent + "  #shadow-root");
+        walk(child.shadowRoot, depth + 1, indent + "    ");
+      }
+      walk(child, depth + 1, indent + "  ");
+    }
+  }
+  walk(doc.body, 0, "");
+  return lines.join("\n");
+}
+async function extractDom(page, opts) {
+  const maxDepth = opts?.maxDepth ?? 20;
+  const maxTextLen = opts?.maxTextLen ?? 200;
+  try {
+    return await page.evaluate(extractDomTree, { maxDepth, maxTextLen });
+  } catch {
+    return void 0;
+  }
+}
+
+// src/observer.ts
+var INTERACTIVE_ROLES = /* @__PURE__ */ new Set([
+  "button",
+  "link",
+  "textbox",
+  "checkbox",
+  "radio",
+  "combobox",
+  "listbox",
+  "menuitem",
+  "menuitemradio",
+  "menuitemcheckbox",
+  "option",
+  "searchbox",
+  "slider",
+  "spinbutton",
+  "switch",
+  "tab",
+  "treeitem",
+  // WAI-ARIA 1.2 standalone widget roles
+  "gridcell",
+  "scrollbar",
+  "separator",
+  // WAI-ARIA 1.2 composite widget roles (interactive containers)
+  "grid",
+  "menu",
+  "menubar",
+  "tree",
+  "treegrid"
+]);
+var CONTENT_ROLES = /* @__PURE__ */ new Set([
+  "heading",
+  "cell",
+  "listitem",
+  "article",
+  "region",
+  "navigation",
+  "progressbar",
+  "tabpanel"
+]);
+var LINE_PATTERN = /^(\s*-\s*)(\w+)(?:\s+"([^"]*)")?(.*)$/;
+var QUOTED_LINE_PATTERN = /^(\s*-\s*)'(\w+)(?:\s+"([^"]*)")?(.*)'\s*$/;
+function parseAriaSnapshot(ariaTree) {
+  const lines = ariaTree.split("\n");
+  const elements = [];
+  const refs = {};
+  const resultLines = [];
+  let refCounter = 0;
+  const roleNameCounts = /* @__PURE__ */ new Map();
+  const refToKey = /* @__PURE__ */ new Map();
+  for (const line of lines) {
+    const match = line.match(LINE_PATTERN) || line.match(QUOTED_LINE_PATTERN);
+    if (!match) {
+      resultLines.push(line);
+      continue;
+    }
+    const [, prefix, role, name, suffix] = match;
+    const roleLower = role.toLowerCase();
+    const shouldGetRef = INTERACTIVE_ROLES.has(roleLower) || CONTENT_ROLES.has(roleLower);
+    if (!shouldGetRef) {
+      resultLines.push(line);
+      continue;
+    }
+    refCounter++;
+    const ref = `e${refCounter}`;
+    const key = `${roleLower}:${name ?? ""}`;
+    const currentCount = roleNameCounts.get(key) ?? 0;
+    roleNameCounts.set(key, currentCount + 1);
+    refToKey.set(ref, key);
+    refs[ref] = { role: roleLower, name, nth: currentCount };
+    const attributes = {};
+    const attrMatches = suffix?.matchAll(/\[(\w+)(?:=([^\]]*))?\]/g);
+    if (attrMatches) {
+      for (const am of attrMatches) {
+        attributes[am[1]] = am[2] ?? "true";
+      }
+    }
+    elements.push({ ref, role: roleLower, name: name ?? "", attributes });
+    let enhanced = `${prefix}${role}`;
+    if (name) enhanced += ` "${name}"`;
+    enhanced += ` [ref=${ref}]`;
+    if (suffix?.trim()) enhanced += suffix;
+    resultLines.push(enhanced);
+  }
+  for (const [ref, data] of Object.entries(refs)) {
+    const key = refToKey.get(ref);
+    if ((roleNameCounts.get(key) ?? 0) <= 1) {
+      delete refs[ref].nth;
+    }
+  }
+  return { tree: resultLines.join("\n"), elements, refs };
+}
+function hideAgentQaElements() {
+  const doc = globalThis.document;
+  doc.querySelectorAll("[data-agent-qa-internal]").forEach((el) => {
+    el.style.display = "none";
+    el.setAttribute("aria-hidden", "true");
+  });
+}
+function restoreAgentQaElements() {
+  const doc = globalThis.document;
+  doc.querySelectorAll("[data-agent-qa-internal]").forEach((el) => {
+    el.style.display = "";
+    el.removeAttribute("aria-hidden");
+  });
+}
+async function observePage(page, options) {
+  const viewport = page.viewportSize();
+  const locator = options?.filterSelector ? page.locator(options.filterSelector) : page.locator(":root");
+  await page.evaluate(hideAgentQaElements);
+  let ariaTree;
+  try {
+    ariaTree = await locator.ariaSnapshot();
+  } finally {
+    await page.evaluate(restoreAgentQaElements);
+  }
+  if (!ariaTree) {
+    return {
+      tree: "(empty)",
+      elements: [],
+      url: page.url(),
+      timestamp: Date.now(),
+      metadata: {
+        coordSpace: "viewport",
+        viewportWidth: viewport?.width ?? 0,
+        viewportHeight: viewport?.height ?? 0,
+        refMap: {}
+      }
+    };
+  }
+  const { tree, elements, refs } = parseAriaSnapshot(ariaTree);
+  try {
+    const refEntries = Object.entries(refs);
+    if (refEntries.length > 0) {
+      const refArgs = refEntries.map(
+        ([ref, data]) => [ref, data.role, data.name, data.nth]
+      );
+      const result = await Promise.race([
+        page.evaluate((args) => {
+          const doc = globalThis.document;
+          const IMPLICIT_ROLES = {
+            button: "button",
+            a: "link",
+            input: "textbox",
+            select: "combobox",
+            textarea: "textbox",
+            h1: "heading",
+            h2: "heading",
+            h3: "heading",
+            h4: "heading",
+            h5: "heading",
+            h6: "heading",
+            nav: "navigation",
+            main: "main",
+            aside: "complementary",
+            footer: "contentinfo",
+            header: "banner",
+            form: "form",
+            table: "table",
+            img: "img",
+            ul: "list",
+            ol: "list",
+            li: "listitem",
+            dialog: "dialog",
+            details: "group",
+            summary: "button",
+            progress: "progressbar",
+            meter: "meter",
+            output: "status",
+            article: "article",
+            section: "region",
+            fieldset: "group",
+            legend: "legend"
+          };
+          const INPUT_TYPE_ROLES = {
+            checkbox: "checkbox",
+            radio: "radio",
+            range: "slider",
+            number: "spinbutton",
+            search: "searchbox",
+            email: "textbox",
+            tel: "textbox",
+            url: "textbox",
+            password: "textbox"
+          };
+          function getAccessibleName(el) {
+            const label = el.getAttribute("aria-label");
+            if (label) return label.trim();
+            const labelledBy = el.getAttribute("aria-labelledby");
+            if (labelledBy) {
+              const parts = labelledBy.split(/\s+/).map((id) => {
+                const ref = doc.getElementById(id);
+                return ref ? (ref.textContent || "").trim() : "";
+              }).filter(Boolean);
+              if (parts.length) return parts.join(" ");
+            }
+            const title = el.getAttribute("title");
+            if (title) return title.trim();
+            const alt = el.getAttribute("alt");
+            if (alt) return alt.trim();
+            return (el.textContent || "").trim();
+          }
+          function matchesName(elName, targetName) {
+            return elName.toLowerCase().includes(targetName.toLowerCase());
+          }
+          function getImplicitRole(el) {
+            const tag = el.tagName.toLowerCase();
+            if (tag === "input") {
+              const type = (el.getAttribute("type") || "text").toLowerCase();
+              return INPUT_TYPE_ROLES[type] || "textbox";
+            }
+            if (tag === "a" && el.hasAttribute("href")) return "link";
+            return IMPLICIT_ROLES[tag] || null;
+          }
+          const results = [];
+          for (const [ref, role, name, nth] of args) {
+            const candidates = [];
+            doc.querySelectorAll(`[role="${role}"]`).forEach((el) => candidates.push(el));
+            doc.querySelectorAll("*").forEach((el) => {
+              if (el.getAttribute("role")) return;
+              if (getImplicitRole(el) === role) candidates.push(el);
+            });
+            let matched = candidates;
+            if (name) {
+              matched = candidates.filter((el) => matchesName(getAccessibleName(el), name));
+            }
+            const target = matched[nth ?? 0];
+            if (target) {
+              const rect = target.getBoundingClientRect();
+              results.push([ref, {
+                x: Math.round(rect.x),
+                y: Math.round(rect.y),
+                width: Math.round(rect.width),
+                height: Math.round(rect.height)
+              }]);
+            } else {
+              results.push([ref, null]);
+            }
+          }
+          return results;
+        }, refArgs),
+        new Promise((resolve) => setTimeout(() => resolve(null), 3e3))
+      ]);
+      if (result) {
+        for (const [ref, box] of result) {
+          if (box) refs[ref].bounds = box;
+        }
+      }
+    }
+  } catch {
+  }
+  let domContext;
+  if (options?.extractDom) {
+    try {
+      domContext = await extractDom(page);
+    } catch {
+    }
+  }
+  return {
+    tree,
+    elements,
+    url: page.url(),
+    timestamp: Date.now(),
+    metadata: {
+      coordSpace: "viewport",
+      viewportWidth: viewport?.width ?? 0,
+      viewportHeight: viewport?.height ?? 0,
+      refMap: refs,
+      ...domContext ? { domContext } : {}
+    }
+  };
+}
+
+// src/element-resolver.ts
+var ACTIONS_WITHOUT_REF = /* @__PURE__ */ new Set(["navigate", "waitFor", "delay", "waitForUrl", "assert"]);
+var ElementResolver = class {
+  constructor(page, refs) {
+    this.page = page;
+    this.refs = refs;
+  }
+  resolve(ref) {
+    const data = this.refs[ref];
+    if (!data) {
+      throw new Error(`Unknown ref "${ref}". Available refs: ${Object.keys(this.refs).join(", ") || "none"}`);
+    }
+    let locator;
+    if (data.name) {
+      locator = this.page.getByRole(data.role, { name: data.name, exact: true });
+    } else {
+      locator = this.page.getByRole(data.role);
+    }
+    if (data.nth !== void 0) {
+      locator = locator.nth(data.nth);
+    }
+    return locator;
+  }
+  resolveAction(action) {
+    if (ACTIONS_WITHOUT_REF.has(action.type)) {
+      return null;
+    }
+    if ("ref" in action && typeof action.ref === "string") {
+      return this.resolve(action.ref);
+    }
+    return null;
+  }
+  async getBoundingBox(ref) {
+    try {
+      const locator = this.resolve(ref);
+      return await locator.boundingBox();
+    } catch {
+      return null;
+    }
+  }
+};
+
+// src/action-validator.ts
+var ActionValidationError = class extends Error {
+  suggestion;
+  constructor(message, suggestion) {
+    super(message);
+    this.name = "ActionValidationError";
+    this.suggestion = suggestion;
+  }
+};
+var FILL_ROLES = /* @__PURE__ */ new Set(["textbox", "searchbox", "spinbutton", "combobox"]);
+var SELECT_ROLES = /* @__PURE__ */ new Set(["listbox", "combobox"]);
+var NO_REF_ACTIONS = /* @__PURE__ */ new Set(["scroll", "navigate", "waitFor", "delay", "waitForUrl", "assert", "pinch", "multiTap", "keyDown", "keyUp", "refresh", "navigateHistory", "readConsoleLogs", "readNetworkLogs", "readCookies", "setCookies", "readLocalStorage", "setLocalStorage", "executeScript"]);
+var ANY_ROLE_ACTIONS = /* @__PURE__ */ new Set(["click", "hover", "keypress", "paste", "doubleClick", "rightClick"]);
+function validateAction(action, elementRole) {
+  if (NO_REF_ACTIONS.has(action.type)) {
+    return { valid: true };
+  }
+  if (ANY_ROLE_ACTIONS.has(action.type)) {
+    return { valid: true };
+  }
+  if (!elementRole) {
+    return { valid: true };
+  }
+  const role = elementRole.toLowerCase();
+  if (action.type === "fill") {
+    if (FILL_ROLES.has(role)) {
+      return { valid: true };
+    }
+    if (SELECT_ROLES.has(role)) {
+      return {
+        valid: false,
+        error: `Cannot fill() on a '${role}' element \u2014 fill is for text inputs. Try 'select' to choose an option.`,
+        suggestion: "select"
+      };
+    }
+    return {
+      valid: false,
+      error: `Element ${action.ref} is not fillable (role: ${role}). Use a textbox or input element instead.`,
+      suggestion: "click"
+    };
+  }
+  if (action.type === "clearText") {
+    if (FILL_ROLES.has(role)) {
+      return { valid: true };
+    }
+    return {
+      valid: false,
+      error: `Element ${action.ref} is not fillable (role: ${role}). clearText only works on text inputs. Use a textbox or input element instead.`,
+      suggestion: "click"
+    };
+  }
+  if (action.type === "select") {
+    if (SELECT_ROLES.has(role)) {
+      return { valid: true };
+    }
+    if (FILL_ROLES.has(role)) {
+      return {
+        valid: false,
+        error: `Cannot select() on a '${role}' element \u2014 select is for lists. Try 'fill' to type a value instead.`,
+        suggestion: "fill"
+      };
+    }
+    return {
+      valid: false,
+      error: `Cannot select() on a '${role}' element \u2014 select is for list/combo elements.`,
+      suggestion: "click"
+    };
+  }
+  return { valid: true };
+}
+
+// src/smart-wait.ts
+var LOADING_SELECTORS = [
+  '[aria-busy="true"]',
+  '[aria-label*="loading" i]',
+  ".loading",
+  ".spinner",
+  ".skeleton",
+  "[data-loading]",
+  '[data-testid="loading"]',
+  "progress:not([value])"
+];
+async function waitForPageReady(page, options) {
+  const timeout = options?.timeout ?? 1e4;
+  await Promise.race([
+    runReadinessChecks(page),
+    new Promise((resolve) => setTimeout(resolve, timeout))
+  ]);
+}
+function checkLoadingIndicators(selectors) {
+  const doc = globalThis.document;
+  return selectors.some((sel) => doc.querySelector(sel) !== null);
+}
+function checkLoadingGone(selectors) {
+  const doc = globalThis.document;
+  return !selectors.some((sel) => doc.querySelector(sel));
+}
+function checkAnimationsRunning() {
+  const doc = globalThis.document;
+  return doc.getAnimations().filter((a) => a.playState === "running").length > 0;
+}
+function checkAnimationsSettled() {
+  const doc = globalThis.document;
+  return doc.getAnimations().filter((a) => a.playState === "running").length === 0;
+}
+async function runReadinessChecks(page) {
+  try {
+    await page.waitForLoadState("domcontentloaded", { timeout: 5e3 });
+  } catch {
+  }
+  try {
+    await page.waitForLoadState("networkidle", { timeout: 5e3 });
+  } catch {
+  }
+  try {
+    const hasIndicators = await page.evaluate(checkLoadingIndicators, LOADING_SELECTORS);
+    if (hasIndicators) {
+      try {
+        await page.waitForFunction(checkLoadingGone, LOADING_SELECTORS, { timeout: 3e3 });
+      } catch {
+      }
+    }
+  } catch {
+  }
+  try {
+    const hasRunning = await page.evaluate(checkAnimationsRunning);
+    if (hasRunning) {
+      try {
+        await page.waitForFunction(checkAnimationsSettled, void 0, { timeout: 2e3 });
+      } catch {
+      }
+    }
+  } catch {
+  }
+}
+
+// src/scroll-helper.ts
+async function scrollWithRef(page, refData, deltaX, deltaY, scrollAxis) {
+  return page.evaluate(
+    (args) => {
+      const [role, name, nth, dx, dy, axis] = args;
+      const doc = globalThis.document;
+      const win = globalThis.window;
+      const IMPLICIT_ROLES = {
+        button: "button",
+        a: "link",
+        input: "textbox",
+        select: "combobox",
+        textarea: "textbox",
+        h1: "heading",
+        h2: "heading",
+        h3: "heading",
+        h4: "heading",
+        h5: "heading",
+        h6: "heading",
+        nav: "navigation",
+        main: "main",
+        aside: "complementary",
+        footer: "contentinfo",
+        header: "banner",
+        form: "form",
+        table: "table",
+        img: "img",
+        ul: "list",
+        ol: "list",
+        li: "listitem",
+        dialog: "dialog",
+        details: "group",
+        summary: "button",
+        progress: "progressbar",
+        meter: "meter",
+        output: "status",
+        article: "article",
+        section: "region",
+        fieldset: "group",
+        legend: "legend"
+      };
+      const INPUT_TYPE_ROLES = {
+        checkbox: "checkbox",
+        radio: "radio",
+        range: "slider",
+        number: "spinbutton",
+        search: "searchbox",
+        email: "textbox",
+        tel: "textbox",
+        url: "textbox",
+        password: "textbox"
+      };
+      function getAccessibleName(el) {
+        const label = el.getAttribute("aria-label");
+        if (label) return label.trim();
+        const labelledBy = el.getAttribute("aria-labelledby");
+        if (labelledBy) {
+          const parts = labelledBy.split(/\s+/).map((id) => {
+            const ref = doc.getElementById(id);
+            return ref ? (ref.textContent || "").trim() : "";
+          }).filter(Boolean);
+          if (parts.length) return parts.join(" ");
+        }
+        const title = el.getAttribute("title");
+        if (title) return title.trim();
+        const alt = el.getAttribute("alt");
+        if (alt) return alt.trim();
+        return (el.textContent || "").trim();
+      }
+      function getImplicitRole(el) {
+        const tag = el.tagName.toLowerCase();
+        if (tag === "input") {
+          const type = (el.getAttribute("type") || "text").toLowerCase();
+          return INPUT_TYPE_ROLES[type] || "textbox";
+        }
+        if (tag === "a" && el.hasAttribute("href")) return "link";
+        return IMPLICIT_ROLES[tag] || null;
+      }
+      const candidates = [];
+      doc.querySelectorAll(`[role="${role}"]`).forEach((el) => candidates.push(el));
+      doc.querySelectorAll("*").forEach((el) => {
+        if (el.getAttribute("role")) return;
+        if (getImplicitRole(el) === role) candidates.push(el);
+      });
+      let matched = candidates;
+      if (name) {
+        matched = candidates.filter(
+          (el) => getAccessibleName(el).toLowerCase().includes(name.toLowerCase())
+        );
+      }
+      const target = matched[nth];
+      if (!target) {
+        win.scrollBy(dx, dy);
+        return { bounds: null, scrolledContainer: "notFound", scrolled: true };
+      }
+      const targetStyle = win.getComputedStyle(target);
+      const targetOverflow = axis === "horizontal" ? targetStyle.overflowX : targetStyle.overflowY;
+      const targetScrollable = targetOverflow === "auto" || targetOverflow === "scroll" || targetOverflow === "hidden";
+      const targetHasContent = axis === "horizontal" ? target.scrollWidth > target.clientWidth : target.scrollHeight > target.clientHeight;
+      if (targetScrollable && targetHasContent) {
+        const prop2 = axis === "horizontal" ? "scrollLeft" : "scrollTop";
+        const before2 = target[prop2];
+        target.scrollBy(dx, dy);
+        const after2 = target[prop2];
+        const rect2 = target.getBoundingClientRect();
+        return {
+          bounds: { x: Math.round(rect2.x), y: Math.round(rect2.y), width: Math.round(rect2.width), height: Math.round(rect2.height) },
+          scrolledContainer: "element",
+          scrolled: before2 !== after2
+        };
+      }
+      let parent = target.parentElement;
+      while (parent && parent !== doc.documentElement) {
+        const style = win.getComputedStyle(parent);
+        const overflow = axis === "horizontal" ? style.overflowX : style.overflowY;
+        const isScrollable = overflow === "auto" || overflow === "scroll" || overflow === "hidden";
+        const hasContent = axis === "horizontal" ? parent.scrollWidth > parent.clientWidth : parent.scrollHeight > parent.clientHeight;
+        if (isScrollable && hasContent) {
+          const prop2 = axis === "horizontal" ? "scrollLeft" : "scrollTop";
+          const before2 = parent[prop2];
+          parent.scrollBy(dx, dy);
+          const after2 = parent[prop2];
+          const rect2 = target.getBoundingClientRect();
+          return {
+            bounds: { x: Math.round(rect2.x), y: Math.round(rect2.y), width: Math.round(rect2.width), height: Math.round(rect2.height) },
+            scrolledContainer: "ancestor",
+            scrolled: before2 !== after2
+          };
+        }
+        parent = parent.parentElement;
+      }
+      const prop = axis === "horizontal" ? "scrollLeft" : "scrollTop";
+      const before = doc.documentElement[prop];
+      doc.documentElement.scrollBy(dx, dy);
+      const after = doc.documentElement[prop];
+      const rect = target.getBoundingClientRect();
+      return {
+        bounds: { x: Math.round(rect.x), y: Math.round(rect.y), width: Math.round(rect.width), height: Math.round(rect.height) },
+        scrolledContainer: "documentElement",
+        scrolled: before !== after
+      };
+    },
+    [refData.role, refData.name, refData.nth ?? 0, deltaX, deltaY, scrollAxis]
+  );
+}
+
+// src/browser-install-error.ts
+function displayBrowserName(browserName) {
+  if (browserName === "chromium") return "Chromium";
+  if (browserName === "firefox") return "Firefox";
+  return "WebKit";
+}
+function isPlaywrightMissingBrowserError(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  const lower = message.toLowerCase();
+  return lower.includes("executable doesn't exist") && lower.includes("playwright") && lower.includes("install");
+}
+function formatMissingBrowserError(browserName) {
+  return [
+    `agent-qa browser support is not installed for ${displayBrowserName(browserName)}.`,
+    "",
+    "Install the browser managed by agent-qa, then rerun the test:",
+    `  agent-qa install-browsers --${browserName}`,
+    "",
+    "This can happen after upgrading agent-qa or Playwright because browser binaries live outside the package install."
+  ].join("\n");
+}
+
+// src/adapter.ts
+function clickDelayOption(clickDelay) {
+  return clickDelay !== void 0 && clickDelay > 0 ? { delay: clickDelay } : {};
+}
+var WebPlatformAdapter = class {
+  platform = "web";
+  browser = null;
+  context = null;
+  page = null;
+  lastRefs = {};
+  pageLogBuffers = /* @__PURE__ */ new Map();
+  logCaptureConfig = { console: true, network: true };
+  disconnected = false;
+  intentionalClose = false;
+  async setup(config) {
+    const { chromium, firefox, webkit } = await import("playwright-core");
+    const launchers = { chromium, firefox, webkit };
+    const browserName = config.browser?.name ?? "chromium";
+    const launcher = launchers[browserName];
+    try {
+      this.browser = await launcher.launch({
+        headless: config.browser?.headless ?? true,
+        ...browserName === "chromium" ? { args: ["--disable-blink-features=AutomationControlled"] } : {}
+      });
+    } catch (error) {
+      if (isPlaywrightMissingBrowserError(error)) {
+        throw new Error(formatMissingBrowserError(browserName));
+      }
+      throw error;
+    }
+    this.disconnected = false;
+    this.intentionalClose = false;
+    this.browser.on("disconnected", () => {
+      if (!this.intentionalClose) {
+        this.disconnected = true;
+      }
+    });
+    const contextOptions = {
+      viewport: config.browser?.viewport ?? { width: 1280, height: 720 }
+    };
+    if (config.recording?.enabled) {
+      contextOptions.recordVideo = {
+        dir: config.recording.videoDir,
+        size: config.recording.videoSize ?? config.browser?.viewport ?? { width: 1280, height: 720 }
+      };
+    }
+    this.context = await this.browser.newContext(contextOptions);
+    if (browserName === "chromium") {
+      await this.context.grantPermissions(["clipboard-write"]);
+    }
+    this.logCaptureConfig = { console: config.logCapture?.console !== false, network: config.logCapture?.network !== false };
+    await this.context.addInitScript(() => {
+      Object.defineProperty(navigator, "webdriver", { get: () => false });
+    });
+    this.page = await this.context.newPage();
+    this.attachLogListeners(this.page);
+  }
+  async cleanup() {
+    this.intentionalClose = true;
+    if (this.browser) {
+      await this.browser.close();
+    }
+    this.browser = null;
+    this.context = null;
+    this.page = null;
+    this.lastRefs = {};
+    this.pageLogBuffers.clear();
+    this.disconnected = false;
+    this.intentionalClose = false;
+  }
+  get isBrowserDisconnected() {
+    return this.disconnected;
+  }
+  async observe(options) {
+    if (!this.page) {
+      throw new Error("WebPlatformAdapter not initialized \u2014 call setup() first");
+    }
+    await waitForPageReady(this.page);
+    const state = await observePage(this.page, {
+      extractDom: options?.extractDom
+    });
+    this.lastRefs = state.metadata.refMap ?? {};
+    return state;
+  }
+  async execute(action) {
+    if (!this.page) {
+      throw new Error("WebPlatformAdapter not initialized \u2014 call setup() first");
+    }
+    try {
+      return await this.executeAction(action);
+    } catch (err) {
+      let screenshot;
+      let boundingBox;
+      try {
+        screenshot = await this.page.screenshot({ scale: "css" });
+      } catch {
+      }
+      try {
+        if ("ref" in action && typeof action.ref === "string") {
+          const resolver = new ElementResolver(this.page, this.lastRefs);
+          const box = await resolver.getBoundingBox(action.ref);
+          if (box) boundingBox = box;
+        }
+      } catch {
+      }
+      return {
+        success: false,
+        error: err instanceof Error ? err.message : String(err),
+        screenshot,
+        boundingBox
+      };
+    }
+  }
+  async screenshot() {
+    try {
+      if (this.page) {
+        return await this.page.screenshot({ scale: "css" });
+      }
+      return void 0;
+    } catch {
+      return void 0;
+    }
+  }
+  getPage() {
+    return this.page;
+  }
+  async getVideoPath() {
+    try {
+      const video = this.page?.video();
+      if (!video) return null;
+      return await video.path();
+    } catch {
+      return null;
+    }
+  }
+  drainConsoleLogs(level) {
+    const all = [];
+    for (const buffers of this.pageLogBuffers.values()) {
+      const newLogs = buffers.consoleLogs.slice(buffers.consoleDrainIndex);
+      buffers.consoleDrainIndex = buffers.consoleLogs.length;
+      all.push(...newLogs);
+    }
+    if (!level) return all;
+    return all.filter((e) => e.level === level);
+  }
+  drainNetworkLogs(urlPattern) {
+    const all = [];
+    for (const buffers of this.pageLogBuffers.values()) {
+      const newLogs = buffers.networkLogs.slice(buffers.networkDrainIndex);
+      buffers.networkDrainIndex = buffers.networkLogs.length;
+      all.push(...newLogs);
+    }
+    if (!urlPattern) return all;
+    return all.filter((e) => e.url.includes(urlPattern));
+  }
+  attachLogListeners(page) {
+    const buffers = {
+      consoleLogs: [],
+      networkLogs: [],
+      consoleDrainIndex: 0,
+      networkDrainIndex: 0,
+      pendingRequests: /* @__PURE__ */ new Map()
+    };
+    this.pageLogBuffers.set(page, buffers);
+    if (this.logCaptureConfig.console) {
+      page.on("console", (msg) => {
+        buffers.consoleLogs.push({
+          level: msg.type(),
+          text: msg.text(),
+          location: msg.location(),
+          timestamp: Date.now()
+        });
+        if (buffers.consoleLogs.length > 1e3) {
+          buffers.consoleLogs = buffers.consoleLogs.slice(-500);
+        }
+      });
+    }
+    if (this.logCaptureConfig.network) {
+      page.on("request", (request) => {
+        buffers.pendingRequests.set(request.url() + request.method(), {
+          url: request.url(),
+          method: request.method(),
+          headers: request.headers(),
+          startTime: Date.now(),
+          postData: request.postData() ?? void 0
+        });
+      });
+      page.on("response", async (response) => {
+        const key = response.url() + response.request().method();
+        const pending = buffers.pendingRequests.get(key);
+        buffers.pendingRequests.delete(key);
+        let body;
+        try {
+          const buf = await response.body();
+          const ct = response.headers()["content-type"] ?? "";
+          if (ct.includes("image/") && !ct.includes("svg")) {
+            body = buf.length > 32768 ? void 0 : `data:${ct.split(";")[0]};base64,${buf.toString("base64")}`;
+          } else {
+            const text = buf.toString("utf-8");
+            body = text.length > 32768 ? text.slice(0, 32768) + "...[truncated]" : text;
+          }
+        } catch {
+          body = void 0;
+        }
+        buffers.networkLogs.push({
+          url: response.url(),
+          method: response.request().method(),
+          status: response.status(),
+          requestHeaders: pending?.headers ?? response.request().headers(),
+          responseHeaders: response.headers(),
+          body,
+          requestBody: pending?.postData,
+          startTime: pending?.startTime ?? Date.now(),
+          endTime: Date.now(),
+          timing: response.request().timing()
+        });
+        if (buffers.networkLogs.length > 500) {
+          buffers.networkLogs = buffers.networkLogs.slice(-250);
+        }
+      });
+    }
+  }
+  async resolveTabTargetAsync(tab) {
+    const pages = this.context.pages();
+    if (tab.index !== void 0) {
+      return tab.index >= 0 && tab.index < pages.length ? pages[tab.index] : void 0;
+    }
+    if (tab.title) {
+      for (const p of pages) {
+        const t = await p.title();
+        if (t.includes(tab.title)) return p;
+      }
+      return void 0;
+    }
+    if (tab.url) {
+      return pages.find((p) => p.url().includes(tab.url));
+    }
+    return void 0;
+  }
+  async executeAction(action) {
+    const page = this.page;
+    const resolver = new ElementResolver(page, this.lastRefs);
+    if ("ref" in action && typeof action.ref === "string") {
+      const refData = this.lastRefs[action.ref];
+      const role = refData?.role;
+      const validation = validateAction(action, role);
+      if (!validation.valid) {
+        return { success: false, error: validation.error };
+      }
+    }
+    switch (action.type) {
+      case "click": {
+        const locator = resolver.resolve(action.ref);
+        const box = await resolver.getBoundingBox(action.ref);
+        const coordinates = box ? { x: box.x + box.width / 2, y: box.y + box.height / 2 } : void 0;
+        await locator.click({
+          ...clickDelayOption(action.clickDelay)
+        });
+        return { success: true, coordinates, boundingBox: box ?? void 0 };
+      }
+      case "fill": {
+        const locator = resolver.resolve(action.ref);
+        const box = await resolver.getBoundingBox(action.ref);
+        await locator.fill(action.value);
+        return { success: true, boundingBox: box ?? void 0 };
+      }
+      case "select": {
+        const locator = resolver.resolve(action.ref);
+        const box = await resolver.getBoundingBox(action.ref);
+        await locator.selectOption(action.value);
+        return { success: true, boundingBox: box ?? void 0 };
+      }
+      case "navigate": {
+        await page.goto(action.url, { waitUntil: "domcontentloaded" });
+        await waitForPageReady(page);
+        return { success: true };
+      }
+      case "scroll": {
+        const deltaX = action.scrollType === "horizontal" ? action.value : 0;
+        const deltaY = action.scrollType === "vertical" ? action.value : 0;
+        let coordinates;
+        let boundingBox;
+        let scrollData;
+        if (action.ref) {
+          const refData = this.lastRefs[action.ref];
+          if (refData) {
+            const scrollAxis = action.scrollType === "horizontal" ? "horizontal" : "vertical";
+            const result = await scrollWithRef(page, refData, deltaX, deltaY, scrollAxis);
+            if (result.bounds) {
+              coordinates = { x: result.bounds.x + result.bounds.width / 2, y: result.bounds.y + result.bounds.height / 2 };
+              boundingBox = result.bounds;
+            }
+            scrollData = { scrolled: result.scrolled, scrolledContainer: result.scrolledContainer };
+          } else {
+            await page.mouse.wheel(deltaX, deltaY);
+          }
+        } else {
+          await page.mouse.wheel(deltaX, deltaY);
+        }
+        await page.evaluate(`new Promise(resolve => {
+          const t = setTimeout(() => resolve('timeout'), 500);
+          requestAnimationFrame(() => requestAnimationFrame(() => {
+            clearTimeout(t);
+            resolve('raf');
+          }));
+        })`);
+        return { success: true, coordinates, boundingBox, data: scrollData };
+      }
+      case "waitFor": {
+        const timeout = action.timeout ?? 5e3;
+        try {
+          await page.waitForFunction(
+            `document.body && document.body.innerText.includes(${JSON.stringify(action.condition)})`,
+            { timeout }
+          );
+        } catch {
+          try {
+            await page.waitForSelector(action.condition, { timeout });
+          } catch {
+          }
+        }
+        return { success: true };
+      }
+      case "delay": {
+        await page.waitForTimeout(action.ms);
+        return { success: true };
+      }
+      case "waitForUrl": {
+        try {
+          await page.waitForURL(action.pattern, { timeout: 3e4 });
+          return { success: true };
+        } catch (err) {
+          return {
+            success: false,
+            error: `URL pattern "${action.pattern}" did not match within 30s. Hint: use "**" wildcards for substring matching (e.g., "**/dashboard**"). ${err instanceof Error ? err.message : String(err)}`
+          };
+        }
+      }
+      case "keypress": {
+        const effectiveKeys = (0, import_agent_qa_core.convertKeysForPlatform)(action.keys, {
+          enabled: action.convertPlatformKeys !== false,
+          isMac: (0, import_agent_qa_core.isMacPlatform)()
+        });
+        for (const key of effectiveKeys) {
+          await page.keyboard.press(key);
+        }
+        return { success: true };
+      }
+      case "hover": {
+        const locator = resolver.resolve(action.ref);
+        const box = await resolver.getBoundingBox(action.ref);
+        await locator.hover();
+        return { success: true, boundingBox: box ?? void 0 };
+      }
+      case "paste": {
+        const locator = resolver.resolve(action.ref);
+        const box = await resolver.getBoundingBox(action.ref);
+        await locator.focus();
+        await page.evaluate(`(() => {
+          const el = document.activeElement;
+          if (!el) return;
+          const dt = new DataTransfer();
+          dt.setData('text/plain', ${JSON.stringify(action.value)});
+          el.dispatchEvent(new ClipboardEvent('paste', {
+            clipboardData: dt,
+            bubbles: true,
+            cancelable: true,
+          }));
+        })()`);
+        return { success: true, boundingBox: box ?? void 0 };
+      }
+      case "fileUpload": {
+        const { existsSync } = await import("fs");
+        for (const filePath of action.files) {
+          if (!existsSync(filePath)) {
+            return { success: false, error: `File not found: ${filePath}` };
+          }
+        }
+        const locator = resolver.resolve(action.ref);
+        const box = await resolver.getBoundingBox(action.ref);
+        await locator.setInputFiles(action.files);
+        return { success: true, boundingBox: box ?? void 0 };
+      }
+      case "copy": {
+        const locator = resolver.resolve(action.ref);
+        const box = await resolver.getBoundingBox(action.ref);
+        const text = await locator.textContent() ?? "";
+        await page.evaluate(`navigator.clipboard.writeText(${JSON.stringify(text)})`);
+        return { success: true, boundingBox: box ?? void 0, data: { copied: text } };
+      }
+      case "keyDown": {
+        await page.keyboard.down(action.key);
+        return { success: true };
+      }
+      case "keyUp": {
+        await page.keyboard.up(action.key);
+        return { success: true };
+      }
+      case "refresh": {
+        await page.reload({ waitUntil: "domcontentloaded" });
+        await waitForPageReady(page);
+        return { success: true };
+      }
+      case "navigateHistory": {
+        if (action.direction === "back") {
+          await page.goBack({ waitUntil: "domcontentloaded" });
+        } else {
+          await page.goForward({ waitUntil: "domcontentloaded" });
+        }
+        await waitForPageReady(page);
+        return { success: true };
+      }
+      case "readConsoleLogs": {
+        let entries;
+        if (action.tab) {
+          const targetPage = await this.resolveTabTargetAsync(action.tab);
+          if (!targetPage) {
+            return { success: false, error: `No tab found matching ${JSON.stringify(action.tab)}` };
+          }
+          const buffers = this.pageLogBuffers.get(targetPage);
+          entries = buffers ? [...buffers.consoleLogs] : [];
+        } else {
+          entries = [];
+          for (const buffers of this.pageLogBuffers.values()) {
+            entries.push(...buffers.consoleLogs);
+          }
+        }
+        if (action.level) {
+          entries = entries.filter((e) => e.level === action.level);
+        }
+        return { success: true, data: entries };
+      }
+      case "readNetworkLogs": {
+        let entries;
+        if (action.tab) {
+          const targetPage = await this.resolveTabTargetAsync(action.tab);
+          if (!targetPage) {
+            return { success: false, error: `No tab found matching ${JSON.stringify(action.tab)}` };
+          }
+          const buffers = this.pageLogBuffers.get(targetPage);
+          entries = buffers ? [...buffers.networkLogs] : [];
+        } else {
+          entries = [];
+          for (const buffers of this.pageLogBuffers.values()) {
+            entries.push(...buffers.networkLogs);
+          }
+        }
+        if (action.urlPattern) {
+          entries = entries.filter((e) => e.url.includes(action.urlPattern));
+        }
+        return { success: true, data: entries };
+      }
+      case "readCookies": {
+        const cookies = await this.context.cookies();
+        if (action.name) {
+          const cookie = cookies.find((c) => c.name === action.name) ?? null;
+          return { success: true, data: cookie };
+        }
+        return { success: true, data: cookies };
+      }
+      case "setCookies": {
+        const cookiesWithDefaults = action.cookies.map((c) => ({
+          ...c,
+          url: !c.domain ? page.url() : void 0
+        }));
+        await this.context.addCookies(cookiesWithDefaults);
+        return { success: true };
+      }
+      case "readLocalStorage": {
+        const pageUrl = page.url();
+        if (pageUrl === "about:blank") {
+          return { success: true, data: action.key ? null : {} };
+        }
+        if (action.key) {
+          const value = await page.evaluate(
+            (k) => localStorage.getItem(k),
+            action.key
+          );
+          return { success: true, data: value };
+        }
+        const all = await page.evaluate(
+          () => Object.fromEntries(
+            Object.keys(localStorage).map((k) => [k, localStorage.getItem(k)])
+          )
+        );
+        return { success: true, data: all };
+      }
+      case "setLocalStorage": {
+        await page.evaluate((entries) => {
+          for (const { key, value } of entries) {
+            localStorage.setItem(key, value);
+          }
+        }, action.entries);
+        return { success: true };
+      }
+      case "assert": {
+        return { success: true };
+      }
+      case "clearText": {
+        const loc = resolver.resolve(action.ref);
+        const clearBox = await resolver.getBoundingBox(action.ref);
+        await loc.clear();
+        return { success: true, boundingBox: clearBox ?? void 0 };
+      }
+      case "drag": {
+        const fromLoc = resolver.resolve(action.fromRef);
+        const toLoc = resolver.resolve(action.toRef);
+        await fromLoc.dragTo(toLoc);
+        return { success: true };
+      }
+      case "doubleTap": {
+        const dblLoc = resolver.resolve(action.ref);
+        const dblBox = await resolver.getBoundingBox(action.ref);
+        await dblLoc.dblclick();
+        return { success: true, boundingBox: dblBox ?? void 0 };
+      }
+      case "doubleClick": {
+        const locator = resolver.resolve(action.ref);
+        const box = await resolver.getBoundingBox(action.ref);
+        const coordinates = box ? action.relativePosition ? { x: box.x + action.relativePosition.x, y: box.y + action.relativePosition.y } : { x: box.x + box.width / 2, y: box.y + box.height / 2 } : void 0;
+        await locator.dblclick({
+          ...action.relativePosition && { position: action.relativePosition },
+          ...clickDelayOption(action.clickDelay)
+        });
+        return { success: true, coordinates, boundingBox: box ?? void 0 };
+      }
+      case "rightClick": {
+        const locator = resolver.resolve(action.ref);
+        const box = await resolver.getBoundingBox(action.ref);
+        const coordinates = box ? action.relativePosition ? { x: box.x + action.relativePosition.x, y: box.y + action.relativePosition.y } : { x: box.x + box.width / 2, y: box.y + box.height / 2 } : void 0;
+        await locator.click({
+          button: "right",
+          ...action.relativePosition && { position: action.relativePosition },
+          ...clickDelayOption(action.clickDelay)
+        });
+        return { success: true, coordinates, boundingBox: box ?? void 0 };
+      }
+      case "openLink": {
+        await page.goto(action.url, { waitUntil: "domcontentloaded" });
+        await waitForPageReady(page);
+        return { success: true };
+      }
+      case "newTab": {
+        const newPage = await this.context.newPage();
+        this.attachLogListeners(newPage);
+        await newPage.goto(action.url, { waitUntil: "domcontentloaded" });
+        await waitForPageReady(newPage);
+        this.page = newPage;
+        return { success: true };
+      }
+      case "switchTab": {
+        const pages = this.context.pages();
+        let target;
+        if (action.index !== void 0) {
+          if (action.index < 0 || action.index >= pages.length) {
+            return { success: false, error: `Tab index ${action.index} out of range (${pages.length} tabs open)` };
+          }
+          target = pages[action.index];
+        } else if (action.title) {
+          for (const p of pages) {
+            const t = await p.title();
+            if (t.includes(action.title)) {
+              target = p;
+              break;
+            }
+          }
+        } else if (action.url) {
+          target = pages.find((p) => p.url().includes(action.url));
+        } else {
+          return { success: false, error: "switchTab requires at least one of: index, title, or url" };
+        }
+        if (!target) {
+          return { success: false, error: `No tab found matching ${JSON.stringify({ index: action.index, title: action.title, url: action.url })}` };
+        }
+        this.page = target;
+        return { success: true };
+      }
+      // Mobile-only actions — graceful unsupported messages
+      case "tap":
+      case "swipe":
+      case "longpress":
+      case "pinch":
+      case "multiTap": {
+        return { success: false, error: `${action.type} is a mobile-only gesture` };
+      }
+      case "tapCoordinate": {
+        const vp = page.viewportSize();
+        if (vp) {
+          (0, import_agent_qa_core.warnIfOutOfBounds)({ x: action.x, y: action.y }, { width: vp.width, height: vp.height }, "tapCoordinate");
+        }
+        await page.mouse.click(action.x, action.y);
+        return { success: true, coordinates: { x: action.x, y: action.y } };
+      }
+      case "executeScript": {
+        return { success: false, error: "executeScript is a mobile-only action" };
+      }
+      case "hideKeyboard":
+      case "launchApp":
+      case "stopApp":
+      case "setOrientation": {
+        return { success: true };
+      }
+      default: {
+        return { success: false, error: `Unknown action type: ${action.type}` };
+      }
+    }
+  }
+};
+
+// src/farm-adapter.ts
+var import_agent_qa_core2 = require("@vostride/agent-qa-core");
+var import_agent_qa_core3 = require("@vostride/agent-qa-core");
+function clickDelayOption2(clickDelay) {
+  return clickDelay !== void 0 && clickDelay > 0 ? { delay: clickDelay } : {};
+}
+var FarmWebAdapter = class {
+  platform = "web";
+  browser = null;
+  context = null;
+  page = null;
+  lastRefs = {};
+  sessionUrl;
+  sessionId;
+  testFailed = false;
+  exitHandler = null;
+  credentials = null;
+  pageLogBuffers = /* @__PURE__ */ new Map();
+  logCaptureConfig = { console: true, network: true };
+  async setup(config) {
+    if (!config.farmSession) {
+      throw new Error("FarmWebAdapter requires config.farmSession to be set");
+    }
+    (0, import_agent_qa_core2.registerAllProviders)();
+    const provider = (0, import_agent_qa_core2.getProvider)("browserstack");
+    if (!provider) {
+      throw new Error("Unknown farm provider: browserstack");
+    }
+    this.credentials = provider.resolveCredentials(config.farmSession.capabilities);
+    if (!config.browser?.name) {
+      throw new Error("FarmWebAdapter requires config.browser.name to be set");
+    }
+    const credentials = this.credentials;
+    const farmWebConfig = {
+      browser: config.browser,
+      credentials,
+      testName: config.farmSession.capabilities?.testName
+    };
+    const { wsEndpoint } = await provider.resolveWebEndpoint(farmWebConfig);
+    const { chromium } = await import("playwright-core");
+    this.browser = await chromium.connect({ wsEndpoint });
+    const contextOptions = {
+      viewport: config.browser?.viewport ?? { width: 1280, height: 720 }
+    };
+    if (config.recording?.enabled) {
+      contextOptions.recordVideo = {
+        dir: config.recording.videoDir,
+        size: config.recording.videoSize ?? config.browser?.viewport ?? { width: 1280, height: 720 }
+      };
+    }
+    this.context = await this.browser.newContext(contextOptions);
+    await this.context.grantPermissions(["clipboard-write"]);
+    this.page = await this.context.newPage();
+    try {
+      const cdpSession = await this.page.context().newCDPSession(this.page);
+      const result = await cdpSession.send("Browser.getVersion");
+      await cdpSession.detach();
+      const auth = Buffer.from(`${credentials.username}:${credentials.accessKey}`).toString("base64");
+      const resp = await fetch("https://api.browserstack.com/automate/builds.json?limit=1&status=running", {
+        headers: { Authorization: `Basic ${auth}` }
+      });
+      if (resp.ok) {
+        const builds = await resp.json();
+        if (builds.length > 0) {
+          const buildId = builds[0].automation_build.hashed_id;
+          const sessResp = await fetch(`https://api.browserstack.com/automate/builds/${buildId}/sessions.json?limit=1`, {
+            headers: { Authorization: `Basic ${auth}` }
+          });
+          if (sessResp.ok) {
+            const sessions = await sessResp.json();
+            if (sessions.length > 0) {
+              this.sessionId = sessions[0].automation_session.hashed_id;
+              this.sessionUrl = sessions[0].automation_session.browser_url;
+            }
+          }
+        }
+      }
+    } catch {
+    }
+    this.exitHandler = () => {
+      try {
+        this.browser?.close();
+      } catch {
+      }
+    };
+    process.on("exit", this.exitHandler);
+    this.logCaptureConfig = { console: config.logCapture?.console !== false, network: config.logCapture?.network !== false };
+    this.attachLogListeners(this.page);
+  }
+  async cleanup() {
+    if (this.browser) {
+      await this.browser.close();
+    }
+    if (this.sessionId && this.credentials) {
+      try {
+        const status = this.testFailed ? "failed" : "passed";
+        const reason = this.testFailed ? "Test failed" : "Test passed";
+        const auth = Buffer.from(`${this.credentials.username}:${this.credentials.accessKey}`).toString("base64");
+        await fetch(`https://api.browserstack.com/automate/sessions/${this.sessionId}.json`, {
+          method: "PUT",
+          headers: { Authorization: `Basic ${auth}`, "Content-Type": "application/json" },
+          body: JSON.stringify({ status, reason })
+        });
+      } catch {
+      }
+    }
+    if (this.exitHandler) {
+      process.removeListener("exit", this.exitHandler);
+      this.exitHandler = null;
+    }
+    this.browser = null;
+    this.context = null;
+    this.page = null;
+    this.lastRefs = {};
+    this.pageLogBuffers.clear();
+  }
+  async observe(options) {
+    if (!this.page) {
+      throw new Error("FarmWebAdapter not initialized \u2014 call setup() first");
+    }
+    await waitForPageReady(this.page);
+    const state = await observePage(this.page, {
+      extractDom: options?.extractDom
+    });
+    this.lastRefs = state.metadata.refMap ?? {};
+    return state;
+  }
+  async execute(action) {
+    if (!this.page) {
+      throw new Error("FarmWebAdapter not initialized \u2014 call setup() first");
+    }
+    try {
+      return await this.executeAction(action);
+    } catch (err) {
+      let screenshot;
+      let boundingBox;
+      try {
+        screenshot = await this.page.screenshot();
+      } catch {
+      }
+      try {
+        if ("ref" in action && typeof action.ref === "string") {
+          const resolver = new ElementResolver(this.page, this.lastRefs);
+          const box = await resolver.getBoundingBox(action.ref);
+          if (box) boundingBox = box;
+        }
+      } catch {
+      }
+      return {
+        success: false,
+        error: err instanceof Error ? err.message : String(err),
+        screenshot,
+        boundingBox
+      };
+    }
+  }
+  async screenshot() {
+    try {
+      if (this.page) {
+        return await this.page.screenshot();
+      }
+      return void 0;
+    } catch {
+      return void 0;
+    }
+  }
+  getPage() {
+    return this.page;
+  }
+  async getVideoPath() {
+    try {
+      const video = this.page?.video();
+      if (!video) return null;
+      return await video.path();
+    } catch {
+      return null;
+    }
+  }
+  markFailed() {
+    this.testFailed = true;
+  }
+  getSessionUrl() {
+    return this.sessionUrl;
+  }
+  getSessionId() {
+    return this.sessionId;
+  }
+  drainConsoleLogs(level) {
+    const all = [];
+    for (const buffers of this.pageLogBuffers.values()) {
+      const newLogs = buffers.consoleLogs.slice(buffers.consoleDrainIndex);
+      buffers.consoleDrainIndex = buffers.consoleLogs.length;
+      all.push(...newLogs);
+    }
+    if (!level) return all;
+    return all.filter((e) => e.level === level);
+  }
+  drainNetworkLogs(urlPattern) {
+    const all = [];
+    for (const buffers of this.pageLogBuffers.values()) {
+      const newLogs = buffers.networkLogs.slice(buffers.networkDrainIndex);
+      buffers.networkDrainIndex = buffers.networkLogs.length;
+      all.push(...newLogs);
+    }
+    if (!urlPattern) return all;
+    return all.filter((e) => e.url.includes(urlPattern));
+  }
+  attachLogListeners(page) {
+    const buffers = {
+      consoleLogs: [],
+      networkLogs: [],
+      consoleDrainIndex: 0,
+      networkDrainIndex: 0,
+      pendingRequests: /* @__PURE__ */ new Map()
+    };
+    this.pageLogBuffers.set(page, buffers);
+    if (this.logCaptureConfig.console) {
+      page.on("console", (msg) => {
+        buffers.consoleLogs.push({
+          level: msg.type(),
+          text: msg.text(),
+          location: msg.location(),
+          timestamp: Date.now()
+        });
+        if (buffers.consoleLogs.length > 1e3) {
+          buffers.consoleLogs = buffers.consoleLogs.slice(-500);
+        }
+      });
+    }
+    if (this.logCaptureConfig.network) {
+      page.on("request", (request) => {
+        buffers.pendingRequests.set(request.url() + request.method(), {
+          url: request.url(),
+          method: request.method(),
+          headers: request.headers(),
+          startTime: Date.now(),
+          postData: request.postData() ?? void 0
+        });
+      });
+      page.on("response", async (response) => {
+        const key = response.url() + response.request().method();
+        const pending = buffers.pendingRequests.get(key);
+        buffers.pendingRequests.delete(key);
+        let body;
+        try {
+          const buf = await response.body();
+          const ct = response.headers()["content-type"] ?? "";
+          if (ct.includes("image/") && !ct.includes("svg")) {
+            body = buf.length > 32768 ? void 0 : `data:${ct.split(";")[0]};base64,${buf.toString("base64")}`;
+          } else {
+            const text = buf.toString("utf-8");
+            body = text.length > 32768 ? text.slice(0, 32768) + "...[truncated]" : text;
+          }
+        } catch {
+          body = void 0;
+        }
+        buffers.networkLogs.push({
+          url: response.url(),
+          method: response.request().method(),
+          status: response.status(),
+          requestHeaders: pending?.headers ?? response.request().headers(),
+          responseHeaders: response.headers(),
+          body,
+          requestBody: pending?.postData,
+          startTime: pending?.startTime ?? Date.now(),
+          endTime: Date.now(),
+          timing: response.request().timing()
+        });
+        if (buffers.networkLogs.length > 500) {
+          buffers.networkLogs = buffers.networkLogs.slice(-250);
+        }
+      });
+    }
+  }
+  async resolveTabTargetAsync(tab) {
+    const pages = this.context.pages();
+    if (tab.index !== void 0) {
+      return tab.index >= 0 && tab.index < pages.length ? pages[tab.index] : void 0;
+    }
+    if (tab.title) {
+      for (const p of pages) {
+        const t = await p.title();
+        if (t.includes(tab.title)) return p;
+      }
+      return void 0;
+    }
+    if (tab.url) {
+      return pages.find((p) => p.url().includes(tab.url));
+    }
+    return void 0;
+  }
+  async executeAction(action) {
+    const page = this.page;
+    const resolver = new ElementResolver(page, this.lastRefs);
+    if ("ref" in action && typeof action.ref === "string") {
+      const refData = this.lastRefs[action.ref];
+      const role = refData?.role;
+      const validation = validateAction(action, role);
+      if (!validation.valid) {
+        return { success: false, error: validation.error };
+      }
+    }
+    switch (action.type) {
+      case "click": {
+        const locator = resolver.resolve(action.ref);
+        const box = await resolver.getBoundingBox(action.ref);
+        const coordinates = box ? { x: box.x + box.width / 2, y: box.y + box.height / 2 } : void 0;
+        await locator.click({
+          ...clickDelayOption2(action.clickDelay)
+        });
+        return { success: true, coordinates, boundingBox: box ?? void 0 };
+      }
+      case "fill": {
+        const locator = resolver.resolve(action.ref);
+        const box = await resolver.getBoundingBox(action.ref);
+        await locator.fill(action.value);
+        return { success: true, boundingBox: box ?? void 0 };
+      }
+      case "select": {
+        const locator = resolver.resolve(action.ref);
+        const box = await resolver.getBoundingBox(action.ref);
+        await locator.selectOption(action.value);
+        return { success: true, boundingBox: box ?? void 0 };
+      }
+      case "navigate": {
+        await page.goto(action.url, { waitUntil: "domcontentloaded" });
+        await waitForPageReady(page);
+        return { success: true };
+      }
+      case "scroll": {
+        const deltaX = action.scrollType === "horizontal" ? action.value : 0;
+        const deltaY = action.scrollType === "vertical" ? action.value : 0;
+        let coordinates;
+        let boundingBox;
+        let scrollData;
+        if (action.ref) {
+          const refData = this.lastRefs[action.ref];
+          if (refData) {
+            const scrollAxis = action.scrollType === "horizontal" ? "horizontal" : "vertical";
+            const result = await scrollWithRef(page, refData, deltaX, deltaY, scrollAxis);
+            if (result.bounds) {
+              coordinates = { x: result.bounds.x + result.bounds.width / 2, y: result.bounds.y + result.bounds.height / 2 };
+              boundingBox = result.bounds;
+            }
+            scrollData = { scrolled: result.scrolled, scrolledContainer: result.scrolledContainer };
+          } else {
+            await page.mouse.wheel(deltaX, deltaY);
+          }
+        } else {
+          await page.mouse.wheel(deltaX, deltaY);
+        }
+        await page.evaluate(`new Promise(resolve => {
+          const t = setTimeout(() => resolve('timeout'), 500);
+          requestAnimationFrame(() => requestAnimationFrame(() => {
+            clearTimeout(t);
+            resolve('raf');
+          }));
+        })`);
+        return { success: true, coordinates, boundingBox, data: scrollData };
+      }
+      case "waitFor": {
+        const timeout = action.timeout ?? 5e3;
+        try {
+          await page.waitForFunction(
+            `document.body && document.body.innerText.includes(${JSON.stringify(action.condition)})`,
+            { timeout }
+          );
+        } catch {
+          try {
+            await page.waitForSelector(action.condition, { timeout });
+          } catch {
+          }
+        }
+        return { success: true };
+      }
+      case "delay": {
+        await page.waitForTimeout(action.ms);
+        return { success: true };
+      }
+      case "waitForUrl": {
+        try {
+          await page.waitForURL(action.pattern, { timeout: 3e4 });
+          return { success: true };
+        } catch (err) {
+          return {
+            success: false,
+            error: `URL pattern "${action.pattern}" did not match within 30s. Hint: use "**" wildcards for substring matching (e.g., "**/dashboard**"). ${err instanceof Error ? err.message : String(err)}`
+          };
+        }
+      }
+      case "keypress": {
+        const effectiveKeys = (0, import_agent_qa_core3.convertKeysForPlatform)(action.keys, {
+          enabled: action.convertPlatformKeys !== false,
+          isMac: (0, import_agent_qa_core3.isMacPlatform)()
+        });
+        for (const key of effectiveKeys) {
+          await page.keyboard.press(key);
+        }
+        return { success: true };
+      }
+      case "hover": {
+        const locator = resolver.resolve(action.ref);
+        const box = await resolver.getBoundingBox(action.ref);
+        await locator.hover();
+        return { success: true, boundingBox: box ?? void 0 };
+      }
+      case "paste": {
+        const locator = resolver.resolve(action.ref);
+        const box = await resolver.getBoundingBox(action.ref);
+        await locator.focus();
+        await page.evaluate(`(() => {
+          const el = document.activeElement;
+          if (!el) return;
+          const dt = new DataTransfer();
+          dt.setData('text/plain', ${JSON.stringify(action.value)});
+          el.dispatchEvent(new ClipboardEvent('paste', {
+            clipboardData: dt,
+            bubbles: true,
+            cancelable: true,
+          }));
+        })()`);
+        return { success: true, boundingBox: box ?? void 0 };
+      }
+      case "fileUpload": {
+        const { existsSync } = await import("fs");
+        for (const filePath of action.files) {
+          if (!existsSync(filePath)) {
+            return { success: false, error: `File not found: ${filePath}` };
+          }
+        }
+        const locator = resolver.resolve(action.ref);
+        const box = await resolver.getBoundingBox(action.ref);
+        await locator.setInputFiles(action.files);
+        return { success: true, boundingBox: box ?? void 0 };
+      }
+      case "copy": {
+        const locator = resolver.resolve(action.ref);
+        const box = await resolver.getBoundingBox(action.ref);
+        const text = await locator.textContent() ?? "";
+        await page.evaluate(`navigator.clipboard.writeText(${JSON.stringify(text)})`);
+        return { success: true, boundingBox: box ?? void 0, data: { copied: text } };
+      }
+      case "keyDown": {
+        await page.keyboard.down(action.key);
+        return { success: true };
+      }
+      case "keyUp": {
+        await page.keyboard.up(action.key);
+        return { success: true };
+      }
+      case "refresh": {
+        await page.reload({ waitUntil: "domcontentloaded" });
+        await waitForPageReady(page);
+        return { success: true };
+      }
+      case "navigateHistory": {
+        if (action.direction === "back") {
+          await page.goBack({ waitUntil: "domcontentloaded" });
+        } else {
+          await page.goForward({ waitUntil: "domcontentloaded" });
+        }
+        await waitForPageReady(page);
+        return { success: true };
+      }
+      case "readConsoleLogs": {
+        let entries;
+        if (action.tab) {
+          const targetPage = await this.resolveTabTargetAsync(action.tab);
+          if (!targetPage) {
+            return { success: false, error: `No tab found matching ${JSON.stringify(action.tab)}` };
+          }
+          const buffers = this.pageLogBuffers.get(targetPage);
+          entries = buffers ? [...buffers.consoleLogs] : [];
+        } else {
+          entries = [];
+          for (const buffers of this.pageLogBuffers.values()) {
+            entries.push(...buffers.consoleLogs);
+          }
+        }
+        if (action.level) {
+          entries = entries.filter((e) => e.level === action.level);
+        }
+        return { success: true, data: entries };
+      }
+      case "readNetworkLogs": {
+        let entries;
+        if (action.tab) {
+          const targetPage = await this.resolveTabTargetAsync(action.tab);
+          if (!targetPage) {
+            return { success: false, error: `No tab found matching ${JSON.stringify(action.tab)}` };
+          }
+          const buffers = this.pageLogBuffers.get(targetPage);
+          entries = buffers ? [...buffers.networkLogs] : [];
+        } else {
+          entries = [];
+          for (const buffers of this.pageLogBuffers.values()) {
+            entries.push(...buffers.networkLogs);
+          }
+        }
+        if (action.urlPattern) {
+          entries = entries.filter((e) => e.url.includes(action.urlPattern));
+        }
+        return { success: true, data: entries };
+      }
+      case "readCookies": {
+        const cookies = await this.context.cookies();
+        if (action.name) {
+          const cookie = cookies.find((c) => c.name === action.name) ?? null;
+          return { success: true, data: cookie };
+        }
+        return { success: true, data: cookies };
+      }
+      case "setCookies": {
+        const cookiesWithDefaults = action.cookies.map((c) => ({
+          ...c,
+          url: !c.domain ? page.url() : void 0
+        }));
+        await this.context.addCookies(cookiesWithDefaults);
+        return { success: true };
+      }
+      case "readLocalStorage": {
+        const pageUrl = page.url();
+        if (pageUrl === "about:blank") {
+          return { success: true, data: action.key ? null : {} };
+        }
+        if (action.key) {
+          const value = await page.evaluate(
+            (k) => localStorage.getItem(k),
+            action.key
+          );
+          return { success: true, data: value };
+        }
+        const all = await page.evaluate(
+          () => Object.fromEntries(
+            Object.keys(localStorage).map((k) => [k, localStorage.getItem(k)])
+          )
+        );
+        return { success: true, data: all };
+      }
+      case "setLocalStorage": {
+        await page.evaluate((entries) => {
+          for (const { key, value } of entries) {
+            localStorage.setItem(key, value);
+          }
+        }, action.entries);
+        return { success: true };
+      }
+      case "assert": {
+        return { success: true };
+      }
+      case "clearText": {
+        const loc = resolver.resolve(action.ref);
+        const clearBox = await resolver.getBoundingBox(action.ref);
+        await loc.clear();
+        return { success: true, boundingBox: clearBox ?? void 0 };
+      }
+      case "drag": {
+        const fromLoc = resolver.resolve(action.fromRef);
+        const toLoc = resolver.resolve(action.toRef);
+        await fromLoc.dragTo(toLoc);
+        return { success: true };
+      }
+      case "doubleTap": {
+        const dblLoc = resolver.resolve(action.ref);
+        const dblBox = await resolver.getBoundingBox(action.ref);
+        await dblLoc.dblclick();
+        return { success: true, boundingBox: dblBox ?? void 0 };
+      }
+      case "doubleClick": {
+        const locator = resolver.resolve(action.ref);
+        const box = await resolver.getBoundingBox(action.ref);
+        const coordinates = box ? action.relativePosition ? { x: box.x + action.relativePosition.x, y: box.y + action.relativePosition.y } : { x: box.x + box.width / 2, y: box.y + box.height / 2 } : void 0;
+        await locator.dblclick({
+          ...action.relativePosition && { position: action.relativePosition },
+          ...clickDelayOption2(action.clickDelay)
+        });
+        return { success: true, coordinates, boundingBox: box ?? void 0 };
+      }
+      case "rightClick": {
+        const locator = resolver.resolve(action.ref);
+        const box = await resolver.getBoundingBox(action.ref);
+        const coordinates = box ? action.relativePosition ? { x: box.x + action.relativePosition.x, y: box.y + action.relativePosition.y } : { x: box.x + box.width / 2, y: box.y + box.height / 2 } : void 0;
+        await locator.click({
+          button: "right",
+          ...action.relativePosition && { position: action.relativePosition },
+          ...clickDelayOption2(action.clickDelay)
+        });
+        return { success: true, coordinates, boundingBox: box ?? void 0 };
+      }
+      case "openLink": {
+        await page.goto(action.url, { waitUntil: "domcontentloaded" });
+        await waitForPageReady(page);
+        return { success: true };
+      }
+      case "newTab": {
+        const newPage = await this.context.newPage();
+        this.attachLogListeners(newPage);
+        await newPage.goto(action.url, { waitUntil: "domcontentloaded" });
+        await waitForPageReady(newPage);
+        this.page = newPage;
+        return { success: true };
+      }
+      case "switchTab": {
+        const pages = this.context.pages();
+        let target;
+        if (action.index !== void 0) {
+          if (action.index < 0 || action.index >= pages.length) {
+            return { success: false, error: `Tab index ${action.index} out of range (${pages.length} tabs open)` };
+          }
+          target = pages[action.index];
+        } else if (action.title) {
+          for (const p of pages) {
+            const t = await p.title();
+            if (t.includes(action.title)) {
+              target = p;
+              break;
+            }
+          }
+        } else if (action.url) {
+          target = pages.find((p) => p.url().includes(action.url));
+        } else {
+          return { success: false, error: "switchTab requires at least one of: index, title, or url" };
+        }
+        if (!target) {
+          return { success: false, error: `No tab found matching ${JSON.stringify({ index: action.index, title: action.title, url: action.url })}` };
+        }
+        this.page = target;
+        return { success: true };
+      }
+      case "tap":
+      case "swipe":
+      case "longpress":
+      case "pinch":
+      case "multiTap": {
+        return { success: false, error: `${action.type} is a mobile-only gesture` };
+      }
+      case "tapCoordinate": {
+        await page.mouse.click(action.x, action.y);
+        return { success: true, coordinates: { x: action.x, y: action.y } };
+      }
+      case "hideKeyboard":
+      case "launchApp":
+      case "stopApp":
+      case "setOrientation": {
+        return { success: true };
+      }
+      default: {
+        return { success: false, error: `Unknown action type: ${action.type}` };
+      }
+    }
+  }
+};
+
+// src/accessibility.ts
+var import_playwright = require("@axe-core/playwright");
+async function runAccessibilityCheck(page, options) {
+  let builder = new import_playwright.AxeBuilder({ page });
+  if (options?.standard) {
+    const tagMap = {
+      "wcag2a": ["wcag2a"],
+      "wcag2aa": ["wcag2a", "wcag2aa"],
+      "wcag2aaa": ["wcag2a", "wcag2aa", "wcag2aaa"]
+    };
+    builder = builder.withTags(tagMap[options.standard] ?? ["wcag2a", "wcag2aa"]);
+  }
+  if (options?.disableRules?.length) {
+    builder = builder.disableRules(options.disableRules);
+  }
+  if (options?.exclude?.length) {
+    for (const selector of options.exclude) {
+      builder = builder.exclude(selector);
+    }
+  }
+  const results = await builder.analyze();
+  return results.violations.map((v) => ({
+    ruleId: v.id,
+    impact: v.impact,
+    description: v.description,
+    help: v.help,
+    helpUrl: v.helpUrl,
+    nodes: v.nodes.slice(0, 10).map((n) => ({
+      html: n.html,
+      target: n.target
+    }))
+  }));
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ActionValidationError,
+  ElementResolver,
+  FarmWebAdapter,
+  WebPlatformAdapter,
+  extractDom,
+  observePage,
+  parseAriaSnapshot,
+  runAccessibilityCheck,
+  validateAction,
+  waitForPageReady
+});
+//# sourceMappingURL=index.cjs.map