browser-pilot 0.0.11 → 0.0.13

package/dist/actions.cjs

@@ -26,6 +26,263 @@ __export(actions_exports, {
 });
 module.exports = __toCommonJS(actions_exports);
 
+// 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;
+  }
+};
+
+// 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;
@@ -43,9 +300,101 @@ var ElementNotFoundError = class extends Error {
     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/cdp/protocol.ts
+var CDPError = class extends Error {
+  code;
+  data;
+  constructor(error) {
+    super(error.message);
+    this.name = "CDPError";
+    this.code = error.code;
+    this.data = error.data;
+  }
+};
 
 // 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) {
@@ -61,21 +410,46 @@ var BatchExecutor = class {
     for (let i = 0; i < steps.length; i++) {
       const step = steps[i];
       const stepStart = Date.now();
-      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
-        });
-      } catch (error) {
-        const errorMessage = error instanceof Error ? error.message : String(error);
-        const hints = error instanceof ElementNotFoundError ? error.hints : void 0;
+      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,
@@ -83,7 +457,10 @@ var BatchExecutor = class {
           success: false,
           durationMs: Date.now() - stepStart,
           error: errorMessage,
-          hints
+          hints,
+          failureReason: reason,
+          coveringElement,
+          suggestion: getSuggestion(reason)
         });
         if (onFail === "stop" && !step.optional) {
           return {
@@ -185,7 +562,24 @@ var BatchExecutor = class {
       }
       case "press": {
         if (!step.key) throw new Error("press requires key");
-        await this.page.press(step.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": {
@@ -244,6 +638,9 @@ var BatchExecutor = class {
         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,
@@ -263,6 +660,21 @@ var BatchExecutor = class {
         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 });
@@ -272,6 +684,80 @@ var BatchExecutor = class {
         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 = {
@@ -284,16 +770,48 @@ var BatchExecutor = class {
           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",
-          frame: "switchFrame"
+          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, focus, hover, scroll, wait, snapshot, screenshot, evaluate, text, switchFrame, switchToMain";
+        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}`);
@@ -342,6 +860,8 @@ var ACTION_ALIASES = {
   inspect: "snapshot",
   enter: "press",
   keypress: "press",
+  hotkey: "shortcut",
+  keybinding: "shortcut",
   nav: "goto",
   open: "goto",
   visit: "goto",
@@ -361,7 +881,22 @@ var ACTION_ALIASES = {
   image: "screenshot",
   pic: "screenshot",
   frame: "switchFrame",
-  iframe: "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",
@@ -382,10 +917,14 @@ var PROPERTY_ALIASES = {
   input: "value",
   content: "value",
   keys: "key",
+  shortcutKey: "combo",
+  hotkey: "combo",
+  keybinding: "combo",
   button: "key",
   address: "url",
   page: "url",
-  path: "url"
+  path: "url",
+  tabId: "targetId"
 };
 var ACTION_RULES = {
   goto: {
@@ -395,7 +934,7 @@ var ACTION_RULES = {
   click: {
     required: { selector: { type: "string|string[]" } },
     optional: {
-      waitForNavigation: { type: "boolean" }
+      waitForNavigation: { type: "boolean|auto" }
     }
   },
   fill: {
@@ -407,7 +946,8 @@ var ACTION_RULES = {
   type: {
     required: { selector: { type: "string|string[]" }, value: { type: "string" } },
     optional: {
-      delay: { type: "number" }
+      delay: { type: "number" },
+      blur: { type: "boolean" }
     }
   },
   select: {
@@ -437,6 +977,12 @@ var ACTION_RULES = {
   },
   press: {
     required: { key: { type: "string" } },
+    optional: {
+      modifiers: { type: "string|string[]" }
+    }
+  },
+  shortcut: {
+    required: { combo: { type: "string" } },
     optional: {}
   },
   focus: {
@@ -479,6 +1025,10 @@ var ACTION_RULES = {
       fullPage: { type: "boolean" }
     }
   },
+  forms: {
+    required: {},
+    optional: {}
+  },
   evaluate: {
     required: { value: { type: "string" } },
     optional: {}
@@ -493,9 +1043,51 @@ var ACTION_RULES = {
     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);
@@ -505,7 +1097,10 @@ var KNOWN_STEP_FIELDS = /* @__PURE__ */ new Set([
   "selector",
   "url",
   "value",
+  "targetId",
   "key",
+  "combo",
+  "modifiers",
   "waitFor",
   "timeout",
   "optional",
@@ -522,7 +1117,10 @@ var KNOWN_STEP_FIELDS = /* @__PURE__ */ new Set([
   "amount",
   "format",
   "quality",
-  "fullPage"
+  "fullPage",
+  "expect",
+  "retry",
+  "retryDelay"
 ]);
 function resolveAction(name) {
   if (VALID_ACTIONS.includes(name)) {
@@ -595,6 +1193,10 @@ function checkFieldType(value, rule) {
         return `expected boolean or "auto", got ${typeof value}`;
       }
       return null;
+    default: {
+      const _exhaustive = rule.type;
+      return `unknown type: ${_exhaustive}`;
+    }
   }
 }
 function validateSteps(steps) {
@@ -650,15 +1252,22 @@ function validateSteps(steps) {
     const rule = ACTION_RULES[action];
     for (const key of Object.keys(obj)) {
       if (key === "action") continue;
-      if (!KNOWN_STEP_FIELDS.has(key)) {
-        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
-        });
+      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) {
@@ -708,6 +1317,51 @@ function validateSteps(steps) {
         });
       }
     }
+    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;