@diegosouzacdv/jev-browser-mcp 0.6.0 → 0.6.1

package/mcp_servers/jev-browser-npm/src/flow.mjs

@@ -1,4 +1,4 @@
-import { randomUUID } from "node:crypto";
+import { createHash, randomBytes, randomUUID } from "node:crypto";
 import { lstat, mkdir, readFile, realpath, rm, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { ACCESSIBILITY_STANDARDS, runAccessibilityAudit } from "./accessibility.mjs";
@@ -6,7 +6,8 @@ import { JevBrowserError } from "./config.mjs";
 import { buildChoicePayload, COMPLETE_ACTION_ID, parseDecision, requestJev } from "./jev-client.mjs";
 
 const PLAN_ID = /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,79}$/;
-const CLICK_ROLES = new Set(["button", "link", "tab", "menuitem"]);
+const CLICK_ROLES = new Set(["button", "link", "tab", "menuitem", "checkbox", "radio", "cell", "gridcell", "option"]);
+const CHECK_ROLES = new Set(["checkbox", "radio"]);
 const TEXT_ROLES = new Set(["textbox", "searchbox", "combobox"]);
 const HOVER_ROLES = new Set(["button", "link", "tab", "menuitem", "row", "gridcell", "cell", "region", "group"]);
 const DROPZONE_ROLES = new Set(["button", "region", "group"]);
@@ -16,7 +17,7 @@ const CONTAINER_ROLES = new Set([
   "region", "row", "rowgroup", "table", "tablist", "tabpanel", "tree", "treegrid", "treeitem",
 ]);
 const TARGET_SELECTION_ACTIONS = new Set([
-  "click", "type", "select_option", "hover", "press", "assert_text", "assert_value", "wait_for_value",
+  "click", "check", "uncheck", "type", "select_option", "hover", "press", "assert_text", "assert_value", "wait_for_value",
   "wait_for_enabled", "assert_enabled", "assert_visible", "assert_hidden", "upload_file", "extract",
 ]);
 const LOCATOR_FIELDS = ["label", "placeholder", "title", "text", "test_id", "selector"];
@@ -39,11 +40,66 @@ const MIME_TYPES = new Map([
 ]);
 const FLOW_OPTION_KEYS = new Set([
   "block_trackers", "capture_console_errors", "capture_network_error_bodies", "capture_network_errors",
-  "dry_run", "fast_path", "ready_network_idle", "ready_stable_ms", "ready_text", "ready_timeout_seconds",
+  "auto_angular_idle", "block_fonts", "busy_selectors", "confirmation_token", "dry_run", "fast_path", "local_only",
+  "login_text", "login_url_contains", "max_flow_steps", "ready_network_idle", "ready_stable_ms", "ready_text", "ready_timeout_seconds",
   "report_path",
-  "continue_from_current_page", "reuse_page", "screenshot_on_failure", "snapshot_include_hidden", "snapshot_scope", "stop_on_expected",
+  "continue_from_current_page", "reuse_page", "return_snapshot", "screenshot_on_failure", "snapshot_include_hidden", "snapshot_scope", "step_timeout_seconds", "stop_on_expected",
   "trace_on_failure",
 ]);
+const MUTATING_LABEL = /\b(?:save|submit|issue|emit|cancel|delete|remove|void|confirm|approve|pay|send|generate|create|update|finalize|yes|okay|salvar|gravar|emitir|cancelar|excluir|apagar|remover|estornar|confirmar|aprovar|pagar|enviar|gerar|criar|atualizar|finalizar|sim)\b/i;
+
+export function createMutationAuthorizationStore() {
+  const tokens = new Map();
+  const prune = () => {
+    const now = Date.now();
+    for (const [token, record] of tokens) if (record.expiresAt <= now) tokens.delete(token);
+    while (tokens.size > 1024) tokens.delete(tokens.keys().next().value);
+  };
+  return Object.freeze({
+    issue(record, ttlMs) {
+      prune();
+      const token = randomBytes(32).toString("base64url");
+      tokens.set(token, { ...record, expiresAt: Date.now() + ttlMs });
+      return token;
+    },
+    consume(token, fingerprint) {
+      prune();
+      const record = tokens.get(token);
+      if (!record) throw new JevBrowserError("confirmation_token is invalid, expired, or already used; run dry_run again");
+      tokens.delete(token);
+      if (record.fingerprint !== fingerprint) {
+        throw new JevBrowserError("confirmation_token does not match this flow; run dry_run again");
+      }
+      return record;
+    },
+  });
+}
+
+const defaultMutationAuthorizationStore = createMutationAuthorizationStore();
+
+function canonicalValue(value) {
+  if (Array.isArray(value)) return value.map(canonicalValue);
+  if (!isRecord(value)) return value;
+  return Object.fromEntries(Object.keys(value).sort().map((key) => [key, canonicalValue(value[key])]));
+}
+
+function flowFingerprint({ flow, initialUrl, expectedOutcome, candidatePlans, params, options }) {
+  const stableOptions = { ...options };
+  delete stableOptions.dry_run;
+  delete stableOptions.confirmation_token;
+  delete stableOptions.dryRun;
+  delete stableOptions.confirmationToken;
+  return createHash("sha256").update(JSON.stringify(canonicalValue({
+    flow, initialUrl, expectedOutcome, candidatePlans, params, options: stableOptions,
+  }))).digest("hex");
+}
+
+function looksMutating(rawStep) {
+  if (["confirm_dialog", "like_comment", "unlike_comment", "upload_file"].includes(rawStep.action)) return true;
+  if (rawStep.action !== "click") return false;
+  return [rawStep.name, rawStep.title, rawStep.text, rawStep.target_text, rawStep.label]
+    .some((value) => typeof value === "string" && MUTATING_LABEL.test(value));
+}
 
 function isRecord(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
@@ -109,13 +165,12 @@ function interpolateStep(value, variables) {
   return value;
 }
 
-export function validateCandidatePlans(candidatePlans, settings) {
+export function validateCandidatePlans(candidatePlans, settings, maxFlowSteps = settings.browser.maxFlowSteps) {
   if (!isRecord(candidatePlans)) throw new JevBrowserError("candidate_plans must be an object");
   if (Object.keys(candidatePlans).length > settings.jev.maxActionCount) {
     throw new JevBrowserError("candidate_plans exceeds the configured candidate limit");
   }
   const plans = {};
-  let totalSteps = 0;
   for (const [rawId, rawPlan] of Object.entries(candidatePlans)) {
     const id = rawId.trim();
     if (!PLAN_ID.test(id) || id === COMPLETE_ACTION_ID) throw new JevBrowserError("each plan needs a valid, non-reserved plan ID");
@@ -126,8 +181,7 @@ export function validateCandidatePlans(candidatePlans, settings) {
     if (!Array.isArray(rawPlan.steps) || rawPlan.steps.length === 0) {
       throw new JevBrowserError("each candidate plan needs at least one browser step");
     }
-    totalSteps += rawPlan.steps.length;
-    if (totalSteps > settings.browser.maxFlowSteps) throw new JevBrowserError("candidate plans exceed the configured total browser-step limit");
+    if (rawPlan.steps.length > maxFlowSteps) throw new JevBrowserError(`candidate plan ${id} exceeds the per-plan browser-step limit of ${maxFlowSteps}`);
 
     const steps = rawPlan.steps.map((unprocessedStep) => {
       const rawStep = normalizeStepAliases(unprocessedStep);
@@ -138,9 +192,12 @@ export function validateCandidatePlans(candidatePlans, settings) {
       const locatorFields = TARGET_LOCATOR_FIELDS.filter((field) => field !== "text"
         || !["type", "wait_for_text", "wait_for_condition", "upload_file"].includes(action));
       const schemas = {
-        click: { required: [], optional: [...semanticTarget, "expect_download", "timeout_seconds"] },
+        click: { required: [], optional: [...semanticTarget, "expect_download", "expect_popup", "timeout_seconds"] },
         type: { required: ["text"], optional: [...semanticTarget, "blur", "mode", "sensitive", "timeout_seconds"] },
         confirm_dialog: { required: ["expected_text", "button"], optional: ["timeout_seconds"] },
+        check: { required: [], optional: [...semanticTarget, "timeout_seconds"] },
+        uncheck: { required: [], optional: [...semanticTarget, "timeout_seconds"] },
+        navigate_menu: { required: ["path"], optional: ["toggle_selector", "timeout_seconds"] },
         assert_network: { required: ["url_contains", "method", "status"], optional: ["message_contains", "timeout_seconds"] },
         extract: { required: ["as"], optional: [...semanticTarget, "source", "attribute", "sensitive", "timeout_seconds"] },
         wait: { required: ["ms"], optional: [] },
@@ -149,7 +206,7 @@ export function validateCandidatePlans(candidatePlans, settings) {
         wait_for_value: { required: ["value"], optional: [...semanticTarget, "timeout_seconds"] },
         wait_for_enabled: { required: [], optional: [...semanticTarget, "timeout_seconds"] },
         press: { required: ["key"], optional: [...semanticTarget, "timeout_seconds"] },
-        select_option: { required: ["option"], optional: [...semanticTarget, "timeout_seconds"] },
+        select_option: { required: [], optional: [...semanticTarget, "option", "value", "label_contains", "timeout_seconds"] },
         hover: { required: [], optional: [...semanticTarget, "timeout_seconds"] },
         assert_text: { required: ["expected"], optional: [...semanticTarget, "timeout_seconds"] },
         assert_value: { required: ["expected"], optional: [...semanticTarget, "timeout_seconds"] },
@@ -171,6 +228,11 @@ export function validateCandidatePlans(candidatePlans, settings) {
         }
         if (rawStep[field] !== undefined) step[field] = rawStep[field];
       }
+      const inferredMutating = looksMutating(rawStep);
+      if (inferredMutating && rawStep.mutating === false) {
+        throw new JevBrowserError(`${action} cannot override the default mutating classification for this action`);
+      }
+      if (inferredMutating) step.mutating = true;
       const selectorFields = locatorFields.filter((field) => rawStep[field] !== undefined);
       const hasNear = rawStep.near !== undefined;
       if (selectorFields.length + Number(hasNear) > 1) {
@@ -183,7 +245,8 @@ export function validateCandidatePlans(candidatePlans, settings) {
       }
       if (rawStep.role !== undefined) {
         const allowedRoles = action === "click" ? CLICK_ROLES
-          : action === "type" || action === "select_option" || action === "assert_value" || action === "wait_for_value" ? TEXT_ROLES
+          : action === "check" || action === "uncheck" ? CHECK_ROLES
+            : action === "type" || action === "select_option" || action === "assert_value" || action === "wait_for_value" ? TEXT_ROLES
             : action === "hover" ? HOVER_ROLES
               : action === "upload_file" ? (rawStep.target === "button" ? new Set(["button"]) : DROPZONE_ROLES)
                 : ASSERT_ROLES;
@@ -236,22 +299,27 @@ export function validateCandidatePlans(candidatePlans, settings) {
         if ((!TARGET_SELECTION_ACTIONS.has(action) && !hiddenWait) || !isRecord(rawStep.within)) {
           throw new JevBrowserError("within must be a semantic container on a target-based browser action");
         }
-        if (rawStep.within.row_containing !== undefined || rawStep.within.row_containing_exact !== undefined) {
-          const exact = rawStep.within.row_containing_exact !== undefined;
-          const key = exact ? "row_containing_exact" : "row_containing";
-          exactKeys(rawStep.within, [key], [], "within");
-          step.within = exact
-            ? { rowContainingExact: requiredText(rawStep.within.row_containing_exact, "within exact row text", settings.jev.maxActionDescriptionChars) }
-            : { rowContaining: requiredText(rawStep.within.row_containing, "within row text", settings.jev.maxActionDescriptionChars) };
-        } else {
-          exactKeys(rawStep.within, ["role"], ["name"], "within");
-          if (typeof rawStep.within.role !== "string" || !CONTAINER_ROLES.has(rawStep.within.role)) {
-            throw new JevBrowserError(`within role must be one of: ${[...CONTAINER_ROLES].join(", ")}`);
-          }
-          step.within = { role: rawStep.within.role };
-          if (rawStep.within.name !== undefined && String(rawStep.within.name).trim()) {
-            step.within.name = requiredText(rawStep.within.name, "within accessible name", settings.jev.maxActionDescriptionChars);
-          }
+        const rowKeys = ["row_containing", "row_containing_exact", "row_containing_word"]
+          .filter((key) => rawStep.within[key] !== undefined);
+        if (rowKeys.length > 1) throw new JevBrowserError("within accepts only one row_containing match mode");
+        exactKeys(rawStep.within, [...(rawStep.within.role !== undefined ? ["role"] : []), ...rowKeys], ["name"], "within");
+        if (rawStep.within.role !== undefined && (typeof rawStep.within.role !== "string" || !CONTAINER_ROLES.has(rawStep.within.role))) {
+          throw new JevBrowserError(`within role must be one of: ${[...CONTAINER_ROLES].join(", ")}`);
+        }
+        if (rawStep.within.name !== undefined && rawStep.within.role === undefined) {
+          throw new JevBrowserError("within.name requires within.role");
+        }
+        if (!rawStep.within.role && rowKeys.length === 0) {
+          throw new JevBrowserError("within needs a semantic container role or row_containing text");
+        }
+        step.within = {};
+        if (rawStep.within.role !== undefined) step.within.role = rawStep.within.role;
+        if (rawStep.within.name !== undefined) step.within.name = requiredText(rawStep.within.name, "within accessible name", settings.jev.maxActionDescriptionChars);
+        if (rowKeys.length) {
+          const key = rowKeys[0];
+          const normalizedKey = key === "row_containing_exact" ? "rowContainingExact"
+            : key === "row_containing_word" ? "rowContainingWord" : "rowContaining";
+          step.within[normalizedKey] = requiredText(rawStep.within[key], `within ${key}`, settings.jev.maxActionDescriptionChars);
         }
       }
       if (rawStep.index !== undefined) {
@@ -266,10 +334,34 @@ export function validateCandidatePlans(candidatePlans, settings) {
         if (typeof rawStep.expect_download !== "boolean") throw new JevBrowserError("click expect_download must be a boolean");
         step.expectDownload = rawStep.expect_download;
       }
+      if (action === "click" && rawStep.expect_popup !== undefined) {
+        if (typeof rawStep.expect_popup !== "boolean") throw new JevBrowserError("click expect_popup must be a boolean");
+        step.expectPopup = rawStep.expect_popup;
+      }
+      if (action === "click" && step.expectDownload && step.expectPopup) {
+        throw new JevBrowserError("click cannot expect both a download and a popup");
+      }
       if (action === "select_option") {
+        const choices = ["option", "value", "label_contains"].filter((key) => rawStep[key] !== undefined);
+        if (choices.length !== 1) throw new JevBrowserError("select_option needs exactly one of option, value, or label_contains");
         if (step.role && step.role !== "combobox") throw new JevBrowserError("select_option role must be combobox");
         step.role = "combobox";
-        step.option = requiredText(rawStep.option, "option", settings.jev.maxActionDescriptionChars);
+        step.option = requiredText(rawStep[choices[0]], choices[0], settings.jev.maxActionDescriptionChars);
+        step.optionMatch = choices[0];
+      }
+      if (action === "check" || action === "uncheck") {
+        if (step.role && !CHECK_ROLES.has(step.role)) throw new JevBrowserError(`${action} role must be checkbox or radio`);
+        if (!step.role) step.role = "checkbox";
+        if (action === "uncheck" && step.role === "radio") throw new JevBrowserError("uncheck does not support radio controls");
+      }
+      if (action === "navigate_menu") {
+        if (!Array.isArray(rawStep.path) || rawStep.path.length === 0 || rawStep.path.length > 8) {
+          throw new JevBrowserError("navigate_menu path must contain between 1 and 8 menu labels");
+        }
+        step.path = rawStep.path.map((label) => requiredText(label, "menu path label", settings.jev.maxActionDescriptionChars));
+        step.toggleSelector = rawStep.toggle_selector === undefined
+          ? "#open_btn"
+          : requiredText(rawStep.toggle_selector, "toggle_selector", settings.jev.maxActionDescriptionChars);
       }
       if (action === "type") {
         if (typeof rawStep.text !== "string" || rawStep.text.length === 0) throw new JevBrowserError("type step needs non-empty text");
@@ -473,8 +565,8 @@ function resolveFlowOptions(rawOptions, settings) {
   }
   const booleanOptions = [
     "block_trackers", "capture_console_errors", "capture_network_error_bodies", "capture_network_errors",
-    "continue_from_current_page", "dry_run", "fast_path", "ready_network_idle", "reuse_page", "screenshot_on_failure", "snapshot_include_hidden",
-    "stop_on_expected", "trace_on_failure",
+    "auto_angular_idle", "block_fonts", "continue_from_current_page", "dry_run", "fast_path", "local_only",
+    "ready_network_idle", "reuse_page", "screenshot_on_failure", "snapshot_include_hidden", "stop_on_expected", "trace_on_failure",
   ];
   for (const key of booleanOptions) {
     if (rawOptions[key] !== undefined && typeof rawOptions[key] !== "boolean") {
@@ -484,6 +576,29 @@ function resolveFlowOptions(rawOptions, settings) {
   const scope = rawOptions.snapshot_scope ?? settings.browser.defaults.snapshotScope;
   if (!new Set(["body", "main", "dialog"]).has(scope)) throw new JevBrowserError("options.snapshot_scope must be body, main, or dialog");
   const defaults = settings.browser.defaults;
+  const stepTimeoutSeconds = rawOptions.step_timeout_seconds ?? settings.browser.actionTimeoutMs / 1000;
+  if (typeof stepTimeoutSeconds !== "number" || !Number.isFinite(stepTimeoutSeconds) || stepTimeoutSeconds <= 0
+    || stepTimeoutSeconds > settings.browser.maxStepTimeoutSeconds) {
+    throw new JevBrowserError(`options.step_timeout_seconds must be positive and at most ${settings.browser.maxStepTimeoutSeconds}`);
+  }
+  const maxFlowSteps = rawOptions.max_flow_steps ?? settings.browser.maxFlowSteps;
+  if (!Number.isSafeInteger(maxFlowSteps) || maxFlowSteps <= 0 || maxFlowSteps > settings.browser.maxFlowSteps) {
+    throw new JevBrowserError(`options.max_flow_steps must be a positive integer no greater than ${settings.browser.maxFlowSteps}`);
+  }
+  const returnSnapshot = rawOptions.return_snapshot ?? defaults.returnSnapshot;
+  if (!new Set(["none", "diff", "full"]).has(returnSnapshot)) throw new JevBrowserError("options.return_snapshot must be none, diff, or full");
+  const normalizeListOption = (key, fallback, maxItems = settings.browser.maxBusySelectors) => {
+    const raw = rawOptions[key] ?? fallback;
+    if (!Array.isArray(raw) || raw.length > maxItems) throw new JevBrowserError(`options.${key} must be an array with at most ${maxItems} entries`);
+    return raw.map((value) => requiredText(value, key, settings.jev.maxActionDescriptionChars));
+  };
+  const busySelectors = normalizeListOption("busy_selectors", settings.browser.busySelectorsDefault);
+  const loginUrlContains = normalizeListOption("login_url_contains", settings.browser.loginUrlContainsDefault);
+  const loginText = normalizeListOption("login_text", settings.browser.loginTextDefault);
+  let confirmationToken;
+  if (rawOptions.confirmation_token !== undefined) {
+    confirmationToken = requiredText(rawOptions.confirmation_token, "confirmation_token", 128);
+  }
   const readyTimeoutSeconds = rawOptions.ready_timeout_seconds ?? defaults.readyTimeoutSeconds;
   if (typeof readyTimeoutSeconds !== "number" || !Number.isFinite(readyTimeoutSeconds) || readyTimeoutSeconds <= 0
     || readyTimeoutSeconds > settings.browser.maxReadyTimeoutSeconds) {
@@ -507,21 +622,31 @@ function resolveFlowOptions(rawOptions, settings) {
     reportPath = rawOptions.report_path;
   }
   return Object.freeze({
+    autoAngularIdle: rawOptions.auto_angular_idle ?? defaults.autoAngularIdle,
     blockTrackers: rawOptions.block_trackers ?? defaults.blockTrackers,
+    blockFonts: rawOptions.block_fonts ?? defaults.blockFonts,
+    busySelectors: Object.freeze(busySelectors),
     captureConsoleErrors: rawOptions.capture_console_errors ?? defaults.captureConsoleErrors,
     captureNetworkErrorBodies: rawOptions.capture_network_error_bodies ?? defaults.captureNetworkErrorBodies,
     captureNetworkErrors: rawOptions.capture_network_errors ?? defaults.captureNetworkErrors,
     dryRun: rawOptions.dry_run ?? false,
     fastPath: rawOptions.fast_path ?? defaults.fastPath,
+    localOnly: rawOptions.local_only ?? defaults.localOnly,
+    loginText: Object.freeze(loginText),
+    loginUrlContains: Object.freeze(loginUrlContains),
+    maxFlowSteps,
     readyTimeoutMs: Math.ceil(readyTimeoutSeconds * 1000),
     readyNetworkIdle: rawOptions.ready_network_idle ?? defaults.readyNetworkIdle,
     readyStableMs,
     readyText,
     reportPath,
+    returnSnapshot,
     reusePage: rawOptions.continue_from_current_page ?? rawOptions.reuse_page ?? defaults.reusePage,
     screenshotOnFailure: rawOptions.screenshot_on_failure ?? defaults.screenshotOnFailure,
     snapshotIncludeHidden: rawOptions.snapshot_include_hidden ?? defaults.snapshotIncludeHidden,
     stopOnExpected: rawOptions.stop_on_expected ?? defaults.stopOnExpected,
+    stepTimeoutMs: Math.ceil(stepTimeoutSeconds * 1000),
+    confirmationToken,
     traceOnFailure: rawOptions.trace_on_failure ?? defaults.traceOnFailure,
     snapshotScope: scope,
   });
@@ -893,7 +1018,7 @@ function containsExpectedOutcome(snapshot, phrase) {
   return containsPhrase(expectedOutcomeText(snapshot), phrase);
 }
 
-function createNetworkTracker(page, settings) {
+function createNetworkTracker(page, settings, loginUrlContains = []) {
   const active = new Map();
   const history = [];
   let sequence = 0;
@@ -923,8 +1048,10 @@ function createNetworkTracker(page, settings) {
     since: (marker, urlContains) => history.filter((entry) => entry.sequence > marker && entry.url.includes(urlContains)),
     responsesSince: (marker, urlContains, method) => history.filter((entry) => entry.sequence > marker
       && entry.type === "response" && entry.url.includes(urlContains) && entry.method === method),
-    authenticationFailureSince: (marker) => history.find((entry) => entry.sequence > marker && entry.type === "response"
-      && (entry.status === 401 || entry.status === 403) && /\/auth(?:\/|\?|$)/i.test(new URL(entry.url).pathname)),
+    authenticationFailureSince: (marker) => history.find((entry) => {
+      if (entry.sequence <= marker || entry.type !== "response" || ![401, 403].includes(entry.status)) return false;
+      return loginUrlContains.some((needle) => entry.url.toLocaleLowerCase().includes(needle.toLocaleLowerCase()));
+    }),
     activeFor: (urlContains) => [...active.values()].filter((entry) => entry.url.includes(urlContains)),
     dispose: () => {
       page.off("request", onRequest);
@@ -957,7 +1084,7 @@ async function waitForFilteredNetworkIdle(tracker, urlContains, marker, timeout,
   throw new JevBrowserError(`requests matching url_contains ${JSON.stringify(urlContains)} did not become idle within ${timeout}ms`);
 }
 
-async function waitForAngularIdle(page, timeout, settings) {
+async function waitForAngularIdle(page, timeout, settings, optional = false) {
   const deadline = performance.now() + timeout;
   let consecutiveIdle = 0;
   while (performance.now() < deadline) {
@@ -981,13 +1108,18 @@ async function waitForAngularIdle(page, timeout, settings) {
         };
       });
     } catch {
+      if (optional) return false;
       throw new JevBrowserError("angular_idle could not inspect the page; the AngularJS application may have navigated or closed");
     }
-    if (!state) throw new JevBrowserError("angular_idle requires an AngularJS 1.x page with an accessible injector");
+    if (!state) {
+      if (optional) return false;
+      throw new JevBrowserError("angular_idle requires an AngularJS 1.x page with an accessible injector");
+    }
     consecutiveIdle = state.pending === 0 && !state.digesting && state.outstanding === 0 ? consecutiveIdle + 1 : 0;
     if (consecutiveIdle >= 2) return;
     await new Promise((resolve) => setTimeout(resolve, Math.min(50, remainingMs(deadline))));
   }
+  if (optional) return false;
   throw new JevBrowserError(`AngularJS still had pending requests or digest work after ${timeout}ms`);
 }
 
@@ -1121,7 +1253,7 @@ async function waitForPageReady(page, options, settings, secrets, continued = fa
     });
     lastSnapshot = snapshot;
     const readyTextVisible = !options.readyText || containsPhrase(snapshot, options.readyText);
-    const usefulSnapshot = await hasRenderedContent(page, snapshot);
+    const usefulSnapshot = await hasRenderedContent(page, snapshot, options.busySelectors);
     if (continued && snapshot && readyTextVisible && usefulSnapshot) {
       return { snapshot, readyMs: performance.now() - started };
     }
@@ -1147,7 +1279,7 @@ async function waitForPageReady(page, options, settings, secrets, continued = fa
   throw error;
 }
 
-async function hasRenderedContent(page, snapshot) {
+async function hasRenderedContent(page, snapshot, busySelectors = []) {
   const lines = snapshot.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
   if (!lines.some((line, index) => index > 0 || /:\s+\S|"[^"]+"/.test(line))) return false;
   try {
@@ -1155,9 +1287,65 @@ async function hasRenderedContent(page, snapshot) {
   } catch {
     // The snapshot itself is the fallback when the DOM is transitioning.
   }
+  for (const selector of busySelectors) {
+    try {
+      const busy = page.locator(selector);
+      const count = await busy.count();
+      for (let index = 0; index < count; index += 1) {
+        if (await isActuallyVisible(locatorAt(busy, index))) return false;
+      }
+    } catch {
+      // A malformed or transient selector does not replace the accessible snapshot readiness signal.
+    }
+  }
   return true;
 }
 
+function sensitiveParamSecrets(variables) {
+  const sensitiveName = /(?:cpf|cnpj|e?mail|telefone|celular|cliente|nome|sacado|pagador|cedente|senha|password|token|api[_-]?key|valor|amount|pre[cç]o)/i;
+  return Object.entries(variables).filter(([name]) => sensitiveName.test(name)).map(([, value]) => value);
+}
+
+async function waitForText(locator, expected, timeout, description, settings) {
+  const normalized = expected.replace(/\s+/g, " ").trim().toLocaleLowerCase();
+  const deadline = performance.now() + timeout;
+  while (performance.now() < deadline) {
+    try {
+      const actual = (await locator.innerText({ timeout: Math.min(250, remainingMs(deadline)) }))
+        .replace(/\s+/g, " ").trim().toLocaleLowerCase();
+      if (actual.includes(normalized)) return;
+    } catch {
+      // SPA rerenders may briefly detach the target.
+    }
+    await new Promise((resolve) => setTimeout(resolve, Math.min(settings.browser.visibilityPollMs, remainingMs(deadline))));
+  }
+  throw new JevBrowserError(`${description} did not contain the expected text within ${timeout}ms`);
+}
+
+async function pageFingerprint(page, snapshot) {
+  let controls = [];
+  let visibleText = "";
+  try {
+    ({ controls, visibleText } = await page.evaluate(() => ({
+      visibleText: String(document.body?.innerText || "").slice(0, 30000),
+      controls: [...document.querySelectorAll("input,textarea,select")].slice(0, 1000).map((element) => ({
+        tag: element.localName,
+        type: element.getAttribute("type") || "",
+        name: element.getAttribute("name") || "",
+        id: element.id || "",
+        value: String(element.value ?? "").slice(0, 4000),
+        checked: "checked" in element ? Boolean(element.checked) : undefined,
+        disabled: Boolean(element.disabled),
+      })),
+    })));
+  } catch {
+    // The page may close between a browser event and an authorization check.
+  }
+  return createHash("sha256").update(JSON.stringify({
+    url: typeof page.url === "function" ? page.url() : "unavailable", snapshot, visibleText, controls,
+  })).digest("hex");
+}
+
 async function snapshotAfterStep(page, settings, secrets, scope, previousSnapshot, stepNumber, warnings, includeHidden) {
   const snapshot = await snapshotPage(page, settings, secrets, scope, { allowEmpty: true, includeHidden });
   if (snapshot) return snapshot;
@@ -1315,22 +1503,45 @@ async function exactlyOne(locator, description, timeout, settings) {
 
 async function scopedRoot(root, within, timeout, settings) {
   if (!within) return root;
-  let locator;
-  let description;
-  if (within.rowContaining) {
-    locator = root.getByRole("row").filter({ hasText: new RegExp(escapeRegex(within.rowContaining), "iu") });
-    description = `row containing ${JSON.stringify(within.rowContaining)}`;
-  } else if (within.rowContainingExact) {
-    locator = root.getByRole("row").filter({ has: root.getByText(within.rowContainingExact, { exact: true }) });
-    description = `row containing exact text ${JSON.stringify(within.rowContainingExact)}`;
-  } else {
+  let scope = root;
+  const descriptions = [];
+  if (within.role) {
     const options = within.name === undefined ? {} : { name: within.name, exact: true };
-    locator = root.getByRole(within.role, options);
-    description = `visible ${within.role} container${within.name === undefined ? "" : ` ${JSON.stringify(within.name)}`}`;
+    const container = root.getByRole(within.role, options);
+    const description = `visible ${within.role} container${within.name === undefined ? "" : ` ${JSON.stringify(within.name)}`}`;
+    const { visible } = await visibleIndexes(container, timeout, `within ${description}`, settings);
+    if (visible.length !== 1) throw new JevBrowserError(`within ${description} must match exactly one visible container; found ${visible.length}`);
+    scope = locatorAt(container, visible[0]);
+    descriptions.push(description);
+  }
+  const rowText = within.rowContainingExact ?? within.rowContainingWord ?? within.rowContaining;
+  if (rowText !== undefined) {
+    const rows = scope.getByRole("row");
+    const mode = within.rowContainingExact !== undefined ? "exact"
+      : within.rowContainingWord !== undefined ? "whole word" : "substring";
+    if (within.rowContainingWord !== undefined) {
+      const pattern = new RegExp(`(?:^|[^\\p{L}\\p{N}])${escapeRegex(rowText)}(?:$|[^\\p{L}\\p{N}])`, "iu");
+      const count = await rows.count();
+      const matches = [];
+      for (let index = 0; index < count; index += 1) {
+        const row = locatorAt(rows, index);
+        if (await isActuallyVisible(row) && pattern.test(await row.innerText())) matches.push(index);
+      }
+      const description = `row containing ${mode} text ${JSON.stringify(rowText)}`;
+      if (matches.length !== 1) throw new JevBrowserError(`within ${description} must match exactly one visible row; found ${matches.length}`);
+      return locatorAt(rows, matches[0]);
+    }
+    const matcher = within.rowContainingExact !== undefined
+      ? { has: scope.getByText(rowText, { exact: true }) }
+      : { hasText: new RegExp(escapeRegex(rowText), "iu") };
+    const rowLocator = rows.filter(matcher);
+    const description = `row containing ${mode} text ${JSON.stringify(rowText)}`;
+    const { visible } = await visibleIndexes(rowLocator, timeout, `within ${description}`, settings);
+    if (visible.length !== 1) throw new JevBrowserError(`within ${description} must match exactly one visible row; found ${visible.length}`);
+    scope = locatorAt(rowLocator, visible[0]);
+    descriptions.push(description);
   }
-  const { visible } = await visibleIndexes(locator, timeout, `within ${description}`, settings);
-  if (visible.length !== 1) throw new JevBrowserError(`within ${description} must match exactly one visible container; found ${visible.length}`);
-  return locatorAt(locator, visible[0]);
+  return scope;
 }
 
 function accessibleNamePattern(name) {
@@ -1429,11 +1640,11 @@ function describeTarget(step, secrets) {
   }
   if (step.near) parts.push(`near text ${JSON.stringify(redact(step.near.text, secrets))}`);
   if (step.within) {
-    parts.push(step.within.rowContainingExact !== undefined
-      ? `within row_containing_exact ${JSON.stringify(redact(step.within.rowContainingExact, secrets))}`
-      : step.within.rowContaining !== undefined
-        ? `within row_containing ${JSON.stringify(redact(step.within.rowContaining, secrets))}`
-        : `within ${step.within.role}${step.within.name === undefined ? "" : ` ${JSON.stringify(redact(step.within.name, secrets))}`}`);
+    if (step.within.role) parts.push(`within ${step.within.role}${step.within.name === undefined ? "" : ` ${JSON.stringify(redact(step.within.name, secrets))}`}`);
+    const rowPrefix = step.within.role ? "" : "within ";
+    if (step.within.rowContainingExact !== undefined) parts.push(`${rowPrefix}row_containing_exact ${JSON.stringify(redact(step.within.rowContainingExact, secrets))}`);
+    else if (step.within.rowContainingWord !== undefined) parts.push(`${rowPrefix}row_containing_word ${JSON.stringify(redact(step.within.rowContainingWord, secrets))}`);
+    else if (step.within.rowContaining !== undefined) parts.push(`${rowPrefix}row_containing ${JSON.stringify(redact(step.within.rowContaining, secrets))}`);
   }
   if (step.index !== undefined) parts.push(`index ${step.index}`);
   return parts.length ? parts.join(" + ") : "focused element";
@@ -1515,8 +1726,8 @@ async function namedTarget(root, step, snapshot, secrets, timeout, settings) {
     if (step.fragileName && step.action === "click") {
       const title = await selected.evaluate((element) => [element, ...element.querySelectorAll("[title]")]
         .map((candidate) => candidate.getAttribute("title") || "").find(Boolean) || "").catch(() => "");
-      if (/\b(cancel|delete|remove|void|cancelar|excluir|apagar|remover|estornar)\b/i.test(title)) {
-        throw new JevBrowserError(`refused index-only click on a destructive control titled ${JSON.stringify(redact(title, secrets))}; provide a stable locator`);
+      if (MUTATING_LABEL.test(title)) {
+        throw new JevBrowserError(`refused index-only click on a mutating control titled ${JSON.stringify(redact(title, secrets))}; provide a stable locator`);
       }
     }
     return selected;
@@ -1716,6 +1927,45 @@ async function saveDownload(download, settings, ledger) {
   }
 }
 
+async function visibleMenuItem(root, label, timeout, settings) {
+  for (const role of ["menuitem", "link", "button"]) {
+    const locator = root.getByRole(role, { name: label, exact: true });
+    try {
+      const { visible } = await visibleIndexes(locator, Math.min(timeout, 250), `menu ${role} ${JSON.stringify(label)}`, settings);
+      if (visible.length > 0) {
+        // Nested application menus often reuse the same label for a parent and its newly opened leaf.
+        return locatorAt(locator, visible.at(-1));
+      }
+    } catch {
+      // Try the next semantic role before falling back to exact visible text.
+    }
+  }
+  const textLocator = root.getByText(label, { exact: true });
+  const { visible } = await visibleIndexes(textLocator, Math.min(timeout, 250), `menu text ${JSON.stringify(label)}`, settings);
+  if (visible.length === 0) throw new JevBrowserError(`menu item ${JSON.stringify(label)} must match a visible control; found 0`);
+  return locatorAt(textLocator, visible.at(-1));
+}
+
+async function navigateMenu(page, root, step, settings, execution) {
+  let item;
+  try {
+    item = await visibleMenuItem(root, step.path[0], 250, settings);
+  } catch {
+    const toggle = page.locator(step.toggleSelector);
+    const { visible } = await visibleIndexes(toggle, 250, `menu toggle ${step.toggleSelector}`, settings);
+    if (visible.length !== 1) throw new JevBrowserError(`menu toggle ${step.toggleSelector} must match exactly one visible control; found ${visible.length}`);
+    await locatorAt(toggle, visible[0]).click({ timeout: step.timeoutMs ?? settings.browser.actionTimeoutMs });
+    if (execution.autoAngularIdle) await waitForAngularIdle(page, step.timeoutMs ?? settings.browser.actionTimeoutMs, settings, true);
+    item = await visibleMenuItem(root, step.path[0], step.timeoutMs ?? settings.browser.actionTimeoutMs, settings);
+  }
+  for (let index = 0; index < step.path.length; index += 1) {
+    if (index > 0) item = await visibleMenuItem(root, step.path[index], step.timeoutMs ?? settings.browser.actionTimeoutMs, settings);
+    await item.click({ timeout: step.timeoutMs ?? settings.browser.actionTimeoutMs });
+    if (execution.autoAngularIdle) await waitForAngularIdle(page, step.timeoutMs ?? settings.browser.actionTimeoutMs, settings, true);
+  }
+  return { action: step.action, navigated_menu: step.path };
+}
+
 async function executeStep(page, step, settings, snapshot, secrets, downloadLedger, execution = {}) {
   const root = await stepRoot(page, step.frame);
   const timeout = step.timeoutMs ?? settings.browser.actionTimeoutMs;
@@ -1732,6 +1982,19 @@ async function executeStep(page, step, settings, snapshot, secrets, downloadLedg
     return { action: step.action, asserted: true, url: evidenceUrl(response.url, secrets, settings.jev.maxDiagnosticChars), method: response.method, response_status: response.status, ...(response.message ? { message: response.message } : {}) };
   }
   if (step.action === "confirm_dialog") {
+    const native = execution.nativeDialog?.result;
+    if (native) {
+      const expectedText = step.expectedText.replace(/\s+/g, " ").trim();
+      if (!native.matched || native.handlerError || !native.message.toLocaleLowerCase().includes(expectedText.toLocaleLowerCase())) {
+        throw new JevBrowserError(`confirm_dialog refused to act: native dialog text did not match ${JSON.stringify(redact(expectedText, secrets))}`);
+      }
+      return {
+        action: step.action,
+        confirmed_text: redact(expectedText, secrets),
+        native_dialog: true,
+        button: redact(step.button, secrets),
+      };
+    }
     const dialog = await exactlyOne(root.getByRole("dialog"), "confirmation dialog", timeout, settings);
     const actualText = (await dialog.innerText({ timeout })).replace(/\s+/g, " ").trim();
     const expectedText = step.expectedText.replace(/\s+/g, " ").trim();
@@ -1881,11 +2144,48 @@ async function executeStep(page, step, settings, snapshot, secrets, downloadLedg
     await waitForEnabled(control, timeout, describeTarget(step, secrets), settings);
     return { action: step.action, enabled: true, ...targetEvidence(step, secrets, await describeResolvedTarget(control, step, secrets, settings)) };
   }
-  const control = await namedTarget(root, step, snapshot, secrets, timeout, settings);
+  if (step.action === "navigate_menu") return navigateMenu(page, root, step, settings, execution);
+  const control = execution.preResolvedTarget || await namedTarget(root, step, snapshot, secrets, timeout, settings);
+  if (step.action === "check" || step.action === "uncheck") {
+    const resolvedTarget = await describeResolvedTarget(control, step, secrets, settings);
+    if (step.action === "check") await control.check({ timeout });
+    else await control.uncheck({ timeout });
+    return { action: step.action, checked: step.action === "check", ...targetEvidence(step, secrets, resolvedTarget) };
+  }
   if (step.action === "click") {
     const resolvedTarget = await describeResolvedTarget(control, step, secrets, settings);
+    if (step.expectPopup) {
+      let popup;
+      try {
+        [popup] = await Promise.all([
+          page.waitForEvent("popup", { timeout: settings.browser.downloadTimeoutMs }),
+          control.click({ timeout }),
+        ]);
+      } catch {
+        throw new JevBrowserError("click did not open the expected popup before the configured timeout");
+      }
+      try {
+        await popup.waitForLoadState("domcontentloaded", { timeout: settings.browser.downloadTimeoutMs }).catch(() => {});
+        const popupUrl = popup.url();
+        const popupTitle = await popup.title().catch(() => "");
+        const isPdf = /\.pdf(?:$|[?#])/i.test(popupUrl)
+          || await popup.locator('embed[type="application/pdf"], iframe[src*=".pdf" i]').count().then((count) => count > 0).catch(() => false);
+        return {
+          action: step.action,
+          ...targetEvidence(step, secrets, resolvedTarget),
+          popup_url: evidenceUrl(popupUrl, secrets, settings.jev.maxDiagnosticChars),
+          ...(popupTitle ? { popup_title: redact(popupTitle, secrets).slice(0, settings.jev.maxDiagnosticChars) } : {}),
+          popup_document_type: isPdf ? "pdf" : "page",
+        };
+      } finally {
+        await popup.close().catch(() => {});
+      }
+    }
     if (!step.expectDownload) {
       await control.click({ timeout });
+      if (execution.nativeDialog?.result && !execution.nativeDialog.result.matched) {
+        throw new JevBrowserError(`unexpected native ${execution.nativeDialog.result.type} dialog was dismissed: ${JSON.stringify(sanitizeDiagnosticText(execution.nativeDialog.result.message, secrets, settings.jev.maxDiagnosticChars))}`);
+      }
       return { action: step.action, ...targetEvidence(step, secrets, resolvedTarget) };
     }
     let download;
@@ -1931,7 +2231,17 @@ async function executeStep(page, step, settings, snapshot, secrets, downloadLedg
   }
   if (step.action === "select_option") {
     const resolvedTarget = await describeResolvedTarget(control, step, secrets, settings);
-    await control.selectOption({ label: step.option }, { timeout });
+    if (step.optionMatch === "value") {
+      await control.selectOption(step.option, { timeout });
+    } else if (step.optionMatch === "label_contains") {
+      const matches = await control.locator("option").evaluateAll((options, text) => options
+        .filter((option) => String(option.label || option.textContent || "").toLocaleLowerCase().includes(text.toLocaleLowerCase()))
+        .map((option) => ({ label: String(option.label || option.textContent || "").trim(), value: String(option.value) })), step.option);
+      if (matches.length !== 1) throw new JevBrowserError(`select_option label_contains must match one option; found ${matches.length}`);
+      await control.selectOption(matches[0].value, { timeout });
+    } else {
+      await control.selectOption({ label: step.option }, { timeout });
+    }
     return { action: step.action, ...targetEvidence(step, secrets, resolvedTarget) };
   }
   if (step.action === "hover") {
@@ -1948,11 +2258,7 @@ async function executeStep(page, step, settings, snapshot, secrets, downloadLedg
     };
   }
   if (step.action === "assert_text") {
-    const actual = (await control.innerText({ timeout })).replace(/\s+/g, " ").trim();
-    const expected = step.expected.replace(/\s+/g, " ").trim();
-    if (!actual.toLocaleLowerCase().includes(expected.toLocaleLowerCase())) {
-      throw new JevBrowserError(`assert_text failed for ${describeTarget(step, secrets)}`);
-    }
+    await waitForText(control, step.expected, timeout, `assert_text for ${describeTarget(step, secrets)}`, settings);
     return {
       action: step.action,
       asserted: true,
@@ -1960,8 +2266,7 @@ async function executeStep(page, step, settings, snapshot, secrets, downloadLedg
     };
   }
   if (step.action === "assert_value") {
-    const actual = await control.inputValue({ timeout });
-    if (actual !== step.expected) throw new JevBrowserError(`assert_value failed for ${describeTarget(step, secrets)}`);
+    await waitForValue(control, step.expected, timeout, `assert_value for ${describeTarget(step, secrets)}`, settings);
     return {
       action: step.action,
       asserted: true,
@@ -1975,6 +2280,24 @@ async function executeStep(page, step, settings, snapshot, secrets, downloadLedg
   throw new JevBrowserError("unsupported browser action");
 }
 
+async function inferTargetMutation(page, step, snapshot, settings, secrets) {
+  if (step.action !== "click") return { mutating: step.mutating === true };
+  const root = await stepRoot(page, step.frame);
+  const target = await namedTarget(root, step, snapshot, secrets, step.timeoutMs ?? settings.browser.actionTimeoutMs, settings);
+  if (step.mutating === true) return { mutating: true, target };
+  if (typeof target?.evaluate !== "function") return { mutating: false, target };
+  const label = await target.evaluate((element) => [
+    element.getAttribute("aria-label"),
+    element.getAttribute("title"),
+    element.getAttribute("value"),
+    element.innerText,
+    element.textContent,
+    ...[...element.querySelectorAll("[title]")].map((child) => child.getAttribute("title")),
+  ].filter(Boolean).join(" "));
+  if (MUTATING_LABEL.test(label)) step.mutating = true;
+  return { mutating: step.mutating === true, target };
+}
+
 function flowTimings(started, browserSessionMs, navigationMs, initialSnapshotMs, readyMs, jevDecisionMs, browserPlanMs) {
   return {
     browser_session_ms: Math.round(browserSessionMs * 10) / 10,
@@ -2147,11 +2470,14 @@ function trackerUrl(url, settings) {
   return settings.browser.trackerHostSuffixes.some((suffix) => hostname === suffix || hostname.endsWith(`.${suffix}`));
 }
 
-async function installTrackerBlocking(context, settings, enabled) {
-  if (!enabled) return undefined;
+async function installTrackerBlocking(context, settings, enabled, blockFonts = false) {
+  if (!enabled && !blockFonts) return undefined;
   const handler = async (route) => {
     const request = route.request();
-    if (trackerUrl(request.url(), settings) || settings.browser.blockedResourceTypes.includes(request.resourceType())) {
+    const resourceType = request.resourceType();
+    if ((enabled && trackerUrl(request.url(), settings))
+      || (enabled && settings.browser.blockedResourceTypes.includes(resourceType) && (resourceType !== "font" || blockFonts))
+      || (blockFonts && resourceType === "font")) {
       await route.abort("blockedbyclient");
       return;
     }
@@ -2261,18 +2587,37 @@ function hasAssertions(steps) {
   return steps.some(({ action }) => action.startsWith("assert_"));
 }
 
-export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, candidatePlans, params: rawParams, options: rawOptions, settings, browserPool, fetchImpl = fetch, serverVersion }) {
+function snapshotDiff(initialSnapshot, finalSnapshot) {
+  const remaining = new Map();
+  for (const line of initialSnapshot.split(/\r?\n/).filter(Boolean)) remaining.set(line, (remaining.get(line) || 0) + 1);
+  const added = [];
+  for (const line of finalSnapshot.split(/\r?\n/).filter(Boolean)) {
+    const count = remaining.get(line) || 0;
+    if (count > 0) remaining.set(line, count - 1);
+    else added.push(line);
+  }
+  return added.length ? added.join("\n") : "[no new snapshot lines]";
+}
+
+export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, candidatePlans, params: rawParams, options: rawOptions, settings, browserPool, fetchImpl = fetch, serverVersion, mutationAuthorizationStore = defaultMutationAuthorizationStore }) {
   if (typeof flow !== "string" || typeof expectedOutcome !== "string") throw new JevBrowserError("flow and expected_outcome must be text");
-  const variables = validateParams(rawParams, settings);
+  let variables = validateParams(rawParams, settings);
   const requestedFlow = replaceKnownParams(flow, variables).trim();
   const outcome = replaceKnownParams(expectedOutcome, variables).trim();
   if (!requestedFlow || !outcome) throw new JevBrowserError("flow and expected_outcome must not be empty");
   if (requestedFlow.length > settings.jev.maxFlowChars) throw new JevBrowserError("flow exceeds the configured character limit");
   if (outcome.length > settings.jev.maxActionDescriptionChars) throw new JevBrowserError("expected_outcome exceeds the configured character limit");
   const url = validateUrl(initialUrl);
-  const plans = validateCandidatePlans(replaceKnownParams(candidatePlans, variables), settings);
   const options = resolveFlowOptions(rawOptions, settings);
-  const secrets = [...planSecrets(plans), settings.env?.[settings.jev.credentialEnv]].filter(Boolean)
+  const plans = validateCandidatePlans(replaceKnownParams(candidatePlans, variables), settings, options.maxFlowSteps);
+  if (options.localOnly && Object.keys(plans).length > 0 && !(options.fastPath && Object.keys(plans).length === 1)) {
+    throw new JevBrowserError("local_only does not call Jev; provide exactly one candidate plan and enable fast_path");
+  }
+  const fingerprint = flowFingerprint({ flow, initialUrl: url, expectedOutcome, candidatePlans, params: rawParams, options });
+  const continuation = options.confirmationToken
+    ? mutationAuthorizationStore.consume(options.confirmationToken, fingerprint)
+    : undefined;
+  const secrets = [...planSecrets(plans), ...sensitiveParamSecrets(variables), settings.env?.[settings.jev.credentialEnv]].filter(Boolean)
     .sort((left, right) => right.length - left.length);
   const contentSecrets = planContentSecrets(plans);
   const started = performance.now();
@@ -2294,11 +2639,12 @@ export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, ca
     unnamed_controls: [],
     unnamed_controls_initial: [],
     unnamed_controls_final: [],
-    warnings: [],
+    warnings: continuation?.warnings || [],
     final_snapshot: "",
   };
+  result.snapshot_mode = options.returnSnapshot;
   const downloadLedger = { count: 0, bytes: 0 };
-  const networkTracker = createNetworkTracker(page, settings);
+  const networkTracker = createNetworkTracker(page, settings, options.loginUrlContains);
   const initialNetworkMarker = networkTracker.mark();
   const timings = { navigationMs: 0, initialSnapshotMs: 0, readyMs: 0, decisionMs: 0, browserPlanMs: 0 };
   let unroute;
@@ -2306,10 +2652,33 @@ export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, ca
   let tracePath;
   const artifactErrors = [];
   let navigationError;
+  let initialSnapshot = "";
+  const nativeDialog = { expectedStep: undefined, result: undefined };
+  const onNativeDialog = async (dialog) => {
+    const expectedStep = nativeDialog.expectedStep;
+    const message = String(dialog.message() || "").replace(/\s+/g, " ").trim();
+    const expectedText = expectedStep?.expectedText?.replace(/\s+/g, " ").trim();
+    const matches = Boolean(expectedText && message.toLocaleLowerCase().includes(expectedText.toLocaleLowerCase()));
+    const affirmative = /^(?:sim|yes|ok|okay|confirm|confirmar|aceitar)$/i.test(expectedStep?.button || "");
+    nativeDialog.result = {
+      message,
+      expectedText,
+      matched: matches,
+      button: expectedStep?.button,
+      type: dialog.type(),
+    };
+    try {
+      if (matches && (dialog.type() === "alert" || affirmative)) await dialog.accept();
+      else await dialog.dismiss();
+    } catch {
+      nativeDialog.result.handlerError = true;
+    }
+  };
+  page.on("dialog", onNativeDialog);
   try {
     page.setDefaultTimeout(settings.browser.actionTimeoutMs);
     context.setDefaultTimeout(settings.browser.actionTimeoutMs);
-    unroute = await installTrackerBlocking(context, settings, options.blockTrackers);
+    unroute = await installTrackerBlocking(context, settings, options.blockTrackers, options.blockFonts);
     if (options.traceOnFailure) {
       try {
         await context.tracing.start({ screenshots: true, snapshots: true });
@@ -2340,6 +2709,9 @@ export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, ca
         } else {
           reusedPage = true;
           result.navigation_strategy = "continued_current_page";
+          if (new URL(currentUrl).href !== new URL(url).href) {
+            addDiagnostic(result.warnings, "initial_url differs from the current same-origin URL; continued from the current page", settings.jev.maxDiagnosticItems);
+          }
         }
       }
     }
@@ -2360,9 +2732,14 @@ export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, ca
       const readiness = await waitForPageReady(page, options, settings, secrets, reusedPage);
       const enriched = await enrichSnapshot(page, readiness.snapshot, settings, secrets, options.snapshotScope, options.snapshotIncludeHidden);
       result.final_snapshot = enriched.snapshot;
+      initialSnapshot = continuation?.initialSnapshot || enriched.snapshot;
       result.unnamed_controls = enriched.unnamedControls;
       result.unnamed_controls_initial = enriched.unnamedControls;
       result.unnamed_controls_final = enriched.unnamedControls;
+      if (options.loginText.some((needle) => result.final_snapshot.toLocaleLowerCase().includes(needle.toLocaleLowerCase()))) {
+        navigationError = "AUTHENTICATION_REQUIRED";
+        throw new JevBrowserError("the configured login text is visible; sign in to the application, then run the flow again");
+      }
       for (const control of enriched.unnamedControls) {
         addDiagnostic(
           result.warnings,
@@ -2372,6 +2749,17 @@ export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, ca
       }
       timings.readyMs = readiness.readyMs;
       browserPool.setNavigationError?.(null);
+      if (continuation) {
+        const currentUrl = typeof page.url === "function" ? page.url() : "unavailable";
+        const currentFingerprint = await pageFingerprint(page, result.final_snapshot);
+        if (continuation.pageUrl !== currentUrl || continuation.pageFingerprint !== currentFingerprint) {
+          throw new JevBrowserError("the page changed after dry_run; run dry_run again before confirming a mutation");
+        }
+        if (!Object.hasOwn(plans, continuation.planId)) {
+          throw new JevBrowserError("confirmation_token refers to a candidate plan that is no longer available");
+        }
+        variables = { ...continuation.variables };
+      }
     } catch (error) {
       timings.readyMs = error.readyMs || performance.now() - snapshotStarted;
       throw error;
@@ -2386,7 +2774,9 @@ export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, ca
     } else {
       let planId;
       let decision;
-      if (options.fastPath && Object.keys(plans).length === 1) {
+      if (continuation) {
+        planId = continuation.planId;
+      } else if (options.fastPath && Object.keys(plans).length === 1) {
         [planId] = Object.keys(plans);
       } else {
         const planIdByDecisionId = new Map();
@@ -2422,34 +2812,77 @@ export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, ca
 
       if (planId) {
         const plan = plans[planId];
-        const trace = [];
+        const trace = continuation ? [...continuation.trace] : [];
         let failure = "";
         let environmentFailure = false;
         let failedStep;
-        let dryRunStop;
+        let mutationStop;
+        let issuedToken;
         let snapshot = result.final_snapshot;
         let networkMarker = networkTracker.mark();
+        result.downloaded_files = continuation?.downloadedFiles || [];
+        result.accessibility_audits = continuation?.accessibilityAudits || [];
+        if (continuation?.downloadLedger) Object.assign(downloadLedger, continuation.downloadLedger);
         const planStarted = performance.now();
         const runAllSteps = plan.steps.some(({ action, expectDownload }) => action.startsWith("assert_")
           || ["upload_file", "select_option", "hover", "like_comment", "unlike_comment", "audit_accessibility"].includes(action)
           || expectDownload === true);
-        for (const [index, templateStep] of plan.steps.entries()) {
+        let approvedMutationIndex = continuation?.nextStep;
+        for (let index = continuation?.nextStep || 0; index < plan.steps.length; index += 1) {
+          const templateStep = plan.steps[index];
           const stepStarted = performance.now();
           let step = templateStep;
           try {
             step = interpolateStep(templateStep, variables);
-            if (options.dryRun && step.mutating === true) {
-              dryRunStop = { step: String(index + 1), action: step.action };
+            step.timeoutMs ??= options.stepTimeoutMs;
+            const mutationInspection = await inferTargetMutation(page, step, snapshot, settings, secrets);
+            const dynamicallyMutating = mutationInspection.mutating;
+            const pairedNativeConfirmation = step.action === "confirm_dialog" && nativeDialog.result?.matched === true;
+            if (dynamicallyMutating && !pairedNativeConfirmation && index !== approvedMutationIndex) {
+              mutationStop = { step: String(index + 1), action: step.action };
+              const enriched = await enrichSnapshot(page, snapshot, settings, secrets, options.snapshotScope, options.snapshotIncludeHidden);
+              snapshot = enriched.snapshot;
+              issuedToken = mutationAuthorizationStore.issue({
+                fingerprint,
+                planId,
+                nextStep: index,
+                variables: { ...variables },
+                trace: [...trace],
+                snapshot,
+                initialSnapshot,
+                pageUrl: typeof page.url === "function" ? page.url() : "unavailable",
+                pageFingerprint: await pageFingerprint(page, snapshot),
+                downloadedFiles: [...result.downloaded_files],
+                accessibilityAudits: [...result.accessibility_audits],
+                warnings: [...result.warnings],
+                consoleErrors: [...(continuation?.consoleErrors || []), ...capture.diagnostics.console_errors],
+                networkFailures: [...(continuation?.networkFailures || []), ...capture.diagnostics.network_failures],
+                downloadLedger: { ...downloadLedger },
+              }, settings.browser.mutationConfirmationTtlMs);
               break;
             }
+            if (index === approvedMutationIndex) approvedMutationIndex = undefined;
             if (step.fragileName) addDiagnostic(result.warnings, `step ${index + 1} uses an empty accessible name with index ${step.index}; this target is fragile`, settings.jev.maxDiagnosticItems);
             if (step.fragileSelector) addDiagnostic(result.warnings, `step ${index + 1} uses an explicit CSS/XPath selector as a last resort`, settings.jev.maxDiagnosticItems);
+            if (step.action === "click" && plan.steps[index + 1]?.action === "confirm_dialog") {
+              nativeDialog.expectedStep = interpolateStep(plan.steps[index + 1], variables);
+              nativeDialog.result = undefined;
+            } else if (step.action !== "confirm_dialog") {
+              nativeDialog.expectedStep = undefined;
+              nativeDialog.result = undefined;
+            }
             const actionMarker = networkTracker.mark();
             const traceStep = await executeStep(page, step, settings, snapshot, secrets, downloadLedger, {
               networkTracker,
               networkMarker,
+              autoAngularIdle: options.autoAngularIdle,
+              nativeDialog,
+              preResolvedTarget: mutationInspection.target,
               variables,
             });
+            if (options.autoAngularIdle && ["click", "type"].includes(step.action)) {
+              await waitForAngularIdle(page, step.timeoutMs ?? options.stepTimeoutMs, settings, true);
+            }
             if (!["wait_for_text", "wait_for_condition", "assert_text", "assert_value", "assert_visible", "assert_hidden", "audit_accessibility"].includes(step.action)) {
               networkMarker = actionMarker;
             }
@@ -2539,17 +2972,19 @@ export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, ca
         const downloadsPassed = expectedDownloadCount > 0 && !failure
           && result.downloaded_files.length === expectedDownloadCount && trace.length === plan.steps.length;
         result.status = failure ? environmentFailure ? "environment_error" : "failed"
-          : dryRunStop ? "dry_run" : visible || assertionsPassed || auditsPassed || downloadsPassed ? "passed" : "incomplete";
+          : mutationStop ? options.dryRun ? "dry_run" : "confirmation_required" : visible || assertionsPassed || auditsPassed || downloadsPassed ? "passed" : "incomplete";
         if (environmentFailure) result.navigation_error = "BROWSER_DISCONNECTED";
         result.expected_outcome_visible = visible;
-        result.acceptance_criteria_met = !failure && !dryRunStop && (visible || assertionsPassed || auditsPassed || downloadsPassed);
+        result.acceptance_criteria_met = !failure && !mutationStop && (visible || assertionsPassed || auditsPassed || downloadsPassed);
         result.selected_plan = planId;
         result.steps_executed = trace.length;
         result.steps = trace;
         result.mutating_steps = trace.filter(({ mutating }) => mutating === true).map(({ step, action, duration_ms, status }) => ({ step, action, duration_ms, status }));
-        if (dryRunStop) {
-          result.dry_run_stopped_before_step = dryRunStop;
-          result.reason = `dry_run stopped before mutating step ${dryRunStop.step} (${dryRunStop.action})`;
+        if (mutationStop) {
+          if (options.dryRun) result.dry_run_stopped_before_step = mutationStop;
+          else result.confirmation_required_before_step = mutationStop;
+          result.confirmation_token = issuedToken;
+          result.reason = `${options.dryRun ? "dry_run stopped" : "confirmation required"} before mutating step ${mutationStop.step} (${mutationStop.action}); rerun the same flow with options.confirmation_token to authorize this one step`;
         }
         result.final_snapshot = snapshot;
         if (failure) {
@@ -2581,6 +3016,8 @@ export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, ca
     if (navigationError) result.navigation_error = navigationError;
     result.reason = authenticationFailure
       ? `The application rejected its authentication request with HTTP ${authenticationFailure.status}; the browser session may have expired. Sign in to the application, then run the flow again.`
+      : navigationError === "AUTHENTICATION_REQUIRED"
+        ? "The configured login URL or login text is visible; sign in to the application, then run the flow again."
       : disconnected ? "The browser session disconnected; run browser_health to reconnect, then retry the flow."
       : error instanceof JevBrowserError
       ? error.message
@@ -2639,17 +3076,23 @@ export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, ca
     }
     networkTracker.dispose();
     await capture.dispose();
+    page.off("dialog", onNativeDialog);
   }
   if (tracePath) result.trace_path = tracePath;
   if (artifactErrors.length) result.artifact_errors = artifactErrors;
-  result.console_errors = capture.diagnostics.console_errors;
-  result.network_failures = capture.diagnostics.network_failures;
+  result.console_errors = [...(continuation?.consoleErrors || []), ...capture.diagnostics.console_errors];
+  result.network_failures = [...(continuation?.networkFailures || []), ...capture.diagnostics.network_failures];
   result.warnings.push(...capture.diagnostics.warnings);
   result.timings_ms = flowTimings(started, browserSessionMs, timings.navigationMs, timings.initialSnapshotMs, timings.readyMs, timings.decisionMs, timings.browserPlanMs);
   const safeResult = await redactObject(result, secrets);
   if (typeof safeResult.final_snapshot === "string") {
     safeResult.final_snapshot = redact(safeResult.final_snapshot, contentSecrets);
   }
+  if (options.returnSnapshot === "diff" && typeof safeResult.final_snapshot === "string") {
+    safeResult.final_snapshot = snapshotDiff(initialSnapshot, safeResult.final_snapshot);
+  } else if (options.returnSnapshot === "none") {
+    delete safeResult.final_snapshot;
+  }
   if (options.reportPath) {
     try {
       safeResult.report_path = await writeFlowReport(safeResult, options.reportPath, settings);
@@ -2660,7 +3103,8 @@ export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, ca
   return safeResult;
 }
 
-export async function chooseNextAction({ flow, pageSnapshot, actions, completedSteps = [], settings, fetchImpl = fetch }) {
+export async function chooseNextAction({ flow, pageSnapshot, actions, completedSteps = [], localOnly = false, settings, fetchImpl = fetch }) {
+  if (localOnly) throw new JevBrowserError("local_only is enabled; choose_next_action cannot call the Jev provider");
   const { request, criteria } = buildChoicePayload({ flow, pageSnapshot, actions, completedSteps }, settings.jev);
   return parseDecision(await requestJev(request, settings, fetchImpl), criteria);
 }