browser-pilot 0.0.11 → 0.0.13

package/dist/chunk-A2ZRAEO3.mjs

@@ -0,0 +1,1711 @@
+import {
+  CDPError
+} from "./chunk-JXAUPHZM.mjs";
+
+// src/browser/actionability.ts
+var ActionabilityError = class extends Error {
+  failureType;
+  coveringElement;
+  constructor(message, failureType, coveringElement) {
+    super(message);
+    this.name = "ActionabilityError";
+    this.failureType = failureType;
+    this.coveringElement = coveringElement;
+  }
+};
+var CHECK_VISIBLE = `function() {
+  // checkVisibility handles display:none, visibility:hidden, content-visibility up the tree
+  if (typeof this.checkVisibility === 'function' && !this.checkVisibility()) {
+    return { actionable: false, reason: 'Element is not visible (checkVisibility failed). Try scrolling or check if a prior action is needed to reveal it.' };
+  }
+
+  var style = getComputedStyle(this);
+
+  if (style.visibility !== 'visible') {
+    return { actionable: false, reason: 'Element has visibility: ' + style.visibility + '. Try scrolling or check if a prior action is needed to reveal it.' };
+  }
+
+  // display:contents elements have no box themselves \u2014 check children
+  if (style.display === 'contents') {
+    var children = this.children;
+    if (children.length === 0) {
+      return { actionable: false, reason: 'Element has display:contents with no children. Try scrolling or check if a prior action is needed to reveal it.' };
+    }
+    for (var i = 0; i < children.length; i++) {
+      var childRect = children[i].getBoundingClientRect();
+      if (childRect.width > 0 && childRect.height > 0) {
+        return { actionable: true };
+      }
+    }
+    return { actionable: false, reason: 'Element has display:contents but no visible children. Try scrolling or check if a prior action is needed to reveal it.' };
+  }
+
+  var rect = this.getBoundingClientRect();
+  if (rect.width <= 0 || rect.height <= 0) {
+    return { actionable: false, reason: 'Element has zero size (' + rect.width + 'x' + rect.height + '). Try scrolling or check if a prior action is needed to reveal it.' };
+  }
+
+  return { actionable: true };
+}`;
+var CHECK_ENABLED = `function() {
+  // Native disabled property
+  var disableable = ['BUTTON', 'INPUT', 'SELECT', 'TEXTAREA', 'OPTION', 'OPTGROUP'];
+  if (disableable.indexOf(this.tagName) !== -1 && this.disabled) {
+    return { actionable: false, reason: 'Element is disabled. Check if a prerequisite field needs to be filled first.' };
+  }
+
+  // Check ancestor FIELDSET[disabled]
+  var parent = this.parentElement;
+  while (parent) {
+    if (parent.tagName === 'FIELDSET' && parent.disabled) {
+      // Exception: elements inside the first <legend> of a disabled fieldset are NOT disabled
+      var legend = parent.querySelector(':scope > legend');
+      if (!legend || !legend.contains(this)) {
+        return { actionable: false, reason: 'Element is inside a disabled fieldset. Check if a prerequisite field needs to be filled first.' };
+      }
+    }
+    parent = parent.parentElement;
+  }
+
+  // aria-disabled="true" walking up ancestor chain (crosses shadow DOM)
+  var node = this;
+  while (node) {
+    if (node.nodeType === 1 && node.getAttribute && node.getAttribute('aria-disabled') === 'true') {
+      return { actionable: false, reason: 'Element or ancestor has aria-disabled="true". Check if a prerequisite field needs to be filled first.' };
+    }
+    if (node.parentElement) {
+      node = node.parentElement;
+    } else if (node.getRootNode && node.getRootNode() !== node) {
+      // Cross shadow DOM boundary
+      var root = node.getRootNode();
+      node = root.host || null;
+    } else {
+      break;
+    }
+  }
+
+  return { actionable: true };
+}`;
+var CHECK_STABLE = `function() {
+  var self = this;
+  return new Promise(function(resolve) {
+    // If tab is backgrounded, RAF won't fire reliably \u2014 skip stability check
+    if (document.visibilityState === 'hidden') {
+      var rect = self.getBoundingClientRect();
+      resolve({ actionable: rect.width > 0 && rect.height > 0 });
+      return;
+    }
+
+    var maxFrames = 30;
+    var prev = null;
+    var frame = 0;
+    var resolved = false;
+
+    var fallbackTimer = setTimeout(function() {
+      if (!resolved) {
+        resolved = true;
+        resolve({ actionable: false, reason: 'Element stability check timed out (tab may be backgrounded)' });
+      }
+    }, 2000);
+
+    function check() {
+      if (resolved) return;
+      frame++;
+      if (frame > maxFrames) {
+        resolved = true;
+        clearTimeout(fallbackTimer);
+        resolve({ actionable: false, reason: 'Element position not stable after ' + maxFrames + ' frames' });
+        return;
+      }
+
+      var rect = self.getBoundingClientRect();
+      var cur = { x: rect.x, y: rect.y, w: rect.width, h: rect.height };
+
+      if (prev !== null &&
+          prev.x === cur.x && prev.y === cur.y &&
+          prev.w === cur.w && prev.h === cur.h) {
+        resolved = true;
+        clearTimeout(fallbackTimer);
+        resolve({ actionable: true });
+        return;
+      }
+
+      prev = cur;
+      requestAnimationFrame(check);
+    }
+
+    requestAnimationFrame(check);
+  });
+}`;
+var CHECK_HIT_TARGET = `function(x, y) {
+  // Compute click center if coordinates not provided
+  if (x === undefined || y === undefined) {
+    var rect = this.getBoundingClientRect();
+    x = rect.x + rect.width / 2;
+    y = rect.y + rect.height / 2;
+  }
+
+  function checkPoint(root, px, py) {
+    var method = root.elementsFromPoint || root.msElementsFromPoint;
+    if (!method) return [];
+    return method.call(root, px, py) || [];
+  }
+
+  // Follow only the top-most hit through nested shadow roots.
+  // Accepting any hit in the stack creates false positives for covered elements.
+  var root = document;
+  var topHits = [];
+  var seenRoots = [];
+  while (root && seenRoots.indexOf(root) === -1) {
+    seenRoots.push(root);
+    var hits = checkPoint(root, x, y);
+    if (!hits.length) break;
+    var top = hits[0];
+    topHits.push(top);
+    if (top && top.shadowRoot) {
+      root = top.shadowRoot;
+      continue;
+    }
+    break;
+  }
+
+  // Target must be the top-most hit element or an ancestor/descendant
+  for (var j = 0; j < topHits.length; j++) {
+    var hit = topHits[j];
+    if (hit === this || this.contains(hit) || hit.contains(this)) {
+      return { actionable: true };
+    }
+  }
+
+  // Report the covering element
+  var top = topHits.length > 0 ? topHits[topHits.length - 1] : null;
+  if (top) {
+    return {
+      actionable: false,
+      reason: 'Element is covered by <' + top.tagName.toLowerCase() + '>' +
+        (top.id ? '#' + top.id : '') +
+        (top.className && typeof top.className === 'string' ? '.' + top.className.split(' ').join('.') : '') +
+        '. Try dismissing overlays first.',
+      coveringElement: {
+        tag: top.tagName.toLowerCase(),
+        id: top.id || undefined,
+        className: (typeof top.className === 'string' && top.className) || undefined
+      }
+    };
+  }
+
+  return { actionable: false, reason: 'No element found at click point (' + x + ', ' + y + '). Try scrolling the element into view first.' };
+}`;
+var CHECK_EDITABLE = `function() {
+  // Must be an editable element type
+  var tag = this.tagName;
+  var isEditable = tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT' ||
+    this.isContentEditable;
+  if (!isEditable) {
+    return { actionable: false, reason: 'Element is not an editable type (<' + tag.toLowerCase() + '>). Target an <input>, <textarea>, <select>, or [contenteditable] element instead.' };
+  }
+
+  // Check disabled
+  var disableable = ['BUTTON', 'INPUT', 'SELECT', 'TEXTAREA', 'OPTION', 'OPTGROUP'];
+  if (disableable.indexOf(tag) !== -1 && this.disabled) {
+    return { actionable: false, reason: 'Element is disabled. Check if a prerequisite field needs to be filled first.' };
+  }
+
+  // Check ancestor FIELDSET[disabled]
+  var parent = this.parentElement;
+  while (parent) {
+    if (parent.tagName === 'FIELDSET' && parent.disabled) {
+      var legend = parent.querySelector(':scope > legend');
+      if (!legend || !legend.contains(this)) {
+        return { actionable: false, reason: 'Element is inside a disabled fieldset. Check if a prerequisite field needs to be filled first.' };
+      }
+    }
+    parent = parent.parentElement;
+  }
+
+  // aria-disabled walking up (crosses shadow DOM)
+  var node = this;
+  while (node) {
+    if (node.nodeType === 1 && node.getAttribute && node.getAttribute('aria-disabled') === 'true') {
+      return { actionable: false, reason: 'Element or ancestor has aria-disabled="true". Check if a prerequisite field needs to be filled first.' };
+    }
+    if (node.parentElement) {
+      node = node.parentElement;
+    } else if (node.getRootNode && node.getRootNode() !== node) {
+      var root = node.getRootNode();
+      node = root.host || null;
+    } else {
+      break;
+    }
+  }
+
+  // Check readonly
+  if (this.hasAttribute && this.hasAttribute('readonly')) {
+    return { actionable: false, reason: 'Cannot fill a readonly input. Remove the readonly attribute or target a different element.' };
+  }
+  if (this.getAttribute && this.getAttribute('aria-readonly') === 'true') {
+    return { actionable: false, reason: 'Cannot fill a readonly input (aria-readonly="true"). Remove the attribute or target a different element.' };
+  }
+
+  return { actionable: true };
+}`;
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+var BACKOFF = [0, 20, 100, 100];
+async function runCheck(cdp, objectId, check, options) {
+  let script;
+  let awaitPromise = false;
+  const args = [];
+  switch (check) {
+    case "visible":
+      script = CHECK_VISIBLE;
+      break;
+    case "enabled":
+      script = CHECK_ENABLED;
+      break;
+    case "stable":
+      script = CHECK_STABLE;
+      awaitPromise = true;
+      break;
+    case "hitTarget":
+      script = CHECK_HIT_TARGET;
+      if (options?.coordinates) {
+        args.push({ value: options.coordinates.x });
+        args.push({ value: options.coordinates.y });
+      } else {
+        args.push({ value: void 0 });
+        args.push({ value: void 0 });
+      }
+      break;
+    case "editable":
+      script = CHECK_EDITABLE;
+      break;
+    default: {
+      const _exhaustive = check;
+      throw new Error(`Unknown actionability check: ${_exhaustive}`);
+    }
+  }
+  const params = {
+    functionDeclaration: script,
+    objectId,
+    returnByValue: true,
+    arguments: args
+  };
+  if (awaitPromise) {
+    params["awaitPromise"] = true;
+  }
+  const response = await cdp.send("Runtime.callFunctionOn", params);
+  if (response.exceptionDetails) {
+    return {
+      actionable: false,
+      reason: `Check "${check}" threw: ${response.exceptionDetails.text}`,
+      failureType: check
+    };
+  }
+  const result = response.result.value;
+  if (!result.actionable) {
+    result.failureType = check;
+  }
+  return result;
+}
+async function runChecks(cdp, objectId, checks, options) {
+  for (const check of checks) {
+    const result = await runCheck(cdp, objectId, check, options);
+    if (!result.actionable) {
+      return result;
+    }
+  }
+  return { actionable: true };
+}
+async function ensureActionable(cdp, objectId, checks, options) {
+  const timeout = options?.timeout ?? 3e4;
+  const start = Date.now();
+  let attempt = 0;
+  while (true) {
+    const result = await runChecks(cdp, objectId, checks, options);
+    if (result.actionable) return;
+    if (Date.now() - start >= timeout) {
+      throw new ActionabilityError(
+        `Element not actionable: ${result.reason}`,
+        result.failureType,
+        result.coveringElement
+      );
+    }
+    const delay = attempt < BACKOFF.length ? BACKOFF[attempt] ?? 0 : 500;
+    if (delay > 0) await sleep(delay);
+    attempt++;
+  }
+}
+
+// src/browser/fuzzy-match.ts
+function jaroWinkler(a, b) {
+  if (a.length === 0 && b.length === 0) return 0;
+  if (a.length === 0 || b.length === 0) return 0;
+  if (a === b) return 1;
+  const s1 = a.toLowerCase();
+  const s2 = b.toLowerCase();
+  const matchWindow = Math.max(0, Math.floor(Math.max(s1.length, s2.length) / 2) - 1);
+  const s1Matches = Array.from({ length: s1.length }, () => false);
+  const s2Matches = Array.from({ length: s2.length }, () => false);
+  let matches = 0;
+  let transpositions = 0;
+  for (let i = 0; i < s1.length; i++) {
+    const start = Math.max(0, i - matchWindow);
+    const end = Math.min(i + matchWindow + 1, s2.length);
+    for (let j = start; j < end; j++) {
+      if (s2Matches[j] || s1[i] !== s2[j]) continue;
+      s1Matches[i] = true;
+      s2Matches[j] = true;
+      matches++;
+      break;
+    }
+  }
+  if (matches === 0) return 0;
+  let k = 0;
+  for (let i = 0; i < s1.length; i++) {
+    if (!s1Matches[i]) continue;
+    while (!s2Matches[k]) k++;
+    if (s1[i] !== s2[k]) transpositions++;
+    k++;
+  }
+  const jaro = (matches / s1.length + matches / s2.length + (matches - transpositions / 2) / matches) / 3;
+  let prefix = 0;
+  for (let i = 0; i < Math.min(4, Math.min(s1.length, s2.length)); i++) {
+    if (s1[i] === s2[i]) {
+      prefix++;
+    } else {
+      break;
+    }
+  }
+  const WINKLER_SCALING = 0.1;
+  return jaro + prefix * WINKLER_SCALING * (1 - jaro);
+}
+function stringSimilarity(a, b) {
+  if (a.length === 0 || b.length === 0) return 0;
+  const lowerA = a.toLowerCase();
+  const lowerB = b.toLowerCase();
+  if (lowerA === lowerB) return 1;
+  const jw = jaroWinkler(a, b);
+  let containsBonus = 0;
+  if (lowerB.includes(lowerA)) {
+    containsBonus = 0.2;
+  } else if (lowerA.includes(lowerB)) {
+    containsBonus = 0.1;
+  }
+  return Math.min(1, jw + containsBonus);
+}
+function scoreElement(query, element) {
+  const lowerQuery = query.toLowerCase();
+  const words = lowerQuery.split(/\s+/).filter((w) => w.length > 0);
+  let nameScore = 0;
+  if (element.name) {
+    const lowerName = element.name.toLowerCase();
+    if (lowerName === lowerQuery) {
+      nameScore = 1;
+    } else if (lowerName.includes(lowerQuery)) {
+      nameScore = 0.8;
+    } else if (words.length > 0) {
+      const matchedWords = words.filter((w) => lowerName.includes(w));
+      nameScore = matchedWords.length / words.length * 0.7;
+    } else {
+      nameScore = stringSimilarity(query, element.name) * 0.6;
+    }
+  }
+  let roleScore = 0;
+  const lowerRole = element.role.toLowerCase();
+  if (lowerRole === lowerQuery || lowerQuery.includes(lowerRole)) {
+    roleScore = 0.3;
+  } else if (words.some((w) => lowerRole.includes(w))) {
+    roleScore = 0.2;
+  }
+  let selectorScore = 0;
+  const lowerSelector = element.selector.toLowerCase();
+  if (words.some((w) => lowerSelector.includes(w))) {
+    selectorScore = 0.2;
+  }
+  const totalScore = nameScore * 0.6 + roleScore * 0.25 + selectorScore * 0.15;
+  return totalScore;
+}
+function explainMatch(query, element, score) {
+  const reasons = [];
+  const lowerQuery = query.toLowerCase();
+  const words = lowerQuery.split(/\s+/).filter((w) => w.length > 0);
+  if (element.name) {
+    const lowerName = element.name.toLowerCase();
+    if (lowerName === lowerQuery) {
+      reasons.push("exact name match");
+    } else if (lowerName.includes(lowerQuery)) {
+      reasons.push("name contains query");
+    } else if (words.some((w) => lowerName.includes(w))) {
+      const matchedWords = words.filter((w) => lowerName.includes(w));
+      reasons.push(`name contains: ${matchedWords.join(", ")}`);
+    } else if (stringSimilarity(query, element.name) > 0.5) {
+      reasons.push("similar name");
+    }
+  }
+  const lowerRole = element.role.toLowerCase();
+  if (lowerRole === lowerQuery || words.some((w) => w === lowerRole)) {
+    reasons.push(`role: ${element.role}`);
+  }
+  if (words.some((w) => element.selector.toLowerCase().includes(w))) {
+    reasons.push("selector match");
+  }
+  if (reasons.length === 0) {
+    reasons.push(`fuzzy match (score: ${score.toFixed(2)})`);
+  }
+  return reasons.join(", ");
+}
+function fuzzyMatchElements(query, elements, maxResults = 5) {
+  if (!query || query.length === 0) {
+    return [];
+  }
+  const THRESHOLD = 0.3;
+  const scored = elements.map((element) => ({
+    element,
+    score: scoreElement(query, element)
+  }));
+  return scored.filter((s) => s.score >= THRESHOLD).sort((a, b) => b.score - a.score).slice(0, maxResults).map((s) => ({
+    element: s.element,
+    score: s.score,
+    matchReason: explainMatch(query, s.element, s.score)
+  }));
+}
+
+// src/browser/hint-generator.ts
+var ACTION_ROLE_MAP = {
+  click: ["button", "link", "menuitem", "menuitemcheckbox", "menuitemradio", "tab", "option"],
+  fill: ["textbox", "searchbox", "textarea"],
+  type: ["textbox", "searchbox", "textarea"],
+  submit: ["button", "form"],
+  select: ["combobox", "listbox", "option"],
+  check: ["checkbox", "radio", "switch"],
+  uncheck: ["checkbox", "switch"],
+  focus: [],
+  // Any focusable element
+  hover: [],
+  // Any element
+  clear: ["textbox", "searchbox", "textarea"]
+};
+function extractIntent(selectors) {
+  const patterns = [];
+  let text = "";
+  for (const selector of selectors) {
+    if (selector.startsWith("ref:")) {
+      continue;
+    }
+    const idMatch = selector.match(/#([a-zA-Z0-9_-]+)/);
+    if (idMatch) {
+      patterns.push(idMatch[1]);
+    }
+    const ariaMatch = selector.match(/\[aria-label=["']([^"']+)["']\]/);
+    if (ariaMatch) {
+      patterns.push(ariaMatch[1]);
+    }
+    const testidMatch = selector.match(/\[data-testid=["']([^"']+)["']\]/);
+    if (testidMatch) {
+      patterns.push(testidMatch[1]);
+    }
+    const classMatch = selector.match(/\.([a-zA-Z0-9_-]+)/);
+    if (classMatch) {
+      patterns.push(classMatch[1]);
+    }
+  }
+  patterns.sort((a, b) => b.length - a.length);
+  text = patterns[0] ?? selectors[0] ?? "";
+  return { text, patterns };
+}
+function getHintType(selector) {
+  if (selector.startsWith("ref:")) return "ref";
+  if (selector.includes("data-testid")) return "testid";
+  if (selector.includes("aria-label")) return "aria";
+  if (selector.startsWith("#")) return "id";
+  return "css";
+}
+function getConfidence(score) {
+  if (score >= 0.8) return "high";
+  if (score >= 0.5) return "medium";
+  return "low";
+}
+function diversifyHints(candidates, maxHints) {
+  const hints = [];
+  const usedTypes = /* @__PURE__ */ new Set();
+  for (const candidate of candidates) {
+    if (hints.length >= maxHints) break;
+    const refSelector = `ref:${candidate.element.ref}`;
+    const hintType = getHintType(refSelector);
+    if (!usedTypes.has(hintType)) {
+      hints.push({
+        selector: refSelector,
+        reason: candidate.matchReason,
+        confidence: getConfidence(candidate.score),
+        element: {
+          ref: candidate.element.ref,
+          role: candidate.element.role,
+          name: candidate.element.name,
+          disabled: candidate.element.disabled
+        }
+      });
+      usedTypes.add(hintType);
+    } else if (hints.length < maxHints) {
+      hints.push({
+        selector: refSelector,
+        reason: candidate.matchReason,
+        confidence: getConfidence(candidate.score),
+        element: {
+          ref: candidate.element.ref,
+          role: candidate.element.role,
+          name: candidate.element.name,
+          disabled: candidate.element.disabled
+        }
+      });
+    }
+  }
+  return hints;
+}
+async function generateHints(page, failedSelectors, actionType, maxHints = 3) {
+  let snapshot;
+  try {
+    snapshot = await page.snapshot();
+  } catch {
+    return [];
+  }
+  const intent = extractIntent(failedSelectors);
+  const roleFilter = ACTION_ROLE_MAP[actionType] ?? [];
+  let candidates = snapshot.interactiveElements;
+  if (roleFilter.length > 0) {
+    candidates = candidates.filter((el) => roleFilter.includes(el.role));
+  }
+  const matches = fuzzyMatchElements(intent.text, candidates, maxHints * 2);
+  if (matches.length === 0) {
+    return [];
+  }
+  return diversifyHints(matches, maxHints);
+}
+
+// src/browser/types.ts
+var ElementNotFoundError = class extends Error {
+  selectors;
+  hints;
+  constructor(selectors, hints) {
+    const selectorList = Array.isArray(selectors) ? selectors : [selectors];
+    let msg = `Element not found: ${selectorList.join(", ")}`;
+    if (hints?.length) {
+      msg += `. Did you mean: ${hints.slice(0, 3).map((h) => `${h.element.ref} (${h.element.role} "${h.element.name}")`).join(", ")}`;
+    }
+    msg += `. Run 'bp snapshot' to see available elements.`;
+    super(msg);
+    this.name = "ElementNotFoundError";
+    this.selectors = selectorList;
+    this.hints = hints;
+  }
+};
+var TimeoutError = class extends Error {
+  constructor(message = "Operation timed out") {
+    const msg = message.includes("bp snapshot") ? message : `${message}. Run 'bp snapshot' to check current page state.`;
+    super(msg);
+    this.name = "TimeoutError";
+  }
+};
+var NavigationError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "NavigationError";
+  }
+};
+
+// src/actions/executor.ts
+var DEFAULT_TIMEOUT = 3e4;
+function classifyFailure(error) {
+  if (error instanceof ElementNotFoundError) {
+    return { reason: "missing" };
+  }
+  if (error instanceof ActionabilityError) {
+    switch (error.failureType) {
+      case "visible":
+        return { reason: "hidden" };
+      case "hitTarget":
+        return { reason: "covered", coveringElement: error.coveringElement };
+      case "enabled":
+        return { reason: "disabled" };
+      case "editable":
+        return { reason: error.message?.includes("readonly") ? "readonly" : "notEditable" };
+      case "stable":
+        return { reason: "replaced" };
+      default:
+        return { reason: "unknown" };
+    }
+  }
+  if (error instanceof TimeoutError) {
+    return { reason: "timeout" };
+  }
+  if (error instanceof NavigationError) {
+    return { reason: "navigation" };
+  }
+  if (error instanceof CDPError) {
+    return { reason: "cdpError" };
+  }
+  const msg = String(error?.message ?? error);
+  if (msg.includes("Could not find node") || msg.includes("does not belong to the document")) {
+    return { reason: "detached" };
+  }
+  return { reason: "unknown" };
+}
+function getSuggestion(reason) {
+  switch (reason) {
+    case "missing":
+      return "Element not found. Run 'snapshot' to see available elements, or try alternative selectors.";
+    case "hidden":
+      return "Element exists but is not visible. Try 'scroll' or wait for it to appear.";
+    case "covered":
+      return "Element is blocked by another element. Dismiss the covering element first.";
+    case "disabled":
+      return "Element is disabled. Complete prerequisite steps to enable it.";
+    case "readonly":
+      return "Element is readonly and cannot be edited directly.";
+    case "detached":
+      return "Element was removed from the DOM. Run 'snapshot' for fresh element refs.";
+    case "replaced":
+      return "Element was replaced in the DOM. Run 'snapshot' to get updated refs.";
+    case "notEditable":
+      return "Element is not an editable field. Try a different selector targeting an input or textarea.";
+    case "timeout":
+      return "Timed out waiting. The page may still be loading. Try increasing timeout.";
+    case "navigation":
+      return "Navigation failed. Check the URL and network connectivity.";
+    case "cdpError":
+      return "Browser connection error. Try 'bp connect' again.";
+    case "unknown":
+      return "Unexpected error. Run 'snapshot' to check page state.";
+    default: {
+      const _exhaustive = reason;
+      return `Unknown failure: ${_exhaustive}`;
+    }
+  }
+}
+var BatchExecutor = class {
+  page;
+  constructor(page) {
+    this.page = page;
+  }
+  /**
+   * Execute a batch of steps
+   */
+  async execute(steps, options = {}) {
+    const { timeout = DEFAULT_TIMEOUT, onFail = "stop" } = options;
+    const results = [];
+    const startTime = Date.now();
+    for (let i = 0; i < steps.length; i++) {
+      const step = steps[i];
+      const stepStart = Date.now();
+      const maxAttempts = (step.retry ?? 0) + 1;
+      const retryDelay = step.retryDelay ?? 500;
+      let lastError;
+      let succeeded = false;
+      for (let attempt = 0; attempt < maxAttempts; attempt++) {
+        if (attempt > 0) {
+          await new Promise((resolve) => setTimeout(resolve, retryDelay));
+        }
+        try {
+          const result = await this.executeStep(step, timeout);
+          results.push({
+            index: i,
+            action: step.action,
+            selector: step.selector,
+            selectorUsed: result.selectorUsed,
+            success: true,
+            durationMs: Date.now() - stepStart,
+            result: result.value,
+            text: result.text
+          });
+          succeeded = true;
+          break;
+        } catch (error) {
+          lastError = error instanceof Error ? error : new Error(String(error));
+        }
+      }
+      if (!succeeded) {
+        const errorMessage = lastError?.message ?? "Unknown error";
+        let hints = lastError instanceof ElementNotFoundError ? lastError.hints : void 0;
+        const { reason, coveringElement } = classifyFailure(lastError);
+        if (step.selector && !step.optional && ["missing", "hidden", "covered", "disabled", "detached", "replaced"].includes(reason)) {
+          try {
+            const selectors = Array.isArray(step.selector) ? step.selector : [step.selector];
+            const autoHints = await generateHints(this.page, selectors, step.action, 3);
+            if (autoHints.length > 0) {
+              hints = autoHints;
+            }
+          } catch {
+          }
+        }
+        results.push({
+          index: i,
+          action: step.action,
+          selector: step.selector,
+          success: false,
+          durationMs: Date.now() - stepStart,
+          error: errorMessage,
+          hints,
+          failureReason: reason,
+          coveringElement,
+          suggestion: getSuggestion(reason)
+        });
+        if (onFail === "stop" && !step.optional) {
+          return {
+            success: false,
+            stoppedAtIndex: i,
+            steps: results,
+            totalDurationMs: Date.now() - startTime
+          };
+        }
+      }
+    }
+    const allSuccess = results.every((r) => r.success || steps[r.index]?.optional);
+    return {
+      success: allSuccess,
+      steps: results,
+      totalDurationMs: Date.now() - startTime
+    };
+  }
+  /**
+   * Execute a single step
+   */
+  async executeStep(step, defaultTimeout) {
+    const timeout = step.timeout ?? defaultTimeout;
+    const optional = step.optional ?? false;
+    switch (step.action) {
+      case "goto": {
+        if (!step.url) throw new Error("goto requires url");
+        await this.page.goto(step.url, { timeout, optional });
+        return {};
+      }
+      case "click": {
+        if (!step.selector) throw new Error("click requires selector");
+        if (step.waitForNavigation === true) {
+          const navPromise = this.page.waitForNavigation({ timeout, optional });
+          await this.page.click(step.selector, { timeout, optional });
+          await navPromise;
+        } else {
+          await this.page.click(step.selector, { timeout, optional });
+        }
+        return { selectorUsed: this.getUsedSelector(step.selector) };
+      }
+      case "fill": {
+        if (!step.selector) throw new Error("fill requires selector");
+        if (typeof step.value !== "string") throw new Error("fill requires string value");
+        await this.page.fill(step.selector, step.value, {
+          timeout,
+          optional,
+          blur: step.blur
+        });
+        return { selectorUsed: this.getUsedSelector(step.selector) };
+      }
+      case "type": {
+        if (!step.selector) throw new Error("type requires selector");
+        if (typeof step.value !== "string") throw new Error("type requires string value");
+        await this.page.type(step.selector, step.value, {
+          timeout,
+          optional,
+          delay: step.delay ?? 50
+        });
+        return { selectorUsed: this.getUsedSelector(step.selector) };
+      }
+      case "select": {
+        if (step.trigger && step.option && typeof step.value === "string") {
+          await this.page.select(
+            {
+              trigger: step.trigger,
+              option: step.option,
+              value: step.value,
+              match: step.match
+            },
+            { timeout, optional }
+          );
+          return { selectorUsed: this.getUsedSelector(step.trigger) };
+        }
+        if (!step.selector) throw new Error("select requires selector");
+        if (!step.value) throw new Error("select requires value");
+        await this.page.select(step.selector, step.value, { timeout, optional });
+        return { selectorUsed: this.getUsedSelector(step.selector) };
+      }
+      case "check": {
+        if (!step.selector) throw new Error("check requires selector");
+        await this.page.check(step.selector, { timeout, optional });
+        return { selectorUsed: this.getUsedSelector(step.selector) };
+      }
+      case "uncheck": {
+        if (!step.selector) throw new Error("uncheck requires selector");
+        await this.page.uncheck(step.selector, { timeout, optional });
+        return { selectorUsed: this.getUsedSelector(step.selector) };
+      }
+      case "submit": {
+        if (!step.selector) throw new Error("submit requires selector");
+        await this.page.submit(step.selector, {
+          timeout,
+          optional,
+          method: step.method ?? "enter+click",
+          waitForNavigation: step.waitForNavigation
+        });
+        return { selectorUsed: this.getUsedSelector(step.selector) };
+      }
+      case "press": {
+        if (!step.key) throw new Error("press requires key");
+        try {
+          await this.page.press(step.key, {
+            modifiers: step.modifiers
+          });
+        } catch (e) {
+          if (optional) return {};
+          throw e;
+        }
+        return {};
+      }
+      case "shortcut": {
+        if (!step.combo) throw new Error("shortcut requires combo");
+        try {
+          await this.page.shortcut(step.combo);
+        } catch (e) {
+          if (optional) return {};
+          throw e;
+        }
+        return {};
+      }
+      case "focus": {
+        if (!step.selector) throw new Error("focus requires selector");
+        await this.page.focus(step.selector, { timeout, optional });
+        return { selectorUsed: this.getUsedSelector(step.selector) };
+      }
+      case "hover": {
+        if (!step.selector) throw new Error("hover requires selector");
+        await this.page.hover(step.selector, { timeout, optional });
+        return { selectorUsed: this.getUsedSelector(step.selector) };
+      }
+      case "scroll": {
+        if (step.x !== void 0 || step.y !== void 0) {
+          await this.page.scroll("body", { x: step.x, y: step.y, timeout, optional });
+          return {};
+        }
+        if (!step.selector && (step.direction || step.amount !== void 0)) {
+          const amount = step.amount ?? 500;
+          const direction = step.direction ?? "down";
+          const deltaY = direction === "down" ? amount : direction === "up" ? -amount : 0;
+          const deltaX = direction === "right" ? amount : direction === "left" ? -amount : 0;
+          await this.page.evaluate(`window.scrollBy(${deltaX}, ${deltaY})`);
+          return {};
+        }
+        if (!step.selector) throw new Error("scroll requires selector, coordinates, or direction");
+        await this.page.scroll(step.selector, { timeout, optional });
+        return { selectorUsed: this.getUsedSelector(step.selector) };
+      }
+      case "wait": {
+        if (!step.selector && !step.waitFor) {
+          const delay = step.timeout ?? 1e3;
+          await new Promise((resolve) => setTimeout(resolve, delay));
+          return {};
+        }
+        if (step.waitFor === "navigation") {
+          await this.page.waitForNavigation({ timeout, optional });
+          return {};
+        }
+        if (step.waitFor === "networkIdle") {
+          await this.page.waitForNetworkIdle({ timeout, optional });
+          return {};
+        }
+        if (!step.selector)
+          throw new Error(
+            "wait requires selector (or waitFor: navigation/networkIdle, or timeout for simple delay)"
+          );
+        await this.page.waitFor(step.selector, {
+          timeout,
+          optional,
+          state: step.waitFor ?? "visible"
+        });
+        return { selectorUsed: this.getUsedSelector(step.selector) };
+      }
+      case "snapshot": {
+        const snapshot = await this.page.snapshot();
+        return { value: snapshot };
+      }
+      case "forms": {
+        return { value: await this.page.forms() };
+      }
+      case "screenshot": {
+        const data = await this.page.screenshot({
+          format: step.format,
+          quality: step.quality,
+          fullPage: step.fullPage
+        });
+        return { value: data };
+      }
+      case "evaluate": {
+        if (typeof step.value !== "string")
+          throw new Error("evaluate requires string value (expression)");
+        const result = await this.page.evaluate(step.value);
+        return { value: result };
+      }
+      case "text": {
+        const selector = Array.isArray(step.selector) ? step.selector[0] : step.selector;
+        const text = await this.page.text(selector);
+        return { text, selectorUsed: selector };
+      }
+      case "newTab": {
+        const { targetId } = await this.page.cdpClient.send(
+          "Target.createTarget",
+          {
+            url: step.url ?? "about:blank"
+          },
+          null
+        );
+        return { value: { targetId } };
+      }
+      case "closeTab": {
+        const targetId = step.targetId ?? this.page.targetId;
+        await this.page.cdpClient.send("Target.closeTarget", { targetId }, null);
+        return { value: { targetId, closedCurrent: targetId === this.page.targetId } };
+      }
+      case "switchFrame": {
+        if (!step.selector) throw new Error("switchFrame requires selector");
+        await this.page.switchToFrame(step.selector, { timeout, optional });
+        return { selectorUsed: this.getUsedSelector(step.selector) };
+      }
+      case "switchToMain": {
+        await this.page.switchToMain();
+        return {};
+      }
+      case "assertVisible": {
+        if (!step.selector) throw new Error("assertVisible requires selector");
+        const el = await this.page.waitFor(step.selector, {
+          timeout,
+          optional: true,
+          state: "visible"
+        });
+        if (!el) {
+          throw new Error(
+            `Assertion failed: selector ${JSON.stringify(step.selector)} is not visible`
+          );
+        }
+        return { selectorUsed: this.getUsedSelector(step.selector) };
+      }
+      case "assertExists": {
+        if (!step.selector) throw new Error("assertExists requires selector");
+        const el = await this.page.waitFor(step.selector, {
+          timeout,
+          optional: true,
+          state: "attached"
+        });
+        if (!el) {
+          throw new Error(
+            `Assertion failed: selector ${JSON.stringify(step.selector)} does not exist`
+          );
+        }
+        return { selectorUsed: this.getUsedSelector(step.selector) };
+      }
+      case "assertText": {
+        const selector = Array.isArray(step.selector) ? step.selector[0] : step.selector;
+        const text = await this.page.text(selector);
+        const expected = step.expect ?? step.value;
+        if (typeof expected !== "string") throw new Error("assertText requires expect or value");
+        if (!text.includes(expected)) {
+          throw new Error(
+            `Assertion failed: text does not contain ${JSON.stringify(expected)}. Got: ${JSON.stringify(text.slice(0, 200))}`
+          );
+        }
+        return { selectorUsed: selector, text };
+      }
+      case "assertUrl": {
+        const currentUrl = await this.page.url();
+        const expected = step.expect ?? step.url;
+        if (typeof expected !== "string") throw new Error("assertUrl requires expect or url");
+        if (!currentUrl.includes(expected)) {
+          throw new Error(
+            `Assertion failed: URL does not contain ${JSON.stringify(expected)}. Got: ${JSON.stringify(currentUrl)}`
+          );
+        }
+        return { value: currentUrl };
+      }
+      case "assertValue": {
+        if (!step.selector) throw new Error("assertValue requires selector");
+        const expected = step.expect ?? step.value;
+        if (typeof expected !== "string") throw new Error("assertValue requires expect or value");
+        const found = await this.page.waitFor(step.selector, {
+          timeout,
+          optional: true,
+          state: "attached"
+        });
+        if (!found) {
+          throw new Error(`Assertion failed: selector ${JSON.stringify(step.selector)} not found`);
+        }
+        const usedSelector = this.getUsedSelector(step.selector);
+        const actual = await this.page.evaluate(
+          `(function() { var el = document.querySelector(${JSON.stringify(usedSelector)}); return el ? el.value : null; })()`
+        );
+        if (actual !== expected) {
+          throw new Error(
+            `Assertion failed: value of ${JSON.stringify(usedSelector)} is ${JSON.stringify(actual)}, expected ${JSON.stringify(expected)}`
+          );
+        }
+        return { selectorUsed: usedSelector, value: actual };
+      }
+      default: {
+        const action = step.action;
+        const aliases = {
+          execute: "evaluate",
+          navigate: "goto",
+          input: "fill",
+          tap: "click",
+          go: "goto",
+          run: "evaluate",
+          capture: "screenshot",
+          inspect: "snapshot",
+          enter: "press",
+          keypress: "press",
+          hotkey: "shortcut",
+          keybinding: "shortcut",
+          nav: "goto",
+          open: "goto",
+          visit: "goto",
+          browse: "goto",
+          load: "goto",
+          write: "fill",
+          set: "fill",
+          pick: "select",
+          choose: "select",
+          send: "press",
+          eval: "evaluate",
+          js: "evaluate",
+          script: "evaluate",
+          snap: "snapshot",
+          accessibility: "snapshot",
+          a11y: "snapshot",
+          formslist: "forms",
+          image: "screenshot",
+          pic: "screenshot",
+          frame: "switchFrame",
+          iframe: "switchFrame",
+          newtab: "newTab",
+          opentab: "newTab",
+          createtab: "newTab",
+          closetab: "closeTab",
+          assert_visible: "assertVisible",
+          assert_exists: "assertExists",
+          assert_text: "assertText",
+          assert_url: "assertUrl",
+          assert_value: "assertValue",
+          checkvisible: "assertVisible",
+          checkexists: "assertExists",
+          checktext: "assertText",
+          checkurl: "assertUrl",
+          checkvalue: "assertValue"
+        };
+        const suggestion = aliases[action.toLowerCase()];
+        const hint = suggestion ? ` Did you mean "${suggestion}"?` : "";
+        const valid = "goto, click, fill, type, select, check, uncheck, submit, press, shortcut, focus, hover, scroll, wait, snapshot, forms, screenshot, evaluate, text, newTab, closeTab, switchFrame, switchToMain, assertVisible, assertExists, assertText, assertUrl, assertValue";
+        throw new Error(`Unknown action "${action}".${hint}
+
+Valid actions: ${valid}`);
+      }
+    }
+  }
+  /**
+   * Get the actual selector that matched the element.
+   * Uses the last matched selector tracked by Page, falls back to first selector if unavailable.
+   */
+  getUsedSelector(selector) {
+    const matched = this.page.getLastMatchedSelector();
+    if (matched) return matched;
+    return Array.isArray(selector) ? selector[0] : selector;
+  }
+};
+function addBatchToPage(page) {
+  const executor = new BatchExecutor(page);
+  return Object.assign(page, {
+    batch: (steps, options) => executor.execute(steps, options)
+  });
+}
+
+// src/actions/validate.ts
+function levenshtein(a, b) {
+  const m = a.length;
+  const n = b.length;
+  const dp = Array.from({ length: m + 1 }, () => Array(n + 1).fill(0));
+  for (let i = 0; i <= m; i++) dp[i][0] = i;
+  for (let j = 0; j <= n; j++) dp[0][j] = j;
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      dp[i][j] = a[i - 1] === b[j - 1] ? dp[i - 1][j - 1] : 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1]);
+    }
+  }
+  return dp[m][n];
+}
+var ACTION_ALIASES = {
+  execute: "evaluate",
+  navigate: "goto",
+  input: "fill",
+  tap: "click",
+  go: "goto",
+  run: "evaluate",
+  capture: "screenshot",
+  inspect: "snapshot",
+  enter: "press",
+  keypress: "press",
+  hotkey: "shortcut",
+  keybinding: "shortcut",
+  nav: "goto",
+  open: "goto",
+  visit: "goto",
+  browse: "goto",
+  load: "goto",
+  write: "fill",
+  set: "fill",
+  pick: "select",
+  choose: "select",
+  send: "press",
+  eval: "evaluate",
+  js: "evaluate",
+  script: "evaluate",
+  snap: "snapshot",
+  accessibility: "snapshot",
+  a11y: "snapshot",
+  image: "screenshot",
+  pic: "screenshot",
+  frame: "switchFrame",
+  iframe: "switchFrame",
+  formslist: "forms",
+  newtab: "newTab",
+  opentab: "newTab",
+  createtab: "newTab",
+  closetab: "closeTab",
+  assert_visible: "assertVisible",
+  assert_exists: "assertExists",
+  assert_text: "assertText",
+  assert_url: "assertUrl",
+  assert_value: "assertValue",
+  checkvisible: "assertVisible",
+  checkexists: "assertExists",
+  checktext: "assertText",
+  checkurl: "assertUrl",
+  checkvalue: "assertValue"
+};
+var PROPERTY_ALIASES = {
+  expression: "value",
+  href: "url",
+  target: "selector",
+  element: "selector",
+  code: "value",
+  script: "value",
+  src: "url",
+  link: "url",
+  char: "key",
+  text: "value",
+  query: "selector",
+  el: "selector",
+  elem: "selector",
+  css: "selector",
+  xpath: "selector",
+  input: "value",
+  content: "value",
+  keys: "key",
+  shortcutKey: "combo",
+  hotkey: "combo",
+  keybinding: "combo",
+  button: "key",
+  address: "url",
+  page: "url",
+  path: "url",
+  tabId: "targetId"
+};
+var ACTION_RULES = {
+  goto: {
+    required: { url: { type: "string" } },
+    optional: {}
+  },
+  click: {
+    required: { selector: { type: "string|string[]" } },
+    optional: {
+      waitForNavigation: { type: "boolean|auto" }
+    }
+  },
+  fill: {
+    required: { selector: { type: "string|string[]" }, value: { type: "string" } },
+    optional: {
+      blur: { type: "boolean" }
+    }
+  },
+  type: {
+    required: { selector: { type: "string|string[]" }, value: { type: "string" } },
+    optional: {
+      delay: { type: "number" },
+      blur: { type: "boolean" }
+    }
+  },
+  select: {
+    required: {},
+    optional: {
+      selector: { type: "string|string[]" },
+      value: { type: "string|string[]" },
+      trigger: { type: "string|string[]" },
+      option: { type: "string|string[]" },
+      match: { type: "string", enum: ["text", "value", "contains"] }
+    }
+  },
+  check: {
+    required: { selector: { type: "string|string[]" } },
+    optional: {}
+  },
+  uncheck: {
+    required: { selector: { type: "string|string[]" } },
+    optional: {}
+  },
+  submit: {
+    required: { selector: { type: "string|string[]" } },
+    optional: {
+      method: { type: "string", enum: ["enter", "click", "enter+click"] },
+      waitForNavigation: { type: "boolean|auto" }
+    }
+  },
+  press: {
+    required: { key: { type: "string" } },
+    optional: {
+      modifiers: { type: "string|string[]" }
+    }
+  },
+  shortcut: {
+    required: { combo: { type: "string" } },
+    optional: {}
+  },
+  focus: {
+    required: { selector: { type: "string|string[]" } },
+    optional: {}
+  },
+  hover: {
+    required: { selector: { type: "string|string[]" } },
+    optional: {}
+  },
+  scroll: {
+    required: {},
+    optional: {
+      selector: { type: "string|string[]" },
+      x: { type: "number" },
+      y: { type: "number" },
+      direction: { type: "string", enum: ["up", "down", "left", "right"] },
+      amount: { type: "number" }
+    }
+  },
+  wait: {
+    required: {},
+    optional: {
+      selector: { type: "string|string[]" },
+      waitFor: {
+        type: "string",
+        enum: ["visible", "hidden", "attached", "detached", "navigation", "networkIdle"]
+      }
+    }
+  },
+  snapshot: {
+    required: {},
+    optional: {}
+  },
+  screenshot: {
+    required: {},
+    optional: {
+      format: { type: "string", enum: ["png", "jpeg", "webp"] },
+      quality: { type: "number" },
+      fullPage: { type: "boolean" }
+    }
+  },
+  forms: {
+    required: {},
+    optional: {}
+  },
+  evaluate: {
+    required: { value: { type: "string" } },
+    optional: {}
+  },
+  text: {
+    required: {},
+    optional: {
+      selector: { type: "string|string[]" }
+    }
+  },
+  switchFrame: {
+    required: { selector: { type: "string|string[]" } },
+    optional: {}
+  },
+  newTab: {
+    required: {},
+    optional: {
+      url: { type: "string" }
+    }
+  },
+  closeTab: {
+    required: {},
+    optional: {
+      targetId: { type: "string" }
+    }
+  },
+  switchToMain: {
+    required: {},
+    optional: {}
+  },
+  assertVisible: {
+    required: { selector: { type: "string|string[]" } },
+    optional: {}
+  },
+  assertExists: {
+    required: { selector: { type: "string|string[]" } },
+    optional: {}
+  },
+  assertText: {
+    required: {},
+    optional: {
+      selector: { type: "string|string[]" },
+      expect: { type: "string" },
+      value: { type: "string" }
+    }
+  },
+  assertUrl: {
+    required: {},
+    optional: {
+      expect: { type: "string" },
+      url: { type: "string" }
+    }
+  },
+  assertValue: {
+    required: { selector: { type: "string|string[]" } },
+    optional: {
+      expect: { type: "string" },
+      value: { type: "string" }
+    }
+  }
+};
+var VALID_ACTIONS = Object.keys(ACTION_RULES);
+var VALID_ACTIONS_LIST = VALID_ACTIONS.join(", ");
+var KNOWN_STEP_FIELDS = /* @__PURE__ */ new Set([
+  "action",
+  "selector",
+  "url",
+  "value",
+  "targetId",
+  "key",
+  "combo",
+  "modifiers",
+  "waitFor",
+  "timeout",
+  "optional",
+  "method",
+  "blur",
+  "delay",
+  "waitForNavigation",
+  "trigger",
+  "option",
+  "match",
+  "x",
+  "y",
+  "direction",
+  "amount",
+  "format",
+  "quality",
+  "fullPage",
+  "expect",
+  "retry",
+  "retryDelay"
+]);
+function resolveAction(name) {
+  if (VALID_ACTIONS.includes(name)) {
+    return { action: name };
+  }
+  const lower = name.toLowerCase();
+  if (ACTION_ALIASES[lower]) {
+    return {
+      action: ACTION_ALIASES[lower],
+      suggestion: `Did you mean "${ACTION_ALIASES[lower]}"?`
+    };
+  }
+  let best = null;
+  let bestDist = Infinity;
+  for (const valid of VALID_ACTIONS) {
+    const dist = levenshtein(lower, valid);
+    if (dist < bestDist) {
+      bestDist = dist;
+      best = valid;
+    }
+  }
+  if (best && bestDist <= 2) {
+    return { action: best, suggestion: `Did you mean "${best}"?` };
+  }
+  return null;
+}
+function suggestProperty(name) {
+  if (PROPERTY_ALIASES[name]) {
+    return PROPERTY_ALIASES[name];
+  }
+  let best = null;
+  let bestDist = Infinity;
+  for (const known of KNOWN_STEP_FIELDS) {
+    if (known === "action") continue;
+    const dist = levenshtein(name, known);
+    if (dist < bestDist) {
+      bestDist = dist;
+      best = known;
+    }
+  }
+  if (best && bestDist <= 2) {
+    return best;
+  }
+  return void 0;
+}
+function checkFieldType(value, rule) {
+  switch (rule.type) {
+    case "string":
+      if (typeof value !== "string") return `expected string, got ${typeof value}`;
+      if (rule.enum && !rule.enum.includes(value)) {
+        return `must be one of: ${rule.enum.join(", ")}`;
+      }
+      return null;
+    case "string|string[]":
+      if (typeof value !== "string" && !Array.isArray(value)) {
+        return `expected string or string[], got ${typeof value}`;
+      }
+      if (Array.isArray(value) && value.some((v) => typeof v !== "string")) {
+        return "array elements must be strings";
+      }
+      return null;
+    case "number":
+      if (typeof value !== "number") return `expected number, got ${typeof value}`;
+      return null;
+    case "boolean":
+      if (typeof value !== "boolean") return `expected boolean, got ${typeof value}`;
+      return null;
+    case "boolean|auto":
+      if (typeof value !== "boolean" && value !== "auto") {
+        return `expected boolean or "auto", got ${typeof value}`;
+      }
+      return null;
+    default: {
+      const _exhaustive = rule.type;
+      return `unknown type: ${_exhaustive}`;
+    }
+  }
+}
+function validateSteps(steps) {
+  const errors = [];
+  for (let i = 0; i < steps.length; i++) {
+    const step = steps[i];
+    if (!step || typeof step !== "object" || Array.isArray(step)) {
+      errors.push({
+        stepIndex: i,
+        field: "step",
+        message: "step must be a JSON object."
+      });
+      continue;
+    }
+    const obj = step;
+    if (!("action" in obj)) {
+      errors.push({
+        stepIndex: i,
+        field: "action",
+        message: 'missing required "action" field.'
+      });
+      continue;
+    }
+    const actionName = obj["action"];
+    if (typeof actionName !== "string") {
+      errors.push({
+        stepIndex: i,
+        field: "action",
+        message: `"action" must be a string, got ${typeof actionName}.`
+      });
+      continue;
+    }
+    const resolved = resolveAction(actionName);
+    if (!resolved) {
+      errors.push({
+        stepIndex: i,
+        field: "action",
+        message: `unknown action "${actionName}".`,
+        suggestion: `Valid actions: ${VALID_ACTIONS_LIST}`
+      });
+      continue;
+    }
+    if (resolved.suggestion) {
+      errors.push({
+        stepIndex: i,
+        field: "action",
+        message: `unknown action "${actionName}". ${resolved.suggestion}`,
+        suggestion: resolved.suggestion
+      });
+      continue;
+    }
+    const action = resolved.action;
+    const rule = ACTION_RULES[action];
+    for (const key of Object.keys(obj)) {
+      if (key === "action") continue;
+      if (KNOWN_STEP_FIELDS.has(key)) continue;
+      const canonical = PROPERTY_ALIASES[key];
+      if (canonical) {
+        if (!(canonical in obj)) {
+          obj[canonical] = obj[key];
+        }
+        delete obj[key];
+        continue;
+      }
+      const suggestion = suggestProperty(key);
+      errors.push({
+        stepIndex: i,
+        field: key,
+        message: suggestion ? `unknown property "${key}". Did you mean "${suggestion}"?` : `unknown property "${key}".`,
+        suggestion: suggestion ? `Did you mean "${suggestion}"?` : void 0
+      });
+    }
+    for (const [field, fieldRule] of Object.entries(rule.required)) {
+      if (!(field in obj) || obj[field] === void 0) {
+        errors.push({
+          stepIndex: i,
+          field,
+          message: `missing required "${field}" (${fieldRule.type}).`
+        });
+      } else {
+        const typeErr = checkFieldType(obj[field], fieldRule);
+        if (typeErr) {
+          errors.push({
+            stepIndex: i,
+            field,
+            message: `"${field}" ${typeErr}.`
+          });
+        }
+      }
+    }
+    for (const [field, fieldRule] of Object.entries(rule.optional)) {
+      if (field in obj && obj[field] !== void 0) {
+        const typeErr = checkFieldType(obj[field], fieldRule);
+        if (typeErr) {
+          errors.push({
+            stepIndex: i,
+            field,
+            message: `"${field}" ${typeErr}.`
+          });
+        }
+      }
+    }
+    if ("timeout" in obj && obj["timeout"] !== void 0) {
+      if (typeof obj["timeout"] !== "number") {
+        errors.push({
+          stepIndex: i,
+          field: "timeout",
+          message: `"timeout" expected number, got ${typeof obj["timeout"]}.`
+        });
+      }
+    }
+    if ("optional" in obj && obj["optional"] !== void 0) {
+      if (typeof obj["optional"] !== "boolean") {
+        errors.push({
+          stepIndex: i,
+          field: "optional",
+          message: `"optional" expected boolean, got ${typeof obj["optional"]}.`
+        });
+      }
+    }
+    if ("retry" in obj && obj["retry"] !== void 0) {
+      if (typeof obj["retry"] !== "number") {
+        errors.push({
+          stepIndex: i,
+          field: "retry",
+          message: `"retry" expected number, got ${typeof obj["retry"]}.`
+        });
+      }
+    }
+    if ("retryDelay" in obj && obj["retryDelay"] !== void 0) {
+      if (typeof obj["retryDelay"] !== "number") {
+        errors.push({
+          stepIndex: i,
+          field: "retryDelay",
+          message: `"retryDelay" expected number, got ${typeof obj["retryDelay"]}.`
+        });
+      }
+    }
+    if (action === "assertText") {
+      if (!("expect" in obj) && !("value" in obj)) {
+        errors.push({
+          stepIndex: i,
+          field: "expect",
+          message: 'assertText requires "expect" or "value" containing the expected text.'
+        });
+      }
+    }
+    if (action === "assertUrl") {
+      if (!("expect" in obj) && !("url" in obj)) {
+        errors.push({
+          stepIndex: i,
+          field: "expect",
+          message: 'assertUrl requires "expect" or "url" containing the expected URL substring.'
+        });
+      }
+    }
+    if (action === "assertValue") {
+      if (!("expect" in obj) && !("value" in obj)) {
+        errors.push({
+          stepIndex: i,
+          field: "expect",
+          message: 'assertValue requires "expect" or "value" containing the expected value.'
+        });
+      }
+    }
+    if (action === "select") {
+      const hasNative = "selector" in obj && "value" in obj;
+      const hasCustom = "trigger" in obj && "option" in obj && "value" in obj;
+      if (!hasNative && !hasCustom) {
+        errors.push({
+          stepIndex: i,
+          field: "selector",
+          message: "select requires either (selector + value) for native select, or (trigger + option + value) for custom select."
+        });
+      }
+    }
+  }
+  return {
+    valid: errors.length === 0,
+    errors,
+    formatted() {
+      if (errors.length === 0) return "";
+      const lines = [`Validation failed (${errors.length} error${errors.length > 1 ? "s" : ""}):`];
+      for (const err of errors) {
+        const stepLabel = err.field === "action" || err.field === "step" ? `Step ${err.stepIndex}` : `Step ${err.stepIndex}`;
+        lines.push("");
+        lines.push(`  ${stepLabel}: ${err.message}`);
+        if (err.suggestion && !err.message.includes(err.suggestion)) {
+          lines.push(`    ${err.suggestion}`);
+        }
+        const step = steps[err.stepIndex];
+        if (step && typeof step === "object") {
+          lines.push(`    Got: ${JSON.stringify(step)}`);
+        }
+      }
+      const hasEvaluateError = errors.some((err) => {
+        const step = steps[err.stepIndex];
+        return step && typeof step === "object" && step["action"] === "evaluate";
+      });
+      if (hasEvaluateError) {
+        lines.push("");
+        lines.push(
+          "Tip: For JavaScript evaluation, use 'bp eval' instead \u2014 no JSON wrapping needed:"
+        );
+        lines.push("  bp eval 'your.expression.here'");
+      }
+      lines.push("");
+      lines.push(`Valid actions: ${VALID_ACTIONS_LIST}`);
+      return lines.join("\n");
+    }
+  };
+}
+
+export {
+  ActionabilityError,
+  ensureActionable,
+  generateHints,
+  ElementNotFoundError,
+  TimeoutError,
+  NavigationError,
+  BatchExecutor,
+  addBatchToPage,
+  validateSteps
+};