browser-pilot 0.0.16 → 0.0.17

package/dist/browser.cjs

@@ -5,6 +5,9 @@ var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, { get: all[name], enumerable: true });
@@ -27,6 +30,206 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
+// src/browser/combobox.ts
+var combobox_exports = {};
+__export(combobox_exports, {
+  chooseOption: () => chooseOption
+});
+async function chooseOption(page, config) {
+  const {
+    trigger,
+    listbox,
+    optionSelector,
+    searchText,
+    value,
+    match = "contains",
+    timeout = 1e4
+  } = config;
+  try {
+    await page.click(trigger, { timeout });
+    const listboxSelectors = listbox ? Array.isArray(listbox) ? listbox : [listbox] : DEFAULT_LISTBOX_SELECTORS;
+    const listboxFound = await page.waitFor(listboxSelectors, {
+      timeout: Math.min(timeout, 3e3),
+      optional: true,
+      state: "visible"
+    });
+    if (!listboxFound) {
+      return {
+        success: false,
+        failedAt: "open",
+        error: "Listbox did not appear after clicking trigger"
+      };
+    }
+    if (searchText) {
+      try {
+        const triggerSel = Array.isArray(trigger) ? trigger[0] : trigger;
+        await page.type(triggerSel, searchText, {
+          delay: 30,
+          timeout: Math.min(timeout, 3e3)
+        });
+        await new Promise((resolve) => setTimeout(resolve, 200));
+      } catch {
+        return { success: false, failedAt: "search", error: "Failed to type search text" };
+      }
+    }
+    const optionSelectors = optionSelector ? [optionSelector] : DEFAULT_OPTION_SELECTORS;
+    const matchFn = match === "exact" ? "exact" : match === "startsWith" ? "startsWith" : "contains";
+    const clickedOption = await page.evaluate(`(() => {
+      const selectors = ${JSON.stringify(optionSelectors)};
+      const targetValue = ${JSON.stringify(value)};
+      const matchMode = ${JSON.stringify(matchFn)};
+
+      for (const sel of selectors) {
+        const options = document.querySelectorAll(sel);
+        for (const opt of options) {
+          const text = (opt.textContent || '').trim();
+          let matches = false;
+          if (matchMode === 'exact') matches = text === targetValue;
+          else if (matchMode === 'startsWith') matches = text.startsWith(targetValue);
+          else matches = text.includes(targetValue);
+
+          if (matches) {
+            opt.click();
+            return text;
+          }
+        }
+      }
+      return null;
+    })()`);
+    if (!clickedOption) {
+      return { success: false, failedAt: "select", error: `No option matching "${value}" found` };
+    }
+    return {
+      success: true,
+      selectedText: String(clickedOption)
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : String(error)
+    };
+  }
+}
+var DEFAULT_LISTBOX_SELECTORS, DEFAULT_OPTION_SELECTORS;
+var init_combobox = __esm({
+  "src/browser/combobox.ts"() {
+    "use strict";
+    DEFAULT_LISTBOX_SELECTORS = [
+      '[role="listbox"]',
+      '[role="menu"]',
+      '[role="tree"]',
+      'ul[class*="dropdown"]',
+      'ul[class*="option"]',
+      'ul[class*="list"]',
+      'div[class*="dropdown"]',
+      'div[class*="menu"]'
+    ];
+    DEFAULT_OPTION_SELECTORS = [
+      '[role="option"]',
+      '[role="menuitem"]',
+      '[role="treeitem"]',
+      "li"
+    ];
+  }
+});
+
+// src/browser/upload.ts
+var upload_exports = {};
+__export(upload_exports, {
+  uploadFiles: () => uploadFiles
+});
+async function uploadFiles(page, config) {
+  const { selector, files, timeout = 1e4 } = config;
+  const fileNames = files.map((f) => f.split("/").pop() ?? f);
+  try {
+    const selectors = Array.isArray(selector) ? selector : [selector];
+    let nodeId;
+    for (const sel of selectors) {
+      try {
+        const found = await page.waitFor(sel, {
+          timeout: Math.min(timeout, 5e3),
+          optional: true,
+          state: "attached"
+        });
+        if (found) {
+          const result = await page.evaluate(`(() => {
+            const el = document.querySelector(${JSON.stringify(sel)});
+            if (!el) return null;
+            return el.tagName.toLowerCase() === 'input' && el.type === 'file' ? 'file-input' : 'not-file-input';
+          })()`);
+          if (result === "file-input") {
+            const doc = await page.cdpClient.send("DOM.getDocument");
+            const queryResult = await page.cdpClient.send("DOM.querySelector", {
+              nodeId: doc.root.nodeId,
+              selector: sel
+            });
+            nodeId = queryResult.nodeId;
+            break;
+          }
+        }
+      } catch {
+      }
+    }
+    if (!nodeId) {
+      return {
+        accepted: false,
+        fileCount: 0,
+        fileNames,
+        error: "No file input element found"
+      };
+    }
+    await page.cdpClient.send("DOM.setFileInputFiles", {
+      files,
+      nodeId
+    });
+    await new Promise((resolve) => setTimeout(resolve, 300));
+    let validationError;
+    try {
+      const errorText = await page.evaluate(`(() => {
+        const errorSelectors = ['.error', '.validation-error', '[class*="error"]', '[role="alert"]'];
+        for (const sel of errorSelectors) {
+          const el = document.querySelector(sel);
+          if (el && el.offsetParent !== null && el.textContent.trim()) {
+            return el.textContent.trim();
+          }
+        }
+        return null;
+      })()`);
+      if (errorText) validationError = String(errorText);
+    } catch {
+    }
+    let visibleInUI;
+    try {
+      const visible = await page.evaluate(`(() => {
+        const text = document.body.innerText;
+        const fileNames = ${JSON.stringify(fileNames)};
+        return fileNames.some(name => text.includes(name));
+      })()`);
+      visibleInUI = visible === true;
+    } catch {
+    }
+    return {
+      accepted: true,
+      fileCount: files.length,
+      fileNames,
+      visibleInUI,
+      validationError
+    };
+  } catch (error) {
+    return {
+      accepted: false,
+      fileCount: 0,
+      fileNames,
+      error: error instanceof Error ? error.message : String(error)
+    };
+  }
+}
+var init_upload = __esm({
+  "src/browser/upload.ts"() {
+    "use strict";
+  }
+});
+
 // src/browser/index.ts
 var browser_exports = {};
 __export(browser_exports, {
@@ -35,7 +238,21 @@ __export(browser_exports, {
   NavigationError: () => NavigationError,
   Page: () => Page,
   TimeoutError: () => TimeoutError,
-  connect: () => connect
+  buildFingerprintMap: () => buildFingerprintMap,
+  chooseOption: () => chooseOption,
+  computeDelta: () => computeDelta,
+  connect: () => connect,
+  createFingerprint: () => createFingerprint,
+  createTargetFingerprint: () => createTargetFingerprint,
+  detectOverlay: () => detectOverlay,
+  extractPageState: () => extractPageState,
+  extractReview: () => extractReview,
+  fingerprintKey: () => fingerprintKey,
+  fingerprintSimilarity: () => fingerprintSimilarity,
+  recoverPinnedTarget: () => recoverPinnedTarget,
+  recoverStaleRef: () => recoverStaleRef,
+  submitAndVerify: () => submitAndVerify,
+  uploadFiles: () => uploadFiles
 });
 module.exports = __toCommonJS(browser_exports);
 
@@ -883,6 +1100,275 @@ function createProvider(options) {
   }
 }
 
+// src/utils/strings.ts
+function readString(value) {
+  return typeof value === "string" ? value : void 0;
+}
+function readStringOr(value, fallback = "") {
+  return readString(value) ?? fallback;
+}
+function formatConsoleArg(entry) {
+  return readString(entry["value"]) ?? readString(entry["description"]) ?? "";
+}
+function globToRegex(pattern) {
+  const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+  const withWildcards = escaped.replace(/\*/g, ".*");
+  return new RegExp(`^${withWildcards}$`);
+}
+
+// src/actions/conditions.ts
+var NetworkResponseTracker = class {
+  responses = [];
+  listening = false;
+  handler = null;
+  start(cdp) {
+    if (this.listening) return;
+    this.listening = true;
+    this.handler = (params) => {
+      const response = params["response"];
+      if (response) {
+        this.responses.push({ url: response.url, status: response.status });
+      }
+    };
+    cdp.on("Network.responseReceived", this.handler);
+  }
+  stop(cdp) {
+    if (this.handler) {
+      cdp.off("Network.responseReceived", this.handler);
+      this.handler = null;
+    }
+    this.listening = false;
+  }
+  getResponses() {
+    return this.responses;
+  }
+  reset() {
+    this.responses = [];
+  }
+};
+async function captureStateSignature(page) {
+  try {
+    const url = await page.url();
+    const text = await page.text();
+    const truncated = text.slice(0, 2e3);
+    return `${url}|${simpleHash(truncated)}`;
+  } catch {
+    return "";
+  }
+}
+function simpleHash(str) {
+  let hash = 0;
+  for (let i = 0; i < str.length; i++) {
+    const char = str.charCodeAt(i);
+    hash = (hash << 5) - hash + char | 0;
+  }
+  return hash.toString(36);
+}
+async function evaluateCondition(condition, page, context = {}) {
+  switch (condition.kind) {
+    case "urlMatches": {
+      try {
+        const currentUrl = await page.url();
+        const regex = globToRegex(condition.pattern);
+        const matched = regex.test(currentUrl);
+        return {
+          condition,
+          matched,
+          detail: matched ? `URL "${currentUrl}" matches "${condition.pattern}"` : `URL "${currentUrl}" does not match "${condition.pattern}"`
+        };
+      } catch {
+        return { condition, matched: false, detail: "Failed to get current URL" };
+      }
+    }
+    case "elementVisible": {
+      try {
+        const selectors = Array.isArray(condition.selector) ? condition.selector : [condition.selector];
+        for (const sel of selectors) {
+          const visible = await page.waitFor(sel, {
+            timeout: 2e3,
+            optional: true,
+            state: "visible"
+          });
+          if (visible) {
+            return { condition, matched: true, detail: `Element "${sel}" is visible` };
+          }
+        }
+        return { condition, matched: false, detail: "No matching visible element found" };
+      } catch {
+        return { condition, matched: false, detail: "Visibility check failed" };
+      }
+    }
+    case "elementHidden": {
+      try {
+        const selectors = Array.isArray(condition.selector) ? condition.selector : [condition.selector];
+        for (const sel of selectors) {
+          const visible = await page.waitFor(sel, {
+            timeout: 500,
+            optional: true,
+            state: "visible"
+          });
+          if (visible) {
+            return { condition, matched: false, detail: `Element "${sel}" is still visible` };
+          }
+        }
+        return { condition, matched: true, detail: "Element is hidden or not found" };
+      } catch {
+        return { condition, matched: true, detail: "Element is hidden (check threw)" };
+      }
+    }
+    case "textAppears": {
+      try {
+        const selector = Array.isArray(condition.selector) ? condition.selector[0] : condition.selector;
+        const text = await page.text(selector);
+        const matched = text.includes(condition.text);
+        return {
+          condition,
+          matched,
+          detail: matched ? `Text "${condition.text}" found` : `Text "${condition.text}" not found in page content`
+        };
+      } catch {
+        return { condition, matched: false, detail: "Failed to get page text" };
+      }
+    }
+    case "textChanges": {
+      try {
+        const selector = Array.isArray(condition.selector) ? condition.selector[0] : condition.selector;
+        const text = await page.text(selector);
+        if (condition.to !== void 0) {
+          const matched = text.includes(condition.to);
+          return {
+            condition,
+            matched,
+            detail: matched ? `Text changed to include "${condition.to}"` : `Text does not include "${condition.to}"`
+          };
+        }
+        return { condition, matched: true, detail: "textChanges without `to` defaults to true" };
+      } catch {
+        return { condition, matched: false, detail: "Failed to get text for change detection" };
+      }
+    }
+    case "networkResponse": {
+      const tracker = context.networkTracker;
+      if (!tracker) {
+        return { condition, matched: false, detail: "No network tracker active" };
+      }
+      const regex = globToRegex(condition.urlPattern);
+      const responses = tracker.getResponses();
+      for (const resp of responses) {
+        if (regex.test(resp.url)) {
+          if (condition.status !== void 0 && resp.status !== condition.status) {
+            continue;
+          }
+          return {
+            condition,
+            matched: true,
+            detail: `Network response ${resp.url} (${resp.status}) matches pattern "${condition.urlPattern}"`
+          };
+        }
+      }
+      return {
+        condition,
+        matched: false,
+        detail: `No network response matching "${condition.urlPattern}" (saw ${responses.length} responses)`
+      };
+    }
+    case "stateSignatureChanges": {
+      if (!context.beforeSignature) {
+        return { condition, matched: false, detail: "No before-signature captured" };
+      }
+      const afterSignature = await captureStateSignature(page);
+      const matched = afterSignature !== context.beforeSignature;
+      return {
+        condition,
+        matched,
+        detail: matched ? "Page state changed" : "Page state unchanged"
+      };
+    }
+    default: {
+      const _exhaustive = condition;
+      return { condition: _exhaustive, matched: false, detail: "Unknown condition kind" };
+    }
+  }
+}
+async function evaluateOutcome(page, options) {
+  const {
+    expectAny,
+    expectAll,
+    failIf,
+    dangerous = false,
+    networkTracker,
+    beforeSignature
+  } = options;
+  const allMatched = [];
+  const context = { networkTracker, beforeSignature };
+  if (failIf && failIf.length > 0) {
+    for (const condition of failIf) {
+      const result = await evaluateCondition(condition, page, context);
+      allMatched.push(result);
+      if (result.matched) {
+        return {
+          outcomeStatus: "failed",
+          matchedConditions: allMatched,
+          retrySafe: !dangerous
+        };
+      }
+    }
+  }
+  if (expectAll && expectAll.length > 0) {
+    let allPassed = true;
+    for (const condition of expectAll) {
+      const result = await evaluateCondition(condition, page, context);
+      allMatched.push(result);
+      if (!result.matched) {
+        allPassed = false;
+      }
+    }
+    if (!allPassed) {
+      const status = dangerous ? "unsafe_to_retry" : "ambiguous";
+      return {
+        outcomeStatus: status,
+        matchedConditions: allMatched,
+        retrySafe: !dangerous
+      };
+    }
+    if (!expectAny || expectAny.length === 0) {
+      return {
+        outcomeStatus: "success",
+        matchedConditions: allMatched,
+        retrySafe: true
+      };
+    }
+  }
+  if (expectAny && expectAny.length > 0) {
+    let anyPassed = false;
+    for (const condition of expectAny) {
+      const result = await evaluateCondition(condition, page, context);
+      allMatched.push(result);
+      if (result.matched) {
+        anyPassed = true;
+      }
+    }
+    if (anyPassed) {
+      return {
+        outcomeStatus: "success",
+        matchedConditions: allMatched,
+        retrySafe: true
+      };
+    }
+    const status = dangerous ? "unsafe_to_retry" : "ambiguous";
+    return {
+      outcomeStatus: status,
+      matchedConditions: allMatched,
+      retrySafe: !dangerous
+    };
+  }
+  return {
+    outcomeStatus: "success",
+    matchedConditions: allMatched,
+    retrySafe: true
+  };
+}
+
 // src/actions/executor.ts
 var fs = __toESM(require("fs"), 1);
 var import_node_path = require("path");
@@ -2330,13 +2816,6 @@ var TRACE_SCRIPT = `
 })();
 `;
 
-// src/trace/live.ts
-function globToRegex(pattern) {
-  const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&");
-  const withWildcards = escaped.replace(/\*/g, ".*");
-  return new RegExp(`^${withWildcards}$`);
-}
-
 // src/actions/executor.ts
 var DEFAULT_TIMEOUT = 3e4;
 var DEFAULT_RECORDING_SKIP_ACTIONS = [
@@ -2346,15 +2825,6 @@ var DEFAULT_RECORDING_SKIP_ACTIONS = [
   "text",
   "screenshot"
 ];
-function readString(value) {
-  return typeof value === "string" ? value : void 0;
-}
-function readStringOr(value, fallback = "") {
-  return readString(value) ?? fallback;
-}
-function formatConsoleArg(entry) {
-  return readString(entry["value"]) ?? readString(entry["description"]) ?? "";
-}
 function loadExistingRecording(manifestPath) {
   try {
     const raw = JSON.parse(fs.readFileSync(manifestPath, "utf-8"));
@@ -2468,6 +2938,25 @@ function getSuggestion(reason) {
     }
   }
 }
+function hasOutcomeConditions(step) {
+  return step.expectAny !== void 0 && step.expectAny.length > 0 || step.expectAll !== void 0 && step.expectAll.length > 0 || step.failIf !== void 0 && step.failIf.length > 0;
+}
+function needsNetworkTracking(step) {
+  const allConditions = [
+    ...step.expectAny ?? [],
+    ...step.expectAll ?? [],
+    ...step.failIf ?? []
+  ];
+  return allConditions.some((c) => c.kind === "networkResponse");
+}
+function needsStateSignature(step) {
+  const allConditions = [
+    ...step.expectAny ?? [],
+    ...step.expectAll ?? [],
+    ...step.failIf ?? []
+  ];
+  return allConditions.some((c) => c.kind === "stateSignatureChanges");
+}
 var BatchExecutor = class {
   page;
   constructor(page) {
@@ -2513,9 +3002,25 @@ var BatchExecutor = class {
           })
         );
       }
+      const hasOutcome = hasOutcomeConditions(step);
+      let networkTracker;
+      let beforeSignature;
+      if (hasOutcome) {
+        if (needsNetworkTracking(step)) {
+          networkTracker = new NetworkResponseTracker();
+          networkTracker.start(this.page.cdpClient);
+        }
+        if (needsStateSignature(step)) {
+          beforeSignature = await captureStateSignature(this.page);
+        }
+      }
       for (let attempt = 0; attempt < maxAttempts; attempt++) {
         if (attempt > 0) {
           await new Promise((resolve) => setTimeout(resolve, retryDelay));
+          if (networkTracker) networkTracker.reset();
+          if (hasOutcome && needsStateSignature(step)) {
+            beforeSignature = await captureStateSignature(this.page);
+          }
         }
         try {
           this.page.resetLastActionPosition();
@@ -2533,6 +3038,28 @@ var BatchExecutor = class {
             coordinates: this.page.getLastActionCoordinates() ?? void 0,
             boundingBox: this.page.getLastActionBoundingBox() ?? void 0
           };
+          if (hasOutcome) {
+            if (networkTracker) networkTracker.stop(this.page.cdpClient);
+            const outcome = await evaluateOutcome(this.page, {
+              expectAny: step.expectAny,
+              expectAll: step.expectAll,
+              failIf: step.failIf,
+              dangerous: step.dangerous,
+              networkTracker,
+              beforeSignature
+            });
+            stepResult.outcomeStatus = outcome.outcomeStatus;
+            stepResult.matchedConditions = outcome.matchedConditions;
+            stepResult.retrySafe = outcome.retrySafe;
+            if (outcome.outcomeStatus !== "success") {
+              stepResult.success = false;
+              stepResult.error = `Outcome: ${outcome.outcomeStatus}`;
+              const failedDetails = outcome.matchedConditions.filter((mc) => outcome.outcomeStatus === "failed" ? mc.matched : !mc.matched).map((mc) => mc.detail).filter(Boolean);
+              if (failedDetails.length > 0) {
+                stepResult.suggestion = failedDetails.join("; ");
+              }
+            }
+          }
           if (recording && !recording.skipActions.has(step.action)) {
             await this.captureRecordingFrame(step, stepResult, recording);
           }
@@ -2542,13 +3069,14 @@ var BatchExecutor = class {
                 traceId: createTraceId("action"),
                 elapsedMs: Date.now() - startTime,
                 channel: "action",
-                event: "action.succeeded",
-                summary: `${step.action} succeeded`,
+                event: stepResult.success ? "action.succeeded" : "action.outcome_failed",
+                summary: stepResult.success ? `${step.action} succeeded` : `${step.action} outcome: ${stepResult.outcomeStatus}`,
                 data: {
                   action: step.action,
                   selector: step.selector ?? null,
                   selectorUsed: result.selectorUsed ?? null,
-                  durationMs: Date.now() - stepStart
+                  durationMs: Date.now() - stepStart,
+                  outcomeStatus: stepResult.outcomeStatus ?? null
                 },
                 actionId: `action-${i + 1}`,
                 stepIndex: i,
@@ -2558,6 +3086,18 @@ var BatchExecutor = class {
               })
             );
           }
+          if (hasOutcome && !stepResult.success) {
+            if (step.dangerous) {
+              results.push(stepResult);
+              break;
+            }
+            if (attempt < maxAttempts - 1) {
+              lastError = new Error(stepResult.error ?? "Outcome failed");
+              continue;
+            }
+            results.push(stepResult);
+            break;
+          }
           results.push(stepResult);
           succeeded = true;
           break;
@@ -2565,59 +3105,63 @@ var BatchExecutor = class {
           lastError = error instanceof Error ? error : new Error(String(error));
         }
       }
+      if (networkTracker) networkTracker.stop(this.page.cdpClient);
       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;
+        const resultAlreadyPushed = results.length > 0 && results[results.length - 1].index === i;
+        if (!resultAlreadyPushed) {
+          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 {
             }
-          } catch {
           }
+          const failedResult = {
+            index: i,
+            action: step.action,
+            selector: step.selector,
+            success: false,
+            durationMs: Date.now() - stepStart,
+            error: errorMessage,
+            hints,
+            failureReason: reason,
+            coveringElement,
+            suggestion: getSuggestion(reason),
+            timestamp: Date.now()
+          };
+          if (recording && !recording.skipActions.has(step.action)) {
+            await this.captureRecordingFrame(step, failedResult, recording);
+          }
+          if (recording) {
+            recording.traceEvents.push(
+              normalizeTraceEvent({
+                traceId: createTraceId("action"),
+                elapsedMs: Date.now() - startTime,
+                channel: "action",
+                event: "action.failed",
+                severity: "error",
+                summary: `${step.action} failed: ${errorMessage}`,
+                data: {
+                  action: step.action,
+                  selector: step.selector ?? null,
+                  error: errorMessage,
+                  reason
+                },
+                actionId: `action-${i + 1}`,
+                stepIndex: i,
+                selector: step.selector,
+                url: step.url
+              })
+            );
+          }
+          results.push(failedResult);
         }
-        const failedResult = {
-          index: i,
-          action: step.action,
-          selector: step.selector,
-          success: false,
-          durationMs: Date.now() - stepStart,
-          error: errorMessage,
-          hints,
-          failureReason: reason,
-          coveringElement,
-          suggestion: getSuggestion(reason),
-          timestamp: Date.now()
-        };
-        if (recording && !recording.skipActions.has(step.action)) {
-          await this.captureRecordingFrame(step, failedResult, recording);
-        }
-        if (recording) {
-          recording.traceEvents.push(
-            normalizeTraceEvent({
-              traceId: createTraceId("action"),
-              elapsedMs: Date.now() - startTime,
-              channel: "action",
-              event: "action.failed",
-              severity: "error",
-              summary: `${step.action} failed: ${errorMessage}`,
-              data: {
-                action: step.action,
-                selector: step.selector ?? null,
-                error: errorMessage,
-                reason
-              },
-              actionId: `action-${i + 1}`,
-              stepIndex: i,
-              selector: step.selector,
-              url: step.url
-            })
-          );
-        }
-        results.push(failedResult);
         if (onFail === "stop" && !step.optional) {
           stoppedAtIndex = i;
           break;
@@ -2928,6 +3472,14 @@ var BatchExecutor = class {
       case "forms": {
         return { value: await this.page.forms() };
       }
+      case "delta": {
+        const review = await this.page.review();
+        return { value: review };
+      }
+      case "review": {
+        const review = await this.page.review();
+        return { value: review };
+      }
       case "screenshot": {
         const data = await this.page.screenshot({
           format: step.format,
@@ -3078,6 +3630,35 @@ var BatchExecutor = class {
         const media = await this.assertMediaTrackLive(step.kind);
         return { value: media };
       }
+      case "chooseOption": {
+        const { chooseOption: chooseOption2 } = await Promise.resolve().then(() => (init_combobox(), combobox_exports));
+        if (!step.value) throw new Error("chooseOption requires value");
+        const result = await chooseOption2(this.page, {
+          trigger: step.trigger ?? step.selector ?? "",
+          listbox: step.option ? Array.isArray(step.option) ? step.option : [step.option] : void 0,
+          value: typeof step.value === "string" ? step.value : step.value[0] ?? "",
+          match: step.match,
+          timeout: step.timeout ?? timeout
+        });
+        if (!result.success) {
+          throw new Error(result.error ?? `chooseOption failed at ${result.failedAt}`);
+        }
+        return { value: result };
+      }
+      case "upload": {
+        const { uploadFiles: uploadFiles2 } = await Promise.resolve().then(() => (init_upload(), upload_exports));
+        if (!step.selector) throw new Error("upload requires selector");
+        if (!step.files || step.files.length === 0) throw new Error("upload requires files");
+        const result = await uploadFiles2(this.page, {
+          selector: step.selector,
+          files: step.files,
+          timeout: step.timeout ?? timeout
+        });
+        if (!result.accepted) {
+          throw new Error(result.error ?? "Upload was not accepted");
+        }
+        return { value: result };
+      }
       default: {
         const action = step.action;
         const aliases = {
@@ -5323,6 +5904,114 @@ async function waitForNetworkIdle(cdp, options = {}) {
   });
 }
 
+// src/browser/delta.ts
+function extractPageState(url, title, snapshot, forms, pageText) {
+  const headings = [];
+  const buttons = [];
+  const alerts = [];
+  function walkNodes(nodes) {
+    for (const node of nodes) {
+      const role = node.role?.toLowerCase() ?? "";
+      if (role === "heading" && node.name) {
+        headings.push(node.name);
+      }
+      if ((role === "button" || role === "link") && node.name) {
+        const disabled = node.disabled ?? false;
+        buttons.push({ text: node.name, disabled, ref: node.ref });
+      }
+      if (role === "alert" && node.name) {
+        alerts.push(node.name);
+      }
+      if (node.children) {
+        walkNodes(node.children);
+      }
+    }
+  }
+  walkNodes(snapshot.accessibilityTree);
+  const formFields = forms.map((f) => ({
+    label: f.label,
+    name: f.name,
+    id: f.id,
+    value: f.value,
+    type: f.type
+  }));
+  return {
+    url,
+    title,
+    headings,
+    formFields,
+    buttons,
+    alerts,
+    visibleText: pageText.slice(0, 3e3)
+  };
+}
+function computeDelta(before, after) {
+  const changes = [];
+  if (before.url !== after.url) {
+    changes.push({ kind: "url", before: before.url, after: after.url });
+  }
+  if (before.title !== after.title) {
+    changes.push({ kind: "title", before: before.title, after: after.title });
+  }
+  const beforeHeadings = new Set(before.headings);
+  const afterHeadings = new Set(after.headings);
+  for (const h of after.headings) {
+    if (!beforeHeadings.has(h)) {
+      changes.push({ kind: "heading_added", after: h });
+    }
+  }
+  for (const h of before.headings) {
+    if (!afterHeadings.has(h)) {
+      changes.push({ kind: "heading_removed", before: h });
+    }
+  }
+  const beforeFieldMap = new Map(
+    before.formFields.map((f) => [f.id ?? f.name ?? f.label ?? "", f])
+  );
+  for (const af of after.formFields) {
+    const key = af.id ?? af.name ?? af.label ?? "";
+    const bf = beforeFieldMap.get(key);
+    if (bf && JSON.stringify(bf.value) !== JSON.stringify(af.value)) {
+      changes.push({
+        kind: "field_changed",
+        before: String(bf.value ?? ""),
+        after: String(af.value ?? ""),
+        detail: af.label ?? af.name ?? af.id ?? key
+      });
+    }
+  }
+  const beforeBtnMap = new Map(before.buttons.map((b) => [b.text, b]));
+  for (const ab of after.buttons) {
+    const bb = beforeBtnMap.get(ab.text);
+    if (bb && bb.disabled !== ab.disabled) {
+      changes.push({
+        kind: "button_changed",
+        detail: ab.text,
+        before: bb.disabled ? "disabled" : "enabled",
+        after: ab.disabled ? "disabled" : "enabled"
+      });
+    }
+  }
+  const beforeAlerts = new Set(before.alerts);
+  const afterAlerts = new Set(after.alerts);
+  for (const a of after.alerts) {
+    if (!beforeAlerts.has(a)) {
+      changes.push({ kind: "alert_added", after: a });
+    }
+  }
+  for (const a of before.alerts) {
+    if (!afterAlerts.has(a)) {
+      changes.push({ kind: "alert_removed", before: a });
+    }
+  }
+  return {
+    changes,
+    before,
+    after,
+    hasChanges: changes.length > 0
+  };
+}
+
 // src/browser/keyboard.ts
 var US_KEYBOARD = {
   // Letters (lowercase)
@@ -5482,8 +6171,118 @@ function parseShortcut(combo) {
   return { modifiers, key };
 }
 
+// src/browser/review.ts
+function extractReview(url, title, snapshot, forms, pageText) {
+  const headings = [];
+  const alerts = [];
+  const statusLabels = [];
+  const keyValues = [];
+  const tables = [];
+  const summaryCards = [];
+  function walkNodes(nodes, parentHeading) {
+    let currentHeading = parentHeading;
+    for (const node of nodes) {
+      const role = node.role?.toLowerCase() ?? "";
+      if (role === "heading" && node.name) {
+        headings.push(node.name);
+        currentHeading = node.name;
+      }
+      if (role === "alert" && node.name) {
+        alerts.push(node.name);
+      }
+      if (role === "status" && node.name) {
+        statusLabels.push(node.name);
+      }
+      if (role === "table" || role === "grid") {
+        const table = extractTableFromNode(node);
+        if (table) tables.push(table);
+      }
+      if ((role === "definition" || role === "term") && node.name) {
+        if (role === "term") {
+          keyValues.push({ key: node.name, value: "" });
+        } else if (role === "definition" && keyValues.length > 0) {
+          const last = keyValues[keyValues.length - 1];
+          if (!last.value) last.value = node.name;
+        }
+      }
+      if (node.children) {
+        walkNodes(node.children, currentHeading);
+      }
+    }
+  }
+  walkNodes(snapshot.accessibilityTree);
+  const textKvPairs = extractKeyValueFromText(pageText);
+  keyValues.push(...textKvPairs);
+  const formEntries = forms.map((f) => ({
+    label: f.label,
+    value: f.value,
+    type: f.type,
+    disabled: f.disabled
+  }));
+  return {
+    url,
+    title,
+    headings,
+    forms: formEntries,
+    alerts,
+    summaryCards,
+    tables,
+    keyValues,
+    statusLabels
+  };
+}
+function extractTableFromNode(node) {
+  const headers = [];
+  const rows = [];
+  function findRows(n) {
+    const role = n.role?.toLowerCase() ?? "";
+    if (role === "columnheader" && n.name) {
+      headers.push(n.name);
+    }
+    if (role === "row") {
+      const cells = [];
+      if (n.children) {
+        for (const child of n.children) {
+          const childRole = child.role?.toLowerCase() ?? "";
+          if ((childRole === "cell" || childRole === "gridcell") && child.name) {
+            cells.push(child.name);
+          }
+        }
+      }
+      if (cells.length > 0) rows.push(cells);
+    }
+    if (n.children) {
+      for (const child of n.children) findRows(child);
+    }
+  }
+  findRows(node);
+  if (rows.length === 0) return null;
+  return { headers, rows };
+}
+function extractKeyValueFromText(text) {
+  const pairs = [];
+  const lines = text.split("\n").map((l) => l.trim()).filter(Boolean);
+  for (const line of lines) {
+    const match = line.match(/^([A-Z][A-Za-z0-9 ]{1,30})[:—]\s+(.+)$/);
+    if (match) {
+      pairs.push({ key: match[1].trim(), value: match[2].trim() });
+    }
+  }
+  return pairs.slice(0, 20);
+}
+
 // src/browser/page.ts
 var DEFAULT_TIMEOUT2 = 3e4;
+function normalizeAXCheckedValue(value) {
+  if (typeof value === "boolean") {
+    return value;
+  }
+  if (typeof value === "string") {
+    if (value === "true") return true;
+    if (value === "false") return false;
+  }
+  return void 0;
+}
 var EVENT_LISTENER_TRACKER_SCRIPT = `(() => {
   if (globalThis.__bpEventListenerTrackerInstalled) return;
   Object.defineProperty(globalThis, '__bpEventListenerTrackerInstalled', {
@@ -7269,7 +8068,9 @@ var Page = class {
         }
       }
       const disabled = node.properties?.find((p) => p.name === "disabled")?.value.value;
-      const checked = node.properties?.find((p) => p.name === "checked")?.value.value;
+      const checked = normalizeAXCheckedValue(
+        node.properties?.find((p) => p.name === "checked")?.value.value
+      );
       return {
         role,
         name,
@@ -7325,7 +8126,9 @@ var Page = class {
         const ref = nodeRefs.get(node.nodeId);
         const name = node.name?.value ?? "";
         const disabled = node.properties?.find((p) => p.name === "disabled")?.value.value;
-        const checked = node.properties?.find((p) => p.name === "checked")?.value.value;
+        const checked = normalizeAXCheckedValue(
+          node.properties?.find((p) => p.name === "checked")?.value.value
+        );
         const value = node.value?.value;
         const selector = node.backendDOMNodeId ? `[data-backend-node-id="${node.backendDOMNodeId}"]` : `[aria-label="${name}"]`;
         interactiveElements.push({
@@ -7392,6 +8195,45 @@ var Page = class {
       }
     }
   }
+  // ============ Delta & Review ============
+  /**
+   * Capture current page state for delta comparison.
+   * Call before an action, then call delta() again after and use computeDelta().
+   */
+  async captureState() {
+    const [url, title, snapshot, forms, text] = await Promise.all([
+      this.url(),
+      this.title(),
+      this.snapshot(),
+      this.forms(),
+      this.text()
+    ]);
+    return extractPageState(url, title, snapshot, forms, text);
+  }
+  /**
+   * Compute what changed between two page states.
+   * If no arguments: captures current state and returns it (for use as "before").
+   * If one argument (before state): captures current state and computes delta.
+   */
+  async delta(before) {
+    const currentState = await this.captureState();
+    if (!before) return currentState;
+    return computeDelta(before, currentState);
+  }
+  /**
+   * Extract structured review surface from the current page.
+   * Returns headings, form values, alerts, key-value pairs, tables, and status labels.
+   */
+  async review() {
+    const [url, title, snapshot, forms, text] = await Promise.all([
+      this.url(),
+      this.title(),
+      this.snapshot(),
+      this.forms(),
+      this.text()
+    ]);
+    return extractReview(url, title, snapshot, forms, text);
+  }
   // ============ Batch Execution ============
   /**
    * Execute a batch of steps
@@ -8816,6 +9658,316 @@ var Browser = class _Browser {
 function connect(options) {
   return Browser.connect(options);
 }
+
+// src/browser/index.ts
+init_combobox();
+
+// src/browser/fingerprint.ts
+function createFingerprint(node, context) {
+  const role = node.role?.toLowerCase() ?? "";
+  const name = node.name ?? "";
+  let valueShape = "";
+  if (node.value !== void 0) {
+    valueShape = typeof node.value === "string" ? "text" : typeof node.value === "number" ? "number" : typeof node.value === "boolean" ? "boolean" : "other";
+  }
+  const stableAttrs = {};
+  if (node.properties) {
+    for (const key of ["id", "name", "type", "aria-label"]) {
+      const val = node.properties[key];
+      if (val !== void 0 && val !== null) {
+        stableAttrs[key] = String(val);
+      }
+    }
+  }
+  return {
+    role,
+    name,
+    valueShape,
+    label: name,
+    // label is typically the accessible name
+    stableAttrs,
+    nearestHeading: context.nearestHeading,
+    siblingIndex: context.siblingIndex,
+    sectionPath: [...context.headingTrail]
+  };
+}
+function fingerprintKey(fp) {
+  const parts = [fp.role, fp.name, fp.sectionPath.join(">")];
+  if (fp.stableAttrs["id"]) parts.push(`id=${fp.stableAttrs["id"]}`);
+  if (fp.stableAttrs["name"]) parts.push(`name=${fp.stableAttrs["name"]}`);
+  return parts.join("|");
+}
+function fingerprintSimilarity(a, b) {
+  let score = 0;
+  let weight = 0;
+  weight += 3;
+  if (a.role === b.role) score += 3;
+  else return 0;
+  weight += 5;
+  if (a.name && b.name && a.name === b.name) score += 5;
+  else if (a.name && b.name && a.name.toLowerCase() === b.name.toLowerCase()) score += 4;
+  weight += 3;
+  const pathA = a.sectionPath.join(">");
+  const pathB = b.sectionPath.join(">");
+  if (pathA === pathB) score += 3;
+  else if (pathA && pathB && (pathA.includes(pathB) || pathB.includes(pathA))) score += 1;
+  const attrKeys = /* @__PURE__ */ new Set([...Object.keys(a.stableAttrs), ...Object.keys(b.stableAttrs)]);
+  for (const key of attrKeys) {
+    weight += 2;
+    if (a.stableAttrs[key] && b.stableAttrs[key] && a.stableAttrs[key] === b.stableAttrs[key]) {
+      score += 2;
+    }
+  }
+  weight += 1;
+  if (a.siblingIndex === b.siblingIndex) score += 1;
+  return score / weight;
+}
+var INTERACTIVE_ROLES = /* @__PURE__ */ new Set([
+  "button",
+  "link",
+  "textbox",
+  "checkbox",
+  "radio",
+  "combobox",
+  "listbox",
+  "menuitem",
+  "tab",
+  "switch",
+  "searchbox",
+  "spinbutton",
+  "slider"
+]);
+function buildFingerprintMap(nodes) {
+  const map = /* @__PURE__ */ new Map();
+  function walk(nodeList, headingTrail, nearestHeading) {
+    const roleCounts = /* @__PURE__ */ new Map();
+    for (const node of nodeList) {
+      const role = node.role?.toLowerCase() ?? "";
+      let currentHeadingTrail = headingTrail;
+      let currentNearestHeading = nearestHeading;
+      if (role === "heading" && node.name) {
+        currentHeadingTrail = [...headingTrail, node.name];
+        currentNearestHeading = node.name;
+      }
+      if (INTERACTIVE_ROLES.has(role) && node.ref) {
+        const siblingCount = roleCounts.get(role) ?? 0;
+        roleCounts.set(role, siblingCount + 1);
+        const fp = createFingerprint(node, {
+          headingTrail: currentHeadingTrail,
+          siblingIndex: siblingCount,
+          nearestHeading: currentNearestHeading
+        });
+        map.set(node.ref, fp);
+      }
+      if (node.children) {
+        walk(node.children, currentHeadingTrail, currentNearestHeading);
+      }
+    }
+  }
+  walk(nodes, [], "");
+  return map;
+}
+function recoverStaleRef(staleFingerprint, currentFingerprints, threshold = 0.7) {
+  let bestRef = null;
+  let bestScore = 0;
+  let secondBestScore = 0;
+  for (const [ref, fp] of currentFingerprints) {
+    const similarity = fingerprintSimilarity(staleFingerprint, fp);
+    if (similarity > bestScore) {
+      secondBestScore = bestScore;
+      bestScore = similarity;
+      bestRef = ref;
+    } else if (similarity > secondBestScore) {
+      secondBestScore = similarity;
+    }
+  }
+  if (!bestRef || bestScore < threshold) return null;
+  if (secondBestScore > 0 && bestScore - secondBestScore < 0.15) return null;
+  return { ref: bestRef, confidence: bestScore };
+}
+
+// src/browser/overlay-detect.ts
+async function detectOverlay(page) {
+  const result = await page.evaluate(`(() => {
+    // Check for role="dialog" or role="alertdialog"
+    const dialogs = document.querySelectorAll('[role="dialog"], [role="alertdialog"], dialog[open]');
+    for (const d of dialogs) {
+      if (d.offsetParent !== null || getComputedStyle(d).display !== 'none') {
+        return {
+          hasOverlay: true,
+          overlaySelector: d.id ? '#' + d.id : (d.getAttribute('role') ? '[role="' + d.getAttribute('role') + '"]' : 'dialog'),
+          overlayText: (d.textContent || '').trim().slice(0, 200),
+        };
+      }
+    }
+
+    // Check for fixed/absolute positioned elements with high z-index that look like modals
+    const allElements = document.querySelectorAll('*');
+    for (const el of allElements) {
+      const style = getComputedStyle(el);
+      if (
+        (style.position === 'fixed' || style.position === 'absolute') &&
+        parseInt(style.zIndex || '0', 10) > 999 &&
+        el.offsetWidth > 100 &&
+        el.offsetHeight > 100 &&
+        style.display !== 'none' &&
+        style.visibility !== 'hidden'
+      ) {
+        const text = (el.textContent || '').trim();
+        if (text.length > 10) {
+          return {
+            hasOverlay: true,
+            overlaySelector: el.id ? '#' + el.id : null,
+            overlayText: text.slice(0, 200),
+          };
+        }
+      }
+    }
+
+    return { hasOverlay: false };
+  })()`);
+  return result ?? { hasOverlay: false };
+}
+
+// src/browser/safe-submit.ts
+async function submitAndVerify(page, options) {
+  const {
+    selector,
+    method = "enter+click",
+    expectAny,
+    expectAll,
+    failIf,
+    dangerous = false,
+    timeout = 3e4,
+    waitForNavigation: waitForNavigation2 = "auto"
+  } = options;
+  const startTime = Date.now();
+  const allConditions = [...expectAny ?? [], ...expectAll ?? [], ...failIf ?? []];
+  const needsNetwork = allConditions.some((c) => c.kind === "networkResponse");
+  const needsSignature = allConditions.some((c) => c.kind === "stateSignatureChanges");
+  let networkTracker;
+  let beforeSignature;
+  if (needsNetwork) {
+    networkTracker = new NetworkResponseTracker();
+    networkTracker.start(page.cdpClient);
+  }
+  if (needsSignature) {
+    beforeSignature = await captureStateSignature(page);
+  }
+  try {
+    await page.submit(selector, {
+      timeout,
+      method,
+      waitForNavigation: waitForNavigation2
+    });
+    if (networkTracker) networkTracker.stop(page.cdpClient);
+    if (allConditions.length === 0) {
+      return {
+        submitted: true,
+        outcomeStatus: "success",
+        matchedConditions: [],
+        retrySafe: !dangerous,
+        durationMs: Date.now() - startTime
+      };
+    }
+    const outcome = await evaluateOutcome(page, {
+      expectAny,
+      expectAll,
+      failIf,
+      dangerous,
+      networkTracker,
+      beforeSignature
+    });
+    return {
+      submitted: true,
+      outcomeStatus: outcome.outcomeStatus,
+      matchedConditions: outcome.matchedConditions,
+      retrySafe: outcome.retrySafe,
+      durationMs: Date.now() - startTime
+    };
+  } catch (error) {
+    if (networkTracker) networkTracker.stop(page.cdpClient);
+    return {
+      submitted: false,
+      outcomeStatus: "failed",
+      matchedConditions: [],
+      retrySafe: !dangerous,
+      durationMs: Date.now() - startTime,
+      error: error instanceof Error ? error.message : String(error)
+    };
+  }
+}
+
+// src/runtime/clock.ts
+function now() {
+  return Date.now();
+}
+
+// src/browser/target-pin.ts
+function createTargetFingerprint(targetId, url, title) {
+  return {
+    url,
+    title,
+    originalTargetId: targetId,
+    pinnedAt: now()
+  };
+}
+function scoreCandidate(candidate, pin) {
+  if (candidate.targetId === pin.originalTargetId) return 1;
+  let score = 0;
+  if (candidate.url && pin.url) {
+    if (candidate.url === pin.url) {
+      score += 0.6;
+    } else {
+      try {
+        const candidateOrigin = new URL(candidate.url).origin;
+        const pinOrigin = new URL(pin.url).origin;
+        if (candidateOrigin === pinOrigin) score += 0.3;
+      } catch {
+      }
+    }
+  }
+  if (candidate.title && pin.title) {
+    if (candidate.title === pin.title) {
+      score += 0.3;
+    } else if (candidate.title.includes(pin.title) || pin.title.includes(candidate.title)) {
+      score += 0.15;
+    }
+  }
+  if (candidate.type !== "page") score *= 0.5;
+  return Math.min(score, 0.95);
+}
+function recoverPinnedTarget(pin, targets, threshold = 0.4) {
+  if (targets.length === 0) return null;
+  let bestTarget = null;
+  let bestScore = 0;
+  for (const target of targets) {
+    const score = scoreCandidate(target, pin);
+    if (score > bestScore) {
+      bestScore = score;
+      bestTarget = target;
+    }
+  }
+  if (!bestTarget || bestScore < threshold) return null;
+  let method;
+  if (bestTarget.targetId === pin.originalTargetId) {
+    method = "exact";
+  } else if (bestTarget.url === pin.url) {
+    method = "url_match";
+  } else if (bestTarget.title === pin.title) {
+    method = "title_match";
+  } else {
+    method = "best_guess";
+  }
+  return {
+    targetId: bestTarget.targetId,
+    method,
+    confidence: bestScore
+  };
+}
+
+// src/browser/index.ts
+init_upload();
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   Browser,
@@ -8823,5 +9975,19 @@ function connect(options) {
   NavigationError,
   Page,
   TimeoutError,
-  connect
+  buildFingerprintMap,
+  chooseOption,
+  computeDelta,
+  connect,
+  createFingerprint,
+  createTargetFingerprint,
+  detectOverlay,
+  extractPageState,
+  extractReview,
+  fingerprintKey,
+  fingerprintSimilarity,
+  recoverPinnedTarget,
+  recoverStaleRef,
+  submitAndVerify,
+  uploadFiles
 });