browser-pilot 0.0.16 → 0.0.17

package/dist/{chunk-6GBYX7C2.mjs → chunk-MRY3HRFJ.mjs}

@@ -3,6 +3,275 @@ import {
   stringifyUnknown
 } from "./chunk-DTVRFXKI.mjs";
 
+// 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
 import * as fs from "fs";
 import { join } from "path";
@@ -1469,282 +1738,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}$`);
-}
-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"]) ?? "";
-}
-var LiveTraceCollector = class {
-  cdp;
-  options;
-  handlers = [];
-  wsUrls = /* @__PURE__ */ new Map();
-  httpUrls = /* @__PURE__ */ new Map();
-  events = [];
-  startTime = Date.now();
-  matchRegex;
-  constructor(cdp, options = {}) {
-    this.cdp = cdp;
-    this.options = options;
-    this.matchRegex = options.match ? globToRegex(options.match) : null;
-  }
-  async start() {
-    await this.cdp.send("Runtime.enable");
-    await this.cdp.send("Page.enable");
-    await this.cdp.send("Network.enable");
-    await this.cdp.send("Runtime.addBinding", { name: TRACE_BINDING_NAME });
-    await this.cdp.send("Page.addScriptToEvaluateOnNewDocument", { source: TRACE_SCRIPT });
-    await this.cdp.send("Runtime.evaluate", { expression: TRACE_SCRIPT, awaitPromise: false });
-    if ((this.options.mode ?? "all") !== "http") {
-      this.subscribe("Network.webSocketCreated", (params) => {
-        const requestId = readStringOr(params["requestId"]);
-        const url = readStringOr(params["url"]);
-        if (!this.matchesUrl(url)) {
-          return;
-        }
-        this.wsUrls.set(requestId, url);
-        void this.emit({
-          channel: "ws",
-          event: "ws.connection.created",
-          summary: `WebSocket opened ${url}`,
-          connectionId: requestId,
-          requestId,
-          url,
-          data: { url }
-        });
-      });
-      this.subscribe("Network.webSocketFrameSent", (params) => {
-        const requestId = readStringOr(params["requestId"]);
-        const response = params["response"];
-        const payload = this.formatPayload(response?.payloadData, response?.opcode ?? 1);
-        const url = this.wsUrls.get(requestId);
-        if (this.matchRegex && !this.matchRegex.test(url ?? "") && !this.matchRegex.test(payload)) {
-          return;
-        }
-        void this.emit({
-          channel: "ws",
-          event: "ws.frame.sent",
-          summary: `WebSocket frame sent ${requestId}`,
-          connectionId: requestId,
-          requestId,
-          url,
-          data: {
-            opcode: response?.opcode ?? 1,
-            payload,
-            length: response?.payloadData?.length ?? 0
-          }
-        });
-      });
-      this.subscribe("Network.webSocketFrameReceived", (params) => {
-        const requestId = readStringOr(params["requestId"]);
-        const response = params["response"];
-        const payload = this.formatPayload(response?.payloadData, response?.opcode ?? 1);
-        const url = this.wsUrls.get(requestId);
-        if (this.matchRegex && !this.matchRegex.test(url ?? "") && !this.matchRegex.test(payload)) {
-          return;
-        }
-        void this.emit({
-          channel: "ws",
-          event: "ws.frame.received",
-          summary: `WebSocket frame received ${requestId}`,
-          connectionId: requestId,
-          requestId,
-          url,
-          data: {
-            opcode: response?.opcode ?? 1,
-            payload,
-            length: response?.payloadData?.length ?? 0
-          }
-        });
-      });
-      this.subscribe("Network.webSocketClosed", (params) => {
-        const requestId = readStringOr(params["requestId"]);
-        const url = this.wsUrls.get(requestId);
-        this.wsUrls.delete(requestId);
-        void this.emit({
-          channel: "ws",
-          event: "ws.connection.closed",
-          summary: `WebSocket closed ${requestId}`,
-          severity: "warn",
-          connectionId: requestId,
-          requestId,
-          url,
-          data: { url }
-        });
-      });
-    }
-    if ((this.options.mode ?? "all") !== "ws") {
-      this.subscribe("Network.requestWillBeSent", (params) => {
-        const request = params["request"];
-        const requestId = readStringOr(params["requestId"]);
-        const url = request?.url ?? "";
-        if (!this.matchesUrl(url)) {
-          return;
-        }
-        this.httpUrls.set(requestId, url);
-        void this.emit({
-          channel: "http",
-          event: "http.request.sent",
-          summary: `${request?.method ?? "GET"} ${url}`,
-          requestId,
-          url,
-          data: {
-            method: request?.method ?? "GET",
-            headers: request?.headers ?? {},
-            body: request?.postData ?? null
-          }
-        });
-      });
-      this.subscribe("Network.responseReceived", (params) => {
-        const requestId = readStringOr(params["requestId"]);
-        if (!this.httpUrls.has(requestId)) {
-          return;
-        }
-        const response = params["response"];
-        void this.emit({
-          channel: "http",
-          event: "http.response.received",
-          summary: `${response?.status ?? 0} ${response?.url ?? this.httpUrls.get(requestId) ?? ""}`,
-          requestId,
-          url: response?.url ?? this.httpUrls.get(requestId),
-          data: {
-            status: response?.status ?? 0,
-            headers: response?.headers ?? {},
-            mimeType: response?.mimeType ?? null
-          }
-        });
-      });
-      this.subscribe("Network.loadingFailed", (params) => {
-        const requestId = readStringOr(params["requestId"]);
-        const url = readString(params["blockedReason"]) ?? this.httpUrls.get(requestId) ?? "";
-        void this.emit({
-          channel: "http",
-          event: "http.response.failed",
-          summary: `HTTP request failed ${requestId}`,
-          severity: "error",
-          requestId,
-          url,
-          data: {
-            errorText: params["errorText"] ?? null,
-            blockedReason: params["blockedReason"] ?? null,
-            canceled: params["canceled"] ?? false
-          }
-        });
-      });
-    }
-    this.subscribe("Runtime.consoleAPICalled", (params) => {
-      const type = readStringOr(params["type"], "log");
-      if (type !== "log" && type !== "warn" && type !== "error") {
-        return;
-      }
-      const args = Array.isArray(params["args"]) ? params["args"] : [];
-      const text = args.map(formatConsoleArg).filter(Boolean).join(" ");
-      void this.emit({
-        channel: "console",
-        event: `console.${type}`,
-        severity: type === "error" ? "error" : type === "warn" ? "warn" : "info",
-        summary: text || `console.${type}`,
-        data: { args }
-      });
-    });
-    this.subscribe("Runtime.exceptionThrown", (params) => {
-      const details = params["exceptionDetails"] ?? {};
-      const text = readString(details["text"]) ?? "Runtime exception";
-      void this.emit({
-        channel: "runtime",
-        event: "runtime.exception",
-        severity: "error",
-        summary: text,
-        data: details
-      });
-    });
-    this.subscribe("Runtime.bindingCalled", (params) => {
-      if (params["name"] !== TRACE_BINDING_NAME) {
-        return;
-      }
-      const raw = readStringOr(params["payload"]);
-      try {
-        const payload = JSON.parse(raw);
-        const channel = this.channelForTraceEvent(payload.event);
-        void this.emit({
-          channel,
-          event: payload.event,
-          severity: payload.severity,
-          summary: payload.summary ?? payload.event,
-          ts: payload.ts ? new Date(payload.ts).toISOString() : void 0,
-          data: payload.data ?? {},
-          url: readString(payload.data?.["url"])
-        });
-      } catch {
-      }
-    });
-  }
-  async stop() {
-    for (const { event, handler } of this.handlers) {
-      this.cdp.off(event, handler);
-    }
-    this.handlers.length = 0;
-    return [...this.events];
-  }
-  getEvents() {
-    return [...this.events];
-  }
-  subscribe(event, handler) {
-    this.cdp.on(event, handler);
-    this.handlers.push({ event, handler });
-  }
-  matchesUrl(url) {
-    if (!this.matchRegex) {
-      return true;
-    }
-    return this.matchRegex.test(url);
-  }
-  formatPayload(payloadData, opcode) {
-    const data = payloadData ?? "";
-    const maxPayload = this.options.maxPayload ?? 256;
-    if (opcode === 2) {
-      const byteLength = Math.floor(data.length * 3 / 4);
-      return `[binary: ${byteLength} bytes]`;
-    }
-    if (data.length > maxPayload) {
-      return `${data.slice(0, maxPayload)}... [truncated, ${data.length} total]`;
-    }
-    return data;
-  }
-  channelForTraceEvent(eventName) {
-    if (eventName.startsWith("ws.")) return "ws";
-    if (eventName.startsWith("http.")) return "http";
-    if (eventName.startsWith("console.")) return "console";
-    if (eventName.startsWith("permission.")) return "permission";
-    if (eventName.startsWith("media.")) return "media";
-    if (eventName.startsWith("voice.")) return "voice";
-    if (eventName.startsWith("dom.")) return "dom";
-    if (eventName.startsWith("runtime.")) return "runtime";
-    return "session";
-  }
-  async emit(event) {
-    const normalized = normalizeTraceEvent({
-      traceId: event.traceId ?? createTraceId(event.channel),
-      sessionId: this.options.sessionId,
-      targetId: this.options.targetId,
-      elapsedMs: event.elapsedMs ?? Date.now() - this.startTime,
-      ...event
-    });
-    this.events.push(normalized);
-    await this.options.onEvent?.(normalized);
-  }
-};
-
 // src/actions/executor.ts
 var DEFAULT_TIMEOUT = 3e4;
 var DEFAULT_RECORDING_SKIP_ACTIONS = [
@@ -1754,15 +1747,6 @@ var DEFAULT_RECORDING_SKIP_ACTIONS = [
   "text",
   "screenshot"
 ];
-function readString2(value) {
-  return typeof value === "string" ? value : void 0;
-}
-function readStringOr2(value, fallback = "") {
-  return readString2(value) ?? fallback;
-}
-function formatConsoleArg2(entry) {
-  return readString2(entry["value"]) ?? readString2(entry["description"]) ?? "";
-}
 function loadExistingRecording(manifestPath) {
   try {
     const raw = JSON.parse(fs.readFileSync(manifestPath, "utf-8"));
@@ -1876,6 +1860,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) {
@@ -1921,9 +1924,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();
@@ -1941,6 +1960,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);
           }
@@ -1950,13 +1991,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,
@@ -1966,6 +2008,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;
@@ -1973,59 +2027,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;
@@ -2336,6 +2394,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,
@@ -2486,6 +2552,35 @@ var BatchExecutor = class {
         const media = await this.assertMediaTrackLive(step.kind);
         return { value: media };
       }
+      case "chooseOption": {
+        const { chooseOption } = await import("./combobox-RAKBA2BW.mjs");
+        if (!step.value) throw new Error("chooseOption requires value");
+        const result = await chooseOption(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 } = await import("./upload-E6MCC2OF.mjs");
+        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 uploadFiles(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 = {
@@ -2587,10 +2682,10 @@ Valid actions: ${valid}`);
         clearTimeout(timer);
       };
       const onCreated = (params) => {
-        wsUrls.set(readStringOr2(params["requestId"]), readStringOr2(params["url"]));
+        wsUrls.set(readStringOr(params["requestId"]), readStringOr(params["url"]));
       };
       const onFrame = (params) => {
-        const requestId = readStringOr2(params["requestId"]);
+        const requestId = readStringOr(params["requestId"]);
         const response = params["response"] ?? {};
         const payload = response.payloadData ?? "";
         const url = wsUrls.get(requestId) ?? "";
@@ -2608,13 +2703,13 @@ Valid actions: ${valid}`);
           return;
         }
         try {
-          const parsed = JSON.parse(readStringOr2(params["payload"]));
+          const parsed = JSON.parse(readStringOr(params["payload"]));
           if (parsed.event !== "ws.frame.received") {
             return;
           }
           const data = parsed.data ?? {};
-          const payload = readStringOr2(data["payload"]);
-          const url = readStringOr2(data["url"]);
+          const payload = readStringOr(data["payload"]);
+          const url = readStringOr(data["url"]);
           if (!regex.test(url) && !regex.test(payload)) {
             return;
           }
@@ -2623,7 +2718,7 @@ Valid actions: ${valid}`);
           }
           cleanup();
           resolve({
-            requestId: readStringOr2(data["connectionId"]),
+            requestId: readStringOr(data["connectionId"]),
             url,
             payload
           });
@@ -2668,13 +2763,13 @@ Valid actions: ${valid}`);
         continue;
       }
       const record = entry;
-      const event = readStringOr2(record["event"]);
+      const event = readStringOr(record["event"]);
       if (event !== "ws.frame.received") {
         continue;
       }
       const data = record["data"] ?? {};
-      const payload = readStringOr2(data["payload"]);
-      const url = readStringOr2(data["url"]);
+      const payload = readStringOr(data["payload"]);
+      const url = readStringOr(data["url"]);
       if (!regex.test(url) && !regex.test(payload)) {
         continue;
       }
@@ -2682,7 +2777,7 @@ Valid actions: ${valid}`);
         continue;
       }
       return {
-        requestId: readStringOr2(data["connectionId"]),
+        requestId: readStringOr(data["connectionId"]),
         url,
         payload
       };
@@ -2703,11 +2798,11 @@ Valid actions: ${valid}`);
           return;
         }
         const args = Array.isArray(params["args"]) ? params["args"] : [];
-        errors.push(args.map(formatConsoleArg2).filter(Boolean).join(" "));
+        errors.push(args.map(formatConsoleArg).filter(Boolean).join(" "));
       };
       const onException = (params) => {
         const details = params["exceptionDetails"] ?? {};
-        errors.push(readString2(details["text"]) ?? "Runtime exception");
+        errors.push(readString(details["text"]) ?? "Runtime exception");
       };
       const timer = setTimeout(() => {
         cleanup();
@@ -3079,6 +3174,30 @@ var ACTION_RULES = {
       kind: { type: "string", enum: ["audio", "video"] }
     },
     optional: {}
+  },
+  delta: {
+    required: {},
+    optional: {}
+  },
+  review: {
+    required: {},
+    optional: {}
+  },
+  chooseOption: {
+    required: { value: { type: "string|string[]" } },
+    optional: {
+      trigger: { type: "string|string[]" },
+      selector: { type: "string|string[]" },
+      option: { type: "string|string[]" },
+      match: { type: "string", enum: ["exact", "contains", "startsWith"] }
+    }
+  },
+  upload: {
+    required: {
+      selector: { type: "string|string[]" },
+      files: { type: "string|string[]" }
+    },
+    optional: {}
   }
 };
 var VALID_ACTIONS = Object.keys(ACTION_RULES);
@@ -3118,7 +3237,12 @@ var KNOWN_STEP_FIELDS = /* @__PURE__ */ new Set([
   "name",
   "state",
   "kind",
-  "windowMs"
+  "windowMs",
+  "expectAny",
+  "expectAll",
+  "failIf",
+  "dangerous",
+  "files"
 ]);
 function resolveAction(name) {
   if (VALID_ACTIONS.includes(name)) {
@@ -3338,6 +3462,64 @@ function validateSteps(steps) {
         });
       }
     }
+    if ("dangerous" in obj && obj["dangerous"] !== void 0) {
+      if (typeof obj["dangerous"] !== "boolean") {
+        errors.push({
+          stepIndex: i,
+          field: "dangerous",
+          message: `"dangerous" expected boolean, got ${typeof obj["dangerous"]}.`
+        });
+      }
+    }
+    for (const condField of ["expectAny", "expectAll", "failIf"]) {
+      if (condField in obj && obj[condField] !== void 0) {
+        if (!Array.isArray(obj[condField])) {
+          errors.push({
+            stepIndex: i,
+            field: condField,
+            message: `"${condField}" expected array, got ${typeof obj[condField]}.`
+          });
+        } else {
+          const conditions = obj[condField];
+          for (let ci = 0; ci < conditions.length; ci++) {
+            const cond = conditions[ci];
+            if (!cond || typeof cond !== "object" || Array.isArray(cond)) {
+              errors.push({
+                stepIndex: i,
+                field: condField,
+                message: `"${condField}[${ci}]" must be a condition object.`
+              });
+              continue;
+            }
+            const condObj = cond;
+            if (!("kind" in condObj) || typeof condObj["kind"] !== "string") {
+              errors.push({
+                stepIndex: i,
+                field: condField,
+                message: `"${condField}[${ci}]" missing required "kind" field.`
+              });
+            } else {
+              const validKinds = [
+                "urlMatches",
+                "elementVisible",
+                "elementHidden",
+                "textAppears",
+                "textChanges",
+                "networkResponse",
+                "stateSignatureChanges"
+              ];
+              if (!validKinds.includes(condObj["kind"])) {
+                errors.push({
+                  stepIndex: i,
+                  field: condField,
+                  message: `"${condField}[${ci}].kind" must be one of: ${validKinds.join(", ")}. Got "${condObj["kind"]}".`
+                });
+              }
+            }
+          }
+        }
+      }
+    }
     if (action === "assertText") {
       if (!("expect" in obj) && !("value" in obj)) {
         errors.push({
@@ -5398,6 +5580,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)
@@ -5557,8 +5847,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', {
@@ -7344,7 +7744,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,
@@ -7400,7 +7802,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({
@@ -7467,6 +7871,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
@@ -8645,6 +9088,10 @@ function sleep4(ms) {
 
 export {
   pcmToWav,
+  readString,
+  readStringOr,
+  formatConsoleArg,
+  globToRegex,
   SENSITIVE_AUTOCOMPLETE_TOKENS,
   redactValueForRecording,
   fuzzyMatchElements,
@@ -8656,7 +9103,6 @@ export {
   normalizeTraceEvent,
   TRACE_BINDING_NAME,
   TRACE_SCRIPT,
-  LiveTraceCollector,
   addBatchToPage,
   validateSteps,
   grantAudioPermissions,