@diegosouzacdv/jev-browser-mcp 0.6.0 → 0.6.2

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", "switch", "cell", "gridcell", "option"]);
+const CHECK_ROLES = new Set(["checkbox", "radio", "switch"]);
 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"]);
@@ -15,22 +16,22 @@ const CONTAINER_ROLES = new Set([
   "group", "list", "listbox", "listitem", "main", "menu", "menubar", "navigation",
   "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",
+const TARGET_SELECTION_ACTIONS = new Set([
+  "click", "check", "uncheck", "type", "clear", "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"];
 const TARGET_LOCATOR_FIELDS = [...LOCATOR_FIELDS, "target_text"];
 const LOCATOR_STEP_KEYS = { label: "label", placeholder: "placeholder", title: "title", text: "targetText", test_id: "testId", selector: "selector", target_text: "typedTargetText" };
 const ASSERT_ROLES = new Set([
-  "alert", "button", "cell", "checkbox", "combobox", "dialog", "gridcell", "heading",
+  "alert", "button", "cell", "checkbox", "combobox", "dialog", "gridcell", "heading",
   "img", "link", "listitem", "main", "menuitem", "option", "paragraph", "progressbar",
-  "radio", "region", "row", "searchbox", "status", "tab", "textbox",
+  "radio", "region", "row", "searchbox", "status", "switch", "tab", "textbox",
 ]);
 const UNNAMED_ACCESSIBLE_NAME = /^[\s\uE000-\uF8FF]*$/u;
 const APPROVED_KEYS = new Set([
   "PageDown", "PageUp", "Home", "End", "ArrowDown", "ArrowUp", "ArrowLeft", "ArrowRight",
-  "Enter", "Escape", "Tab", "Shift+Tab",
+  "Enter", "Escape", "Tab", "Shift+Tab", "Space", "Backspace", "Delete",
 ]);
 const MIME_TYPES = new Map([
   [".csv", "text/csv"], [".json", "application/json"], [".pdf", "application/pdf"],
@@ -38,12 +39,68 @@ const MIME_TYPES = new Map([
   [".txt", "text/plain"], [".webp", "image/webp"],
 ]);
 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",
-  "report_path",
-  "continue_from_current_page", "reuse_page", "screenshot_on_failure", "snapshot_include_hidden", "snapshot_scope", "stop_on_expected",
+  "allow_mutations", "block_trackers", "capture_console_errors", "capture_network_error_bodies", "capture_network_errors",
+  "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", "permissions", "fake_media", "viewport", "mobile", "device_scale_factor", "locale", "timezone_id",
+  "color_scheme", "geolocation", "screenshot_on_success", "record_video", "trace_on_success",
+  "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 +166,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,30 +182,34 @@ 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);
       if (!isRecord(rawStep) || typeof rawStep.action !== "string") throw new JevBrowserError("each browser step must be an object with an action");
       const { action } = rawStep;
       const targetSelection = ["frame", "comment", "within", "index", "near", ...TARGET_LOCATOR_FIELDS];
-      const semanticTarget = [...targetSelection, "role", "name"];
+      const semanticTarget = [...targetSelection, "role", "name", "name_match", "target_page"];
       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"] },
-        type: { required: ["text"], optional: [...semanticTarget, "blur", "mode", "sensitive", "timeout_seconds"] },
+      const schemas = {
+        click: { required: [], optional: [...semanticTarget, "expect_download", "expect_popup", "timeout_seconds"] },
+        type: { required: [], optional: [...semanticTarget, "text", "text_env", "blur", "mode", "sensitive", "timeout_seconds"] },
+        clear: { required: [], optional: [...semanticTarget, "timeout_seconds"] },
+        navigate: { required: ["url"], optional: ["timeout_seconds", "target_page"] },
         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: [] },
-        wait_for_text: { required: ["text"], optional: ["frame", "comment", "fail_on", "timeout_seconds"] },
-        wait_for_condition: { required: ["condition"], optional: [...semanticTarget, "url_contains", "timeout_seconds"] },
+        wait_for_text: { required: ["text"], optional: ["frame", "comment", "fail_on", "target_page", "timeout_seconds"] },
+        wait_for_condition: { required: ["condition"], optional: [...semanticTarget, "url_contains", "timeout_seconds"] },
         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"] },
@@ -157,12 +217,12 @@ export function validateCandidatePlans(candidatePlans, settings) {
         assert_visible: { required: [], optional: [...semanticTarget, "timeout_seconds"] },
         assert_hidden: { required: [], optional: [...semanticTarget, "timeout_seconds"] },
         upload_file: { required: ["file_paths"], optional: ["target", ...semanticTarget, "timeout_seconds"] },
-        audit_accessibility: { required: ["standard"], optional: ["comment", "timeout_seconds"] },
+        audit_accessibility: { required: ["standard"], optional: ["comment", "scope", "fail_on_impact", "timeout_seconds", "target_page"] },
         like_comment: { required: ["author", "text", "like_label", "liked_label"], optional: ["frame", "comment", "timeout_seconds"] },
         unlike_comment: { required: ["author", "text", "like_label", "liked_label"], optional: ["frame", "comment", "timeout_seconds"] },
       };
       if (!Object.hasOwn(schemas, action)) throw new JevBrowserError(`unsupported browser action ${JSON.stringify(action)}; supported actions: ${Object.keys(schemas).join(", ")}`);
-      exactKeys(rawStep, ["action", ...schemas[action].required], [...schemas[action].optional, "mutating", "screenshot"], action);
+      exactKeys(rawStep, ["action", ...schemas[action].required], [...schemas[action].optional, "mutating", "screenshot"], action);
 
       const step = { action };
       for (const field of ["mutating", "screenshot"]) {
@@ -171,6 +231,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 +248,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;
@@ -192,7 +258,7 @@ export function validateCandidatePlans(candidatePlans, settings) {
         }
         step.role = rawStep.role;
       }
-      if (rawStep.name !== undefined) {
+      if (rawStep.name !== undefined) {
         if (typeof rawStep.name !== "string") throw new JevBrowserError("name must be text");
         if (rawStep.name.trim()) step.name = requiredText(rawStep.name, "accessible name", settings.jev.maxActionDescriptionChars);
         else if (rawStep.name === "" && Number.isSafeInteger(rawStep.index) && rawStep.index >= 0) {
@@ -201,8 +267,27 @@ export function validateCandidatePlans(candidatePlans, settings) {
         } else {
           throw new JevBrowserError("name may be empty only when a non-negative index is provided");
         }
-        if (!step.role) throw new JevBrowserError("name requires role; use a locator field such as label, title, placeholder, test_id, text, or selector");
-      }
+        if (!step.role) throw new JevBrowserError("name requires role; use a locator field such as label, title, placeholder, test_id, text, or selector");
+      }
+      if (rawStep.name_match !== undefined) {
+        if (!step.name) throw new JevBrowserError("name_match requires a non-empty name");
+        if (!new Set(["exact", "contains", "regex"]).has(rawStep.name_match)) {
+          throw new JevBrowserError("name_match must be exact, contains, or regex");
+        }
+        if (rawStep.name_match === "regex") {
+          if (step.name.length > 128 || /\([^)]*[+*][^)]*\)[+*{]|\\[1-9]|\(\?[=!<]/.test(step.name)) {
+            throw new JevBrowserError("name_match regex is too long or uses an unsafe construct");
+          }
+          try { new RegExp(step.name, "u"); } catch { throw new JevBrowserError("name_match regex is invalid"); }
+        }
+        step.nameMatch = rawStep.name_match;
+      }
+      if (rawStep.target_page !== undefined) {
+        if (!new Set(["current", "popup"]).has(rawStep.target_page)) {
+          throw new JevBrowserError("target_page must be current or popup");
+        }
+        step.targetPage = rawStep.target_page;
+      }
       if (action === "select_option" && !step.role) step.role = "combobox";
       if (TARGET_SELECTION_ACTIONS.has(action) && action !== "press"
         && !step.role && step.name === undefined && selectorFields.length === 0 && !hasNear) {
@@ -236,22 +321,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,14 +356,47 @@ 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 === "type") {
-        if (typeof rawStep.text !== "string" || rawStep.text.length === 0) throw new JevBrowserError("type step needs non-empty text");
-        if (rawStep.text.length > settings.browser.maxTextEntryChars) throw new JevBrowserError("type text exceeds the configured character limit");
+      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 === "navigate") {
+        step.url = requiredText(rawStep.url, "navigation URL", settings.jev.maxActionDescriptionChars);
+      }
+      if (action === "type") {
+        const hasText = typeof rawStep.text === "string";
+        const hasTextEnv = rawStep.text_env !== undefined;
+        if (hasText === hasTextEnv) throw new JevBrowserError("type step needs exactly one of text or text_env");
+        if (hasText && rawStep.text.length === 0) throw new JevBrowserError("type text must not be empty; use action clear to empty a field");
+        if (hasText && rawStep.text.length > settings.browser.maxTextEntryChars) throw new JevBrowserError("type text exceeds the configured character limit");
+        if (hasTextEnv && (typeof rawStep.text_env !== "string" || !/^[A-Z][A-Z0-9_]*$/.test(rawStep.text_env))) {
+          throw new JevBrowserError("type text_env must name an environment variable such as APP_PASSWORD");
+        }
         if (rawStep.mode !== undefined && !new Set(["fill", "keys"]).has(rawStep.mode)) {
           throw new JevBrowserError("type mode must be fill or keys");
         }
@@ -282,11 +405,16 @@ export function validateCandidatePlans(candidatePlans, settings) {
         if (step.typedTargetText !== undefined && (!step.role || !TEXT_ROLES.has(step.role))) {
           throw new JevBrowserError("type target_text needs role textbox, searchbox, or combobox");
         }
-        step.text = rawStep.text;
-        step.mode = rawStep.mode || "fill";
-        step.blur = rawStep.blur ?? false;
-        step.sensitive = rawStep.sensitive ?? true;
-      }
+        if (hasText) step.text = rawStep.text;
+        if (hasTextEnv) step.textEnv = rawStep.text_env;
+        step.mode = rawStep.mode || "fill";
+        step.blur = rawStep.blur ?? false;
+        step.sensitive = rawStep.sensitive ?? true;
+        if (hasTextEnv && rawStep.sensitive === false) throw new JevBrowserError("type text_env is always sensitive");
+      }
+      if (action === "clear" && step.role && !TEXT_ROLES.has(step.role)) {
+        throw new JevBrowserError("clear requires role textbox, searchbox, or combobox");
+      }
       if (action === "wait_for_text") {
         step.text = requiredText(rawStep.text, "wait text", settings.jev.maxActionDescriptionChars);
         if (rawStep.fail_on !== undefined) {
@@ -343,9 +471,9 @@ export function validateCandidatePlans(candidatePlans, settings) {
         }
         step.sensitive = rawStep.sensitive ?? true;
       }
-      if (action === "wait_for_condition") {
-        if (!new Set(["network_idle", "hidden", "text_hidden", "angular_idle"]).has(rawStep.condition)) {
-          throw new JevBrowserError("wait_for_condition condition must be network_idle, hidden, text_hidden, or angular_idle");
+      if (action === "wait_for_condition") {
+        if (!new Set(["network_idle", "url", "hidden", "text_hidden", "angular_idle"]).has(rawStep.condition)) {
+          throw new JevBrowserError("wait_for_condition condition must be network_idle, url, hidden, text_hidden, or angular_idle");
         }
         step.condition = rawStep.condition;
         if (rawStep.condition === "hidden") {
@@ -364,26 +492,40 @@ export function validateCandidatePlans(candidatePlans, settings) {
           }
           step.text = requiredText(rawStep.text, "hidden text", settings.jev.maxActionDescriptionChars);
           step.targetText = step.text;
-        } else if (rawStep.condition === "angular_idle") {
+        } else if (rawStep.condition === "url") {
+          if (step.role || step.name !== undefined || rawStep.text !== undefined || hasLocatorField(step)
+            || step.near || step.within || rawStep.index !== undefined) {
+            throw new JevBrowserError("url condition accepts only url_contains and timeout_seconds");
+          }
+          step.urlContains = requiredText(rawStep.url_contains, "url_contains", settings.jev.maxActionDescriptionChars);
+        } else if (rawStep.condition === "angular_idle") {
           if (rawStep.url_contains !== undefined || step.role || step.name !== undefined || rawStep.text !== undefined
             || hasLocatorField(step) || step.near || step.within || rawStep.index !== undefined) {
             throw new JevBrowserError("angular_idle condition accepts only condition and timeout_seconds");
           }
-        } else if (step.role || step.name !== undefined || rawStep.text !== undefined || hasLocatorField(step)
-          || step.near || step.within || rawStep.index !== undefined) {
-          throw new JevBrowserError("network_idle condition accepts only url_contains as an optional filter");
-        }
+        } else if (rawStep.condition === "network_idle" && (step.role || step.name !== undefined || rawStep.text !== undefined || hasLocatorField(step)
+          || step.near || step.within || rawStep.index !== undefined)) {
+          throw new JevBrowserError("network_idle condition accepts only url_contains as an optional filter");
+        }
         if (rawStep.condition === "network_idle" && rawStep.url_contains !== undefined) {
           step.urlContains = requiredText(rawStep.url_contains, "url_contains", settings.jev.maxActionDescriptionChars);
-        } else if (rawStep.url_contains !== undefined) {
-          throw new JevBrowserError("url_contains is only supported by the network_idle condition");
+        } else if (rawStep.condition !== "url" && rawStep.url_contains !== undefined) {
+          throw new JevBrowserError("url_contains is only supported by the network_idle and url conditions");
         }
       }
-      if (action === "audit_accessibility") {
+      if (action === "audit_accessibility") {
         if (typeof rawStep.standard !== "string" || !Object.hasOwn(ACCESSIBILITY_STANDARDS, rawStep.standard)) {
           throw new JevBrowserError("audit_accessibility standard must be wcag2aa");
         }
-        step.standard = rawStep.standard;
+        step.standard = rawStep.standard;
+        if (rawStep.scope !== undefined) {
+          step.scope = requiredText(rawStep.scope, "accessibility scope", settings.jev.maxActionDescriptionChars);
+          if (/^xpath(?:=|:)/i.test(step.scope)) throw new JevBrowserError("audit_accessibility scope must be a CSS selector");
+        }
+        step.failOnImpact = rawStep.fail_on_impact ?? settings.browser.accessibilityFailOnImpactDefault;
+        if (!new Set(["minor", "moderate", "serious", "critical"]).has(step.failOnImpact)) {
+          throw new JevBrowserError("audit_accessibility fail_on_impact must be minor, moderate, serious, or critical");
+        }
       }
       if (action === "press") {
         if (typeof rawStep.key !== "string" || !APPROVED_KEYS.has(rawStep.key)) {
@@ -462,7 +604,7 @@ function normalizeStepAliases(rawStep) {
   return step;
 }
 
-function resolveFlowOptions(rawOptions, settings) {
+function resolveFlowOptions(rawOptions, settings) {
   if (rawOptions === undefined) rawOptions = {};
   if (!isRecord(rawOptions) || Object.keys(rawOptions).some((key) => !FLOW_OPTION_KEYS.has(key))) {
     throw new JevBrowserError("options contains unsupported flow settings");
@@ -471,10 +613,11 @@ function resolveFlowOptions(rawOptions, settings) {
     && rawOptions.continue_from_current_page !== rawOptions.reuse_page) {
     throw new JevBrowserError("options.continue_from_current_page and options.reuse_page cannot disagree");
   }
-  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",
+  const booleanOptions = [
+    "allow_mutations", "block_trackers", "capture_console_errors", "capture_network_error_bodies", "capture_network_errors",
+    "auto_angular_idle", "block_fonts", "continue_from_current_page", "dry_run", "fast_path", "local_only",
+    "ready_network_idle", "reuse_page", "screenshot_on_failure", "screenshot_on_success", "record_video", "mobile",
+    "snapshot_include_hidden", "stop_on_expected", "trace_on_failure", "trace_on_success",
   ];
   for (const key of booleanOptions) {
     if (rawOptions[key] !== undefined && typeof rawOptions[key] !== "boolean") {
@@ -484,12 +627,86 @@ 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);
+  const rawPermissions = rawOptions.permissions;
+  if (rawPermissions !== undefined && !Array.isArray(rawPermissions)) {
+    throw new JevBrowserError("options.permissions must contain unique supported values: microphone, geolocation");
+  }
+  const permissions = rawPermissions === undefined ? [] : [...rawPermissions];
+  if (permissions.length > 2
+    || permissions.some((permission) => !new Set(["microphone", "geolocation"]).has(permission))
+    || new Set(permissions).size !== permissions.length) {
+    throw new JevBrowserError("options.permissions must contain unique supported values: microphone, geolocation");
+  }
+  const viewport = rawOptions.viewport;
+  if (viewport !== undefined) {
+    if (!isRecord(viewport)) throw new JevBrowserError("options.viewport must contain width and height");
+    exactKeys(viewport, ["width", "height"], [], "options.viewport");
+    if (!Number.isSafeInteger(viewport.width) || viewport.width < 320 || viewport.width > settings.browser.maxViewportWidth
+      || !Number.isSafeInteger(viewport.height) || viewport.height < 240 || viewport.height > settings.browser.maxViewportHeight) {
+      throw new JevBrowserError(`options.viewport dimensions must be within 320x240 and ${settings.browser.maxViewportWidth}x${settings.browser.maxViewportHeight}`);
+    }
+  }
+  if (rawOptions.mobile === true && !viewport) throw new JevBrowserError("options.viewport is required when options.mobile is true");
+  const deviceScaleFactor = rawOptions.device_scale_factor;
+  if (deviceScaleFactor !== undefined && (typeof deviceScaleFactor !== "number" || !Number.isFinite(deviceScaleFactor)
+    || deviceScaleFactor < 0.5 || deviceScaleFactor > 3)) {
+    throw new JevBrowserError("options.device_scale_factor must be between 0.5 and 3");
+  }
+  const locale = rawOptions.locale === undefined ? undefined : requiredText(rawOptions.locale, "locale", 64);
+  if (locale !== undefined) {
+    try { new Intl.Locale(locale); } catch { throw new JevBrowserError("options.locale must be a valid BCP 47 locale"); }
+  }
+  const timezoneId = rawOptions.timezone_id === undefined ? undefined : requiredText(rawOptions.timezone_id, "timezone_id", 64);
+  if (timezoneId !== undefined) {
+    try { new Intl.DateTimeFormat("en", { timeZone: timezoneId }); } catch { throw new JevBrowserError("options.timezone_id must be a valid IANA time zone"); }
+  }
+  const colorScheme = rawOptions.color_scheme;
+  if (colorScheme !== undefined && !new Set(["light", "dark", "no-preference"]).has(colorScheme)) {
+    throw new JevBrowserError("options.color_scheme must be light, dark, or no-preference");
+  }
+  const geolocation = rawOptions.geolocation;
+  if (geolocation !== undefined) {
+    if (!isRecord(geolocation)) throw new JevBrowserError("options.geolocation must contain latitude and longitude");
+    exactKeys(geolocation, ["latitude", "longitude"], ["accuracy"], "options.geolocation");
+    if (![geolocation.latitude, geolocation.longitude].every((value) => typeof value === "number" && Number.isFinite(value))
+      || geolocation.latitude < -90 || geolocation.latitude > 90 || geolocation.longitude < -180 || geolocation.longitude > 180
+      || (geolocation.accuracy !== undefined && (typeof geolocation.accuracy !== "number" || !Number.isFinite(geolocation.accuracy)
+        || geolocation.accuracy < 0 || geolocation.accuracy > 10000))) {
+      throw new JevBrowserError("options.geolocation coordinates or accuracy are outside valid ranges");
+    }
+    if (!permissions.includes("geolocation")) permissions.push("geolocation");
+  }
+  const fakeMedia = rawOptions.fake_media === undefined ? undefined : requiredText(rawOptions.fake_media, "fake_media", settings.browser.maxUploadPathChars);
+  if (fakeMedia && !permissions.includes("microphone")) permissions.push("microphone");
+  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) {
     throw new JevBrowserError(`options.ready_timeout_seconds must be positive and at most ${settings.browser.maxReadyTimeoutSeconds}`);
   }
-  const readyStableMs = rawOptions.ready_stable_ms ?? defaults.readyStableMs;
+  const readyStableMs = rawOptions.ready_stable_ms ?? defaults.readyStableMs;
   if (!Number.isSafeInteger(readyStableMs) || readyStableMs <= 0 || readyStableMs > settings.browser.maxReadyStableMs
     || readyStableMs > readyTimeoutSeconds * 1000) {
     throw new JevBrowserError("options.ready_stable_ms must be a positive integer within the configured readiness limits");
@@ -506,22 +723,45 @@ function resolveFlowOptions(rawOptions, settings) {
     if (!new Set([".md", ".xml"]).has(extension)) throw new JevBrowserError("options.report_path must end in .md or .xml (JUnit)");
     reportPath = rawOptions.report_path;
   }
-  return Object.freeze({
+  return Object.freeze({
+    allowMutations: rawOptions.allow_mutations ?? false,
+    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),
+    permissions: Object.freeze([...permissions]),
+    fakeMedia,
+    viewport: viewport ? Object.freeze({ width: viewport.width, height: viewport.height }) : undefined,
+    mobile: rawOptions.mobile ?? false,
+    deviceScaleFactor,
+    locale,
+    timezoneId,
+    colorScheme,
+    geolocation: geolocation ? Object.freeze({ ...geolocation }) : undefined,
+    screenshotOnSuccess: rawOptions.screenshot_on_success ?? false,
+    recordVideo: rawOptions.record_video ?? false,
+    traceOnSuccess: rawOptions.trace_on_success ?? settings.browser.defaults.traceOnSuccess,
+    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,
   });
@@ -551,12 +791,12 @@ function planSecrets(plans) {
   return [...secrets].filter(Boolean).sort((left, right) => right.length - left.length);
 }
 
-function redact(value, secrets) {
+function redact(value, secrets) {
   let result = value;
   for (const secret of secrets) {
     const pattern = secret.length < 4
-      ? new RegExp(`(?<![\\p{L}\\p{N}_])${escapeRegex(secret)}(?![\\p{L}\\p{N}_])`, "giu")
-      : new RegExp(escapeRegex(secret), "giu");
+      ? new RegExp(`(?<![\\p{L}\\p{N}_])${escapeRegex(secret)}(?![\\p{L}\\p{N}_])`, "gu")
+      : new RegExp(escapeRegex(secret), "gu");
     result = result.replace(pattern, "[provided form text]");
   }
   return result;
@@ -623,11 +863,110 @@ function planContentSecrets(plans) {
     .filter(Boolean).sort((left, right) => right.length - left.length);
 }
 
-function redactSnapshotFieldValues(snapshot, secrets) {
-  return snapshot.split(/(\r?\n)/).map((line) => /^\s*-\s*(?:textbox|searchbox|combobox)\b/i.test(line)
-    ? redact(line, secrets)
-    : line).join("");
-}
+function redactSnapshotFieldValues(snapshot, secrets) {
+  return snapshot.split(/(\r?\n)/).map((line) => /^\s*-\s*(?:textbox|searchbox|combobox)\b/i.test(line)
+    ? redact(line, secrets)
+    : line).join("");
+}
+
+function providerSafeSnapshot(snapshot, secrets) {
+  return redactSnapshotFieldValues(redact(snapshot, secrets), secrets)
+    .split(/(\r?\n)/).map((line) => {
+      if (/^\s*-\s*(?:textbox|searchbox|combobox)\b/i.test(line)) {
+        return line.replace(/(:\s*).+$/, "$1[form value omitted]");
+      }
+      if (/^\s*-\s*role\b/i.test(line) || /^\s*-\s*\[form controls:/i.test(line)) {
+        return line.replace(/\bvalue=(?:"[^"]*"|'[^']*'|\S+)/gi, 'value="[form value omitted]"');
+      }
+      return line;
+    }).join("")
+    .replace(/https?:\/\/[^\s"'<>]+/gi, (value) => {
+      try {
+        const url = new URL(value);
+        return `${url.origin}${url.pathname}`;
+      } catch {
+        return value.split(/[?#]/, 1)[0];
+      }
+    });
+}
+
+function localHostOnly(url) {
+  return new Set(["localhost", "127.0.0.1", "::1", "[::1]"]).has(new URL(url).hostname.toLowerCase());
+}
+
+async function resolveFakeMediaPath(fakeMedia, settings) {
+  if (!fakeMedia) return undefined;
+  if (!settings.browser.uploadRoot) {
+    throw new JevBrowserError("fake_media is disabled; configure JEV_BROWSER_UPLOAD_ROOT and keep the WAV file inside it");
+  }
+  let root;
+  let audio;
+  try {
+    root = await realpath(settings.browser.uploadRoot);
+    const requested = path.isAbsolute(fakeMedia) ? fakeMedia : path.resolve(root, fakeMedia);
+    audio = await realpath(requested);
+  } catch {
+    throw new JevBrowserError("fake_media could not read the configured WAV file");
+  }
+  const relative = path.relative(root, audio);
+  if (!relative || relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+    throw new JevBrowserError("fake_media path must stay inside JEV_BROWSER_UPLOAD_ROOT");
+  }
+  if (path.extname(audio).toLowerCase() !== ".wav") throw new JevBrowserError("fake_media accepts WAV files only");
+  const file = await stat(audio);
+  if (!file.isFile() || file.size > settings.browser.maxUploadFileBytes) {
+    throw new JevBrowserError("fake_media must be a regular WAV file within the configured file-size limit");
+  }
+  const header = await readFile(audio, { encoding: null, flag: "r" });
+  if (header.length < 12 || header.toString("ascii", 0, 4) !== "RIFF" || header.toString("ascii", 8, 12) !== "WAVE") {
+    throw new JevBrowserError("fake_media file does not have a valid RIFF/WAVE header");
+  }
+  return audio;
+}
+
+async function browserSessionConfiguration(options, settings) {
+  const audioPath = await resolveFakeMediaPath(options.fakeMedia, settings);
+  const contextOptions = {};
+  if (options.viewport) contextOptions.viewport = options.viewport;
+  if (options.mobile) contextOptions.isMobile = true;
+  if (options.mobile) contextOptions.hasTouch = true;
+  if (options.deviceScaleFactor !== undefined) contextOptions.deviceScaleFactor = options.deviceScaleFactor;
+  if (options.locale) contextOptions.locale = options.locale;
+  if (options.timezoneId) contextOptions.timezoneId = options.timezoneId;
+  if (options.colorScheme) contextOptions.colorScheme = options.colorScheme;
+  if (options.geolocation) contextOptions.geolocation = options.geolocation;
+  if (options.permissions.length) contextOptions.permissions = options.permissions;
+  if (options.recordVideo) {
+    contextOptions.recordVideo = {
+      dir: settings.browser.artifactDirectory,
+      size: options.viewport || settings.browser.recordVideoSize,
+    };
+  }
+  const launchArgs = audioPath ? [
+    "--use-fake-device-for-media-stream",
+    "--use-fake-ui-for-media-stream",
+    `--use-file-for-fake-audio-capture=${audioPath}`,
+  ] : [];
+  return { contextOptions, launchArgs };
+}
+
+function resolveEnvironmentText(plans, settings) {
+  for (const plan of Object.values(plans)) {
+    for (const step of plan.steps) {
+      if (step.action !== "type" || !step.textEnv) continue;
+      const value = settings.env?.[step.textEnv];
+      if (typeof value !== "string" || value.length === 0) {
+        throw new JevBrowserError(`type text_env references missing or empty environment variable ${step.textEnv}`);
+      }
+      if (value.length > settings.browser.maxTextEntryChars) {
+        throw new JevBrowserError(`environment value ${step.textEnv} exceeds the configured character limit`);
+      }
+      step.text = value;
+      step.sensitive = true;
+      delete step.textEnv;
+    }
+  }
+}
 
 async function restoreHiddenDialogs(hiddenDialogs) {
   for (const { dialog, previous } of hiddenDialogs.reverse()) {
@@ -893,71 +1232,89 @@ function containsExpectedOutcome(snapshot, phrase) {
   return containsPhrase(expectedOutcomeText(snapshot), phrase);
 }
 
-function createNetworkTracker(page, settings) {
-  const active = new Map();
-  const history = [];
-  let sequence = 0;
-  const record = (type, request) => {
-    const entry = { sequence: ++sequence, type, url: request.url(), method: request.method(), at: performance.now(), request };
+function createNetworkTracker(page, settings, loginUrlContains = []) {
+  const active = new Map();
+  const history = [];
+  const ignored = new Set();
+  let sequence = 0;
+  const shouldIgnore = (request) => {
+    const type = request.resourceType?.();
+    return type === "websocket" || type === "eventsource" || /^wss?:/i.test(request.url());
+  };
+  const record = (type, request) => {
+    if (shouldIgnore(request)) {
+      if (type === "request") ignored.add(request);
+      if (type === "finished" || type === "failed") ignored.delete(request);
+      return undefined;
+    }
+    if (ignored.has(request)) return undefined;
+    const entry = { sequence: ++sequence, type, url: request.url(), method: request.method(), at: performance.now(), request };
     if (type === "request") active.set(request, entry);
     else if (type === "finished" || type === "failed") active.delete(request);
     history.push(entry);
-    const historyLimit = settings.browser.maxFlowSteps * 8;
+    const historyLimit = settings.browser.maxNetworkHistoryEvents;
     if (history.length > historyLimit) history.splice(0, history.length - historyLimit);
     return entry;
   };
   const onRequest = (request) => record("request", request);
-  const onResponse = (response) => {
-    const entry = record("response", response.request());
+  const onResponse = (response) => {
+    const entry = record("response", response.request());
+    if (!entry) return;
     entry.response = response;
     entry.status = response.status();
-  };
-  const onFinished = (request) => record("finished", request);
-  const onFailed = (request) => record("failed", request);
-  page.on("request", onRequest);
-  page.on("response", onResponse);
-  page.on("requestfinished", onFinished);
-  page.on("requestfailed", onFailed);
-  return {
-    mark: () => sequence,
-    since: (marker, urlContains) => history.filter((entry) => entry.sequence > marker && entry.url.includes(urlContains)),
+  };
+  const onFinished = (request) => record("finished", request);
+  const onFailed = (request) => record("failed", request);
+  const trackedPages = new Set();
+  const attachPage = (trackedPage) => {
+    if (trackedPages.has(trackedPage)) return;
+    trackedPages.add(trackedPage);
+    trackedPage.on("request", onRequest);
+    trackedPage.on("response", onResponse);
+    trackedPage.on("requestfinished", onFinished);
+    trackedPage.on("requestfailed", onFailed);
+  };
+  attachPage(page);
+  return {
+    mark: () => sequence,
+    attachPage,
+    since: (marker, urlContains) => history.filter((entry) => entry.sequence > marker
+      && (urlContains === undefined || 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)),
-    activeFor: (urlContains) => [...active.values()].filter((entry) => entry.url.includes(urlContains)),
-    dispose: () => {
-      page.off("request", onRequest);
-      page.off("response", onResponse);
-      page.off("requestfinished", onFinished);
-      page.off("requestfailed", onFailed);
-      active.clear();
-      history.length = 0;
+    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: () => {
+      for (const trackedPage of trackedPages) {
+        trackedPage.off("request", onRequest);
+        trackedPage.off("response", onResponse);
+        trackedPage.off("requestfinished", onFinished);
+        trackedPage.off("requestfailed", onFailed);
+      }
+      trackedPages.clear();
+      active.clear();
+      ignored.clear();
+      history.length = 0;
     },
   };
 }
 
-async function waitForFilteredNetworkIdle(tracker, urlContains, marker, timeout, settings) {
-  const started = performance.now();
-  let sawRequest = false;
-  let lastMatchingActivity = started;
-  const quietMs = settings.browser.defaults.readyStableMs;
-  while (performance.now() - started < timeout) {
-    const events = tracker.since(marker, urlContains);
-    if (events.length) {
-      sawRequest = sawRequest || events.some(({ type }) => type === "request");
-      lastMatchingActivity = events.at(-1).at;
-    }
-    const active = tracker.activeFor(urlContains);
-    if (active.length) sawRequest = true;
-    if (sawRequest && active.length === 0 && performance.now() - lastMatchingActivity >= quietMs) return;
-    await new Promise((resolve) => setTimeout(resolve, Math.min(settings.browser.visibilityPollMs, remainingMs(started + timeout))));
-  }
-  if (!sawRequest) throw new JevBrowserError(`network_idle did not observe a request matching url_contains ${JSON.stringify(urlContains)} within ${timeout}ms`);
-  throw new JevBrowserError(`requests matching url_contains ${JSON.stringify(urlContains)} did not become idle within ${timeout}ms`);
+async function waitForFilteredNetworkIdle(tracker, urlContains, marker, timeout, quietMs, settings) {
+  const started = performance.now();
+  let lastMatchingActivity = started;
+  while (performance.now() - started < timeout) {
+    const events = tracker.since(marker, urlContains);
+    if (events.length) lastMatchingActivity = Math.max(lastMatchingActivity, events.at(-1).at);
+    if (performance.now() - lastMatchingActivity >= quietMs) return;
+    await new Promise((resolve) => setTimeout(resolve, Math.min(settings.browser.visibilityPollMs, remainingMs(started + timeout))));
+  }
+  throw new JevBrowserError(`network activity${urlContains ? ` 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,17 +1338,22 @@ 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`);
 }
 
-async function waitForValue(locator, expected, timeout, description, settings) {
+async function waitForValue(locator, expected, timeout, description, settings) {
   const deadline = performance.now() + timeout;
   while (performance.now() < deadline) {
     try {
@@ -1090,12 +1452,46 @@ function remainingMs(deadline) {
   return Math.max(1, Math.ceil(deadline - performance.now()));
 }
 
-function browserDisconnected(error) {
+function browserDisconnected(error) {
   return /target (?:page, context or browser )?has been closed|browser (?:has been closed|disconnected)|context has been closed|connection closed/i
     .test(String(error?.message || error?.name || ""));
-}
-
-async function waitForPageReady(page, options, settings, secrets, continued = false) {
+}
+
+function snapshotStabilityKey(snapshot) {
+  return snapshot.split(/\r?\n/)
+    .filter((line) => !/^\s*-\s*text:/i.test(line))
+    .map((line) => line.replace(/"(?:\\.|[^"\\])*"/g, '""').replace(/\bvalue=(?:"[^"]*"|'[^']*'|\S+)/gi, 'value=""'))
+    .join("\n");
+}
+
+async function pageStructureSignature(page, snapshot) {
+  try {
+    const structure = await page.evaluate(() => {
+      const elements = [];
+      const visit = (root) => {
+        for (const element of root.querySelectorAll("*")) {
+          elements.push([
+            element.localName,
+            element.getAttribute("role") || "",
+            element.id || "",
+            element.getAttribute("type") || "",
+            element.getAttribute("aria-busy") || "",
+            Boolean(element.disabled),
+          ]);
+          if (element.shadowRoot) visit(element.shadowRoot);
+          if (elements.length >= 5000) return;
+        }
+      };
+      visit(document);
+      return elements;
+    });
+    return JSON.stringify(structure);
+  } catch {
+    return snapshotStabilityKey(snapshot);
+  }
+}
+
+async function waitForPageReady(page, options, settings, secrets, continued = false) {
   const started = performance.now();
   const deadline = started + options.readyTimeoutMs;
   const bestEffortLoadState = async (state) => {
@@ -1110,7 +1506,7 @@ async function waitForPageReady(page, options, settings, secrets, continued = fa
     if (options.readyNetworkIdle) await bestEffortLoadState("networkidle");
   }
 
-  let previousSnapshot = "";
+  let previousStabilityKey = "";
   let stableSince = 0;
   let lastSnapshot = "";
   while (performance.now() < deadline) {
@@ -1119,24 +1515,25 @@ async function waitForPageReady(page, options, settings, secrets, continued = fa
       timeoutMs: remainingMs(deadline),
       includeHidden: options.snapshotIncludeHidden,
     });
-    lastSnapshot = snapshot;
+    lastSnapshot = snapshot;
+    const stabilityKey = await pageStructureSignature(page, 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 };
     }
     if (snapshot && readyTextVisible && usefulSnapshot) {
-      if (snapshot === previousSnapshot) {
+      if (stabilityKey === previousStabilityKey) {
         if (!stableSince) stableSince = performance.now();
         if (performance.now() - stableSince >= options.readyStableMs) {
           return { snapshot, readyMs: performance.now() - started };
         }
       } else {
-        previousSnapshot = snapshot;
-        stableSince = performance.now();
-      }
-    } else {
-      previousSnapshot = "";
+        previousStabilityKey = stabilityKey;
+        stableSince = performance.now();
+      }
+    } else {
+      previousStabilityKey = "";
       stableSince = 0;
     }
     await new Promise((resolve) => setTimeout(resolve, Math.min(100, remainingMs(deadline))));
@@ -1147,17 +1544,93 @@ 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 {
-    if (await page.locator('[aria-busy="true"]').count() > 0) return false;
+  try {
+    const busy = page.locator('[aria-busy="true"]');
+    const count = await busy.count();
+    for (let index = 0; index < count; index += 1) {
+      if (await isActuallyVisible(locatorAt(busy, index))) return false;
+    }
   } 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) {
+  let structure = [];
+  try {
+    structure = await page.evaluate(() => {
+      const controls = [];
+      const visit = (root) => {
+        for (const element of root.querySelectorAll("a[href],button,input,textarea,select,[role]")) {
+          const style = getComputedStyle(element);
+          if (style.display === "none" || style.visibility === "hidden" || element.getClientRects().length === 0) continue;
+          controls.push({
+            tag: element.localName,
+            role: element.getAttribute("role") || "",
+            type: element.getAttribute("type") || "",
+            name: element.getAttribute("name") || "",
+            id: element.id || "",
+            href: element instanceof HTMLAnchorElement ? `${element.origin}${element.pathname}` : "",
+            disabled: Boolean(element.disabled || element.getAttribute("aria-disabled") === "true"),
+            checked: "checked" in element ? Boolean(element.checked) : undefined,
+            expanded: element.getAttribute("aria-expanded") || "",
+          });
+          if (element.shadowRoot) visit(element.shadowRoot);
+        }
+      };
+      visit(document);
+      return controls.slice(0, 2000);
+    });
+  } catch {
+    // The page may close between a browser event and an authorization check.
+  }
+  let route = "unavailable";
+  try {
+    const url = new URL(page.url());
+    route = `${url.origin}${url.pathname}`;
+  } catch { /* Keep the unavailable marker. */ }
+  return createHash("sha256").update(JSON.stringify({
+    route,
+    structure,
+  })).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 +1788,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) {
@@ -1338,11 +1834,40 @@ function accessibleNamePattern(name) {
   return new RegExp(`^[\\s\\uE000-\\uF8FF]*${normalized}[\\s\\uE000-\\uF8FF]*$`, "u");
 }
 
-function roleOptions(step) {
-  if (step.name === "") return { name: UNNAMED_ACCESSIBLE_NAME };
-  if (step.name === undefined) return {};
-  return { name: step.name, exact: true };
-}
+function roleOptions(step) {
+  if (step.name === "") return { name: UNNAMED_ACCESSIBLE_NAME };
+  if (step.name === undefined) return {};
+  if (step.nameMatch === "contains") return { name: step.name, exact: false };
+  if (step.nameMatch === "regex") return { name: new RegExp(step.name, "u") };
+  return { name: step.name, exact: true };
+}
+
+async function waitForUrlContains(page, fragment, timeout, settings) {
+  const deadline = performance.now() + timeout;
+  while (performance.now() < deadline) {
+    if (page.url().includes(fragment)) return;
+    await new Promise((resolve) => setTimeout(resolve, Math.min(settings.browser.visibilityPollMs, remainingMs(deadline))));
+  }
+  throw new JevBrowserError(`page URL did not contain ${JSON.stringify(fragment)} within ${timeout}ms`);
+}
+
+async function clickAndWaitForLoad(page, control, timeout) {
+  const isPageClosed = () => typeof page.isClosed === "function" && page.isClosed();
+  const waitForDocument = async () => {
+    if (!isPageClosed() && typeof page.waitForLoadState === "function") {
+      await page.waitForLoadState("domcontentloaded", { timeout });
+    }
+  };
+  try {
+    await control.click({ timeout });
+  } catch (error) {
+    if (!/execution context was destroyed|frame was detached/i.test(String(error?.message || ""))) throw error;
+    if (isPageClosed()) throw error;
+    await waitForDocument();
+    return;
+  }
+  await waitForDocument();
+}
 
 function xpathRolePredicate(role) {
   const nativePredicates = {
@@ -1403,10 +1928,10 @@ async function targetLocator(root, step, timeout, settings) {
     locator = targetRoot.getByTestId(step.testId);
   } else if (step.near) {
     locator = relativeTarget(targetRoot.getByText(step.near.text, { exact: true }).first(), step.role);
-  } else if (step.role) {
-    locator = targetRoot.getByRole(step.role, roleOptions(step));
-    if (step.name && await locator.count() === 0) {
-      locator = targetRoot.getByRole(step.role, { name: accessibleNamePattern(step.name) });
+  } else if (step.role) {
+    locator = targetRoot.getByRole(step.role, roleOptions(step));
+    if (step.name && (!step.nameMatch || step.nameMatch === "exact") && await locator.count() === 0) {
+      locator = targetRoot.getByRole(step.role, { name: accessibleNamePattern(step.name) });
     }
   } else {
     throw new JevBrowserError("step has no resolvable target; use role/name, label, placeholder, title, text, target_text, test_id, selector, or near");
@@ -1429,11 +1954,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 +2040,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,9 +2241,61 @@ async function saveDownload(download, settings, ledger) {
   }
 }
 
-async function executeStep(page, step, settings, snapshot, secrets, downloadLedger, execution = {}) {
-  const root = await stepRoot(page, step.frame);
-  const timeout = step.timeoutMs ?? settings.browser.actionTimeoutMs;
+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;
+  if (step.action === "navigate") {
+    let destination;
+    try { destination = new URL(step.url, page.url()).toString(); } catch {
+      throw new JevBrowserError("navigate URL must be absolute or relative to the current page");
+    }
+    destination = validateUrl(destination);
+    if (execution.allowMutations && !localHostOnly(destination)) {
+      throw new JevBrowserError("allow_mutations only permits navigation to localhost, 127.0.0.1, or ::1");
+    }
+    await page.goto(destination, { waitUntil: "domcontentloaded", timeout });
+    execution.browserPool?.setNavigationError?.(null);
+    return { action: step.action, url: evidenceUrl(destination, secrets, settings.jev.maxDiagnosticChars) };
+  }
   if (step.action === "assert_network") {
     const response = await waitForNetworkAssertion(
       execution.networkTracker,
@@ -1732,6 +2309,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();
@@ -1783,29 +2373,29 @@ async function executeStep(page, step, settings, snapshot, secrets, downloadLedg
     await waitForAngularIdle(page, timeout, settings);
     return { action: step.action, condition: step.condition };
   }
-  if (step.action === "wait_for_condition") {
-    if (step.condition === "network_idle") {
-      if (step.urlContains) {
-        await waitForFilteredNetworkIdle(
-          execution.networkTracker,
-          step.urlContains,
-          execution.networkMarker,
-          timeout,
-          settings,
-        );
-      } else {
-        await root.waitForLoadState("networkidle", { timeout });
-      }
-    } else {
+  if (step.action === "wait_for_condition") {
+    if (step.condition === "network_idle") {
+      await waitForFilteredNetworkIdle(
+        execution.networkTracker,
+        step.urlContains,
+        execution.networkMarker,
+        timeout,
+        execution.readyStableMs,
+        settings,
+      );
+    } else if (step.condition === "url") {
+      await waitForUrlContains(page, step.urlContains, timeout, settings);
+    } else {
       const locator = await targetLocator(root, step, timeout, settings);
       await waitForLocatorHidden(locator, timeout, `hidden condition ${describeTarget(step, secrets)}`, settings, step.index);
     }
     return {
       action: step.action,
-      condition: step.condition,
-      ...(step.condition === "network_idle"
-        ? (step.urlContains ? { url_contains: redact(step.urlContains, secrets) } : {})
-        : { target: describeTarget(step, secrets) }),
+      condition: step.condition,
+      ...(step.condition === "network_idle"
+        ? (step.urlContains ? { url_contains: redact(step.urlContains, secrets) } : {})
+        : step.condition === "url" ? { url_contains: redact(step.urlContains, secrets) }
+          : { target: describeTarget(step, secrets) }),
     };
   }
   if (step.action === "press") {
@@ -1822,14 +2412,18 @@ async function executeStep(page, step, settings, snapshot, secrets, downloadLedg
   if (step.action === "like_comment" || step.action === "unlike_comment") {
     return { action: step.action, result: await reactToComment(root, step, timeout, settings) };
   }
-  if (step.action === "audit_accessibility") {
-    return {
-      action: step.action,
-      accessibility_audit: await withTimeout(
-        runAccessibilityAudit(page, step.standard, settings),
-        timeout,
-        `accessibility audit exceeded the ${timeout}ms step timeout`,
-      ),
+  if (step.action === "audit_accessibility") {
+    const accessibilityAudit = await withTimeout(
+      runAccessibilityAudit(page, step.standard, settings, {
+        scope: step.scope,
+        failOnImpact: step.failOnImpact,
+      }),
+      timeout,
+      `accessibility audit exceeded the ${timeout}ms step timeout`,
+    );
+    return {
+      action: step.action,
+      accessibility_audit: accessibilityAudit,
     };
   }
   if (step.action === "upload_file") {
@@ -1881,11 +2475,46 @@ 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.expectDownload) {
-      await control.click({ timeout });
+    if (step.expectPopup) {
+      let popup;
+      try {
+        [popup] = await Promise.all([
+          page.waitForEvent("popup", { timeout: settings.browser.downloadTimeoutMs }),
+          clickAndWaitForLoad(page, control, timeout),
+        ]);
+      } catch {
+        throw new JevBrowserError("click did not open the expected popup before the configured timeout");
+      }
+      execution.popupPage = popup;
+      execution.networkTracker?.attachPage(popup);
+      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",
+      };
+    }
+    if (!step.expectDownload) {
+      await clickAndWaitForLoad(page, control, 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;
@@ -1903,7 +2532,7 @@ async function executeStep(page, step, settings, snapshot, secrets, downloadLedg
       downloaded_file: await saveDownload(download, settings, downloadLedger),
     };
   }
-  if (step.action === "type") {
+  if (step.action === "type") {
     const resolvedTarget = await describeResolvedTarget(control, step, secrets, settings);
     if (step.mode === "keys") {
       await control.fill("", { timeout });
@@ -1928,10 +2557,25 @@ async function executeStep(page, step, settings, snapshot, secrets, downloadLedg
       name: step.name,
       ...targetEvidence(step, secrets, resolvedTarget),
     };
-  }
+  }
+  if (step.action === "clear") {
+    const resolvedTarget = await describeResolvedTarget(control, step, secrets, settings);
+    await control.fill("", { timeout });
+    return { action: step.action, cleared: true, ...targetEvidence(step, secrets, resolvedTarget) };
+  }
   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 +2592,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 +2600,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 +2614,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,
@@ -1987,9 +2644,20 @@ function flowTimings(started, browserSessionMs, navigationMs, initialSnapshotMs,
   };
 }
 
-function addDiagnostic(collection, value, limit) {
-  if (collection.length < limit) collection.push(value);
-}
+function addDiagnostic(collection, value, limit) {
+  if (collection.length < limit) collection.push(value);
+}
+
+function groupConsoleErrors(errors) {
+  const grouped = new Map();
+  for (const entry of errors) {
+    const message = typeof entry === "string" ? entry : String(entry?.message || "");
+    if (!message) continue;
+    const count = typeof entry === "object" ? Math.max(1, Number(entry.count) || 1) : 1;
+    grouped.set(message, (grouped.get(message) || 0) + count);
+  }
+  return [...grouped].map(([message, count]) => ({ message, count }));
+}
 
 function evidenceUrl(value, secrets, limit) {
   try {
@@ -2012,17 +2680,22 @@ function sanitizeDiagnosticText(value, secrets, limit) {
   return result.slice(0, limit);
 }
 
-function createDiagnostics(page, options, settings, secrets) {
+function createDiagnostics(page, options, settings, secrets) {
   const diagnostics = { console_errors: [], network_failures: [], warnings: [] };
   const pendingBodies = [];
   const limit = settings.jev.maxDiagnosticItems;
-  const messageLimit = settings.jev.maxDiagnosticChars;
-  const onConsole = (message) => {
-    if (message.type() !== "error") return;
-    addDiagnostic(diagnostics.console_errors, sanitizeDiagnosticText(message.text(), secrets, messageLimit), limit);
-  };
-  const onPageError = (error) => {
-    addDiagnostic(diagnostics.console_errors, sanitizeDiagnosticText(error.message || error.name, secrets, messageLimit), limit);
+  const messageLimit = settings.jev.maxDiagnosticChars;
+  const addConsoleError = (value) => {
+    const existing = diagnostics.console_errors.find((entry) => entry.message === value);
+    if (existing) existing.count += 1;
+    else if (diagnostics.console_errors.length < limit) diagnostics.console_errors.push({ message: value, count: 1 });
+  };
+  const onConsole = (message) => {
+    if (message.type() !== "error") return;
+    addConsoleError(sanitizeDiagnosticText(message.text(), secrets, messageLimit));
+  };
+  const onPageError = (error) => {
+    addConsoleError(sanitizeDiagnosticText(error.message || error.name, secrets, messageLimit));
   };
   const addResponseMessage = async (response, entry) => {
     const warn = (reason) => addDiagnostic(
@@ -2147,11 +2820,15 @@ 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, allowMedia = 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) && (resourceType !== "media" || !allowMedia))
+      || (blockFonts && resourceType === "font")) {
       await route.abort("blockedbyclient");
       return;
     }
@@ -2237,20 +2914,40 @@ function reportContent(result, extension) {
   ].join("\n");
 }
 
-async function writeFlowReport(result, reportPath, settings) {
+async function writeFlowReport(result, reportPath, settings) {
   const outputPath = await safeReportPath(reportPath, settings);
   await writeFile(outputPath, reportContent(result, path.extname(outputPath).toLowerCase()), { encoding: "utf8", flag: "w" });
   return outputPath;
-}
+}
+
+async function collectPerformanceMetrics(page) {
+  try {
+    return await page.evaluate(() => {
+      const navigation = performance.getEntriesByType("navigation")[0];
+      const paints = performance.getEntriesByType("paint");
+      const firstContentfulPaint = paints.find(({ name }) => name === "first-contentful-paint")?.startTime;
+      return {
+        dom_interactive_ms: navigation ? Math.round(navigation.domInteractive * 10) / 10 : null,
+        dom_content_loaded_ms: navigation ? Math.round(navigation.domContentLoadedEventEnd * 10) / 10 : null,
+        load_event_ms: navigation ? Math.round(navigation.loadEventEnd * 10) / 10 : null,
+        first_contentful_paint_ms: Number.isFinite(firstContentfulPaint) ? Math.round(firstContentfulPaint * 10) / 10 : null,
+        resource_count: performance.getEntriesByType("resource").length,
+        transfer_size_bytes: performance.getEntriesByType("resource").reduce((sum, entry) => sum + Number(entry.transferSize || 0), 0),
+      };
+    });
+  } catch {
+    return undefined;
+  }
+}
 
 async function redactObject(value, secrets) {
   if (typeof value === "string") return redact(value, secrets);
   if (Array.isArray(value)) return Promise.all(value.map((item) => redactObject(item, secrets)));
   if (isRecord(value)) {
     return Object.fromEntries(await Promise.all(Object.entries(value).map(async ([key, item]) => [
-      key,
-      key === "final_snapshot" && typeof item === "string"
-        ? redactSnapshotFieldValues(item, secrets)
+      key,
+      key === "final_snapshot" && typeof item === "string"
+        ? redactSnapshotFieldValues(redact(item, secrets), secrets)
         : await redactObject(item, secrets),
     ])));
   }
@@ -2261,22 +2958,50 @@ 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 options = resolveFlowOptions(rawOptions, settings);
+  const plans = validateCandidatePlans(replaceKnownParams(candidatePlans, variables), settings, options.maxFlowSteps);
+  resolveEnvironmentText(plans, settings);
+  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");
+  }
+  if (options.allowMutations && !localHostOnly(url)) {
+    throw new JevBrowserError("allow_mutations is limited to localhost, 127.0.0.1, and ::1 URLs");
+  }
+  const secretBearingFlow = Object.values(plans).some((plan) => plan.steps.some((step) => step.action === "type" && step.sensitive));
+  if (options.recordVideo && secretBearingFlow) {
+    throw new JevBrowserError("record_video is disabled for flows that type sensitive text");
+  }
+  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();
-  const browser = await browserPool.getPage();
+  const contentSecrets = planContentSecrets(plans);
+  const started = performance.now();
+  const sessionConfiguration = await browserSessionConfiguration(options, settings);
+  const browser = await browserPool.getPage(sessionConfiguration);
   const browserSessionMs = browser.sessionMs;
   const page = browser.page;
   const context = browser.context;
@@ -2294,29 +3019,64 @@ 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;
+  if (options.allowMutations) result.mutation_authorization = "allowed_on_localhost";
   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;
   let tracingStarted = false;
   let tracePath;
-  const artifactErrors = [];
-  let navigationError;
+  const artifactErrors = [];
+  let navigationError;
+  let initialSnapshot = "";
+  let popupPage;
+  let activePage = page;
+  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);
-    if (options.traceOnFailure) {
-      try {
+    unroute = await installTrackerBlocking(
+      context,
+      settings,
+      options.blockTrackers,
+      options.blockFonts,
+      options.permissions.includes("microphone") || Boolean(options.fakeMedia),
+    );
+    if ((options.traceOnFailure || options.traceOnSuccess) && !secretBearingFlow) {
+      try {
         await context.tracing.start({ screenshots: true, snapshots: true });
         tracingStarted = true;
       } catch {
-        artifactErrors.push("trace recording could not be started");
-      }
+        artifactErrors.push("trace recording could not be started");
+      }
+    } else if ((options.traceOnFailure || options.traceOnSuccess || options.recordVideo) && secretBearingFlow) {
+      addDiagnostic(result.warnings, "trace, video, and screenshots were suppressed because this flow contains sensitive text", settings.jev.maxDiagnosticItems);
     }
 
     let reusedPage = false;
@@ -2340,6 +3100,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) {
+            throw new JevBrowserError("reuse_page found a different same-origin URL; add a navigate step or set continue_from_current_page: false");
+          }
         }
       }
     }
@@ -2360,18 +3123,33 @@ 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,
-          `interactive ${control.role} has no accessible name; index ${control.index}; nearest label ${JSON.stringify(control.nearest_label)}; inspect HTML ${control.html}`,
+          result.warnings,
+          `interactive ${control.role} has no accessible name; index ${control.index}; nearest label ${JSON.stringify(control.nearest_label)}; HTML is available in unnamed_controls_initial/final`,
           settings.jev.maxDiagnosticItems,
         );
       }
       timings.readyMs = readiness.readyMs;
       browserPool.setNavigationError?.(null);
+      if (continuation) {
+        const currentFingerprint = await pageFingerprint(page);
+        if (continuation.pageFingerprint !== currentFingerprint) {
+          throw new JevBrowserError("the page structure or route 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 +3164,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();
@@ -2398,7 +3178,7 @@ export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, ca
         const decisionFlow = redact(`${requestedFlow}\nExpected outcome: ${outcome}`, secrets);
         const { request, criteria } = buildChoicePayload({
           flow: decisionFlow,
-          pageSnapshot: redact(result.final_snapshot, contentSecrets),
+          pageSnapshot: providerSafeSnapshot(result.final_snapshot, [...secrets, ...contentSecrets]),
           actions: descriptions,
           answerName: "browser_plan",
           allowComplete: options.stopOnExpected,
@@ -2422,44 +3202,99 @@ 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)
+        const runAllSteps = plan.steps.some(({ action, expectDownload }) => action.startsWith("assert_")
+          || ["navigate", "clear", "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 };
+          try {
+            step = interpolateStep(templateStep, variables);
+            step.timeoutMs ??= options.stepTimeoutMs;
+            const stepPage = step.targetPage === "popup" ? popupPage : page;
+            if (step.targetPage === "popup" && (!popupPage || popupPage.isClosed())) {
+              throw new JevBrowserError("target_page popup requires a preceding click with expect_popup: true");
+            }
+            activePage = stepPage;
+            const mutationInspection = await inferTargetMutation(stepPage, step, snapshot, settings, secrets);
+            const dynamicallyMutating = mutationInspection.mutating;
+            const pairedNativeConfirmation = step.action === "confirm_dialog" && nativeDialog.result?.matched === true;
+            if (dynamicallyMutating && !pairedNativeConfirmation && index !== approvedMutationIndex
+              && !(options.allowMutations && !options.dryRun)) {
+              mutationStop = { step: String(index + 1), action: step.action };
+              const enriched = await enrichSnapshot(stepPage, 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),
+                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);
-            const actionMarker = networkTracker.mark();
-            const traceStep = await executeStep(page, step, settings, snapshot, secrets, downloadLedger, {
-              networkTracker,
-              networkMarker,
-              variables,
-            });
+            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 execution = {
+              networkTracker,
+              networkMarker,
+              autoAngularIdle: options.autoAngularIdle,
+              readyStableMs: options.readyStableMs,
+              allowMutations: options.allowMutations,
+              browserPool,
+              nativeDialog,
+              preResolvedTarget: mutationInspection.target,
+              popupPage,
+              variables,
+            };
+            const traceStep = await executeStep(stepPage, step, settings, snapshot, secrets, downloadLedger, execution);
+            popupPage = execution.popupPage;
+            if (options.autoAngularIdle && ["click", "type"].includes(step.action)) {
+              await waitForAngularIdle(stepPage, 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;
             }
             traceStep.step = String(index + 1);
             traceStep.status = "passed";
             if (step.mutating === true) traceStep.mutating = true;
-            if (step.screenshot === true) {
-              try {
-                traceStep.screenshot_path = await artifactPath(settings, "png");
-                await page.screenshot({ path: traceStep.screenshot_path, fullPage: false });
+            if (step.screenshot === true && !secretBearingFlow) {
+              try {
+                traceStep.screenshot_path = await artifactPath(settings, "png");
+                await stepPage.screenshot({ path: traceStep.screenshot_path, fullPage: false });
               } catch {
                 delete traceStep.screenshot_path;
                 artifactErrors.push(`step ${index + 1} screenshot could not be saved`);
@@ -2468,14 +3303,14 @@ export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, ca
             traceStep.duration_ms = Math.round((performance.now() - stepStarted) * 10) / 10;
             trace.push(traceStep);
             if (traceStep.downloaded_file) result.downloaded_files.push(traceStep.downloaded_file);
-            if (traceStep.accessibility_audit) {
-              result.accessibility_audits.push(traceStep.accessibility_audit);
-              if (traceStep.accessibility_audit.violations_count > 0) {
-                failure = `accessibility audit reported ${traceStep.accessibility_audit.violations_count} violation(s)`;
+            if (traceStep.accessibility_audit) {
+              result.accessibility_audits.push(traceStep.accessibility_audit);
+              if (traceStep.accessibility_audit.blocking_violations_count > 0) {
+                failure = `accessibility audit reported ${traceStep.accessibility_audit.blocking_violations_count} violation(s) at or above ${traceStep.accessibility_audit.fail_on_impact} impact`;
               }
             }
-            snapshot = await snapshotAfterStep(
-              page,
+            snapshot = await snapshotAfterStep(
+              stepPage,
               settings,
               secrets,
               options.snapshotScope,
@@ -2504,9 +3339,9 @@ export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, ca
             break;
           }
         }
-        if (failure || trace.length === 0) {
-          snapshot = await snapshotAfterStep(
-            page,
+        if (failure || trace.length === 0) {
+          snapshot = await snapshotAfterStep(
+            activePage,
             settings,
             secrets,
             options.snapshotScope,
@@ -2516,8 +3351,8 @@ export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, ca
             options.snapshotIncludeHidden,
           );
         }
-        const finalDetails = await enrichSnapshot(
-          page,
+        const finalDetails = await enrichSnapshot(
+          activePage,
           snapshot,
           settings,
           secrets,
@@ -2532,24 +3367,26 @@ export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, ca
         const assertionCount = plan.steps.filter(({ action }) => action.startsWith("assert_")).length;
         const assertionsPassed = assertionCount > 0 && !failure && trace.length === plan.steps.length;
         const auditCount = plan.steps.filter(({ action }) => action === "audit_accessibility").length;
-        const auditsPassed = auditCount > 0 && !failure && result.accessibility_audits.length === auditCount
-          && result.accessibility_audits.every(({ violations_count: count }) => count === 0)
+        const auditsPassed = auditCount > 0 && !failure && result.accessibility_audits.length === auditCount
+          && result.accessibility_audits.every(({ blocking_violations_count: count }) => count === 0)
           && trace.length === plan.steps.length;
         const expectedDownloadCount = plan.steps.filter(({ action, expectDownload }) => action === "click" && expectDownload).length;
         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 +3418,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
@@ -2610,12 +3449,13 @@ export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, ca
     } catch {
       // Keep the last accessible snapshot when the page is closing or unavailable.
     }
-  } finally {
-    if (tracingStarted) {
-      try {
-        if (result.status !== "passed" && options.traceOnFailure) {
-          tracePath = await artifactPath(settings, "zip");
-          await context.tracing.stop({ path: tracePath });
+  } finally {
+    if (tracingStarted) {
+      try {
+        if ((result.status !== "passed" && options.traceOnFailure)
+          || (result.status === "passed" && options.traceOnSuccess)) {
+          tracePath = await artifactPath(settings, "zip");
+          await context.tracing.stop({ path: tracePath });
         } else {
           await context.tracing.stop();
         }
@@ -2623,15 +3463,34 @@ export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, ca
         artifactErrors.push("trace recording could not be saved");
       }
     }
-    if (result.status !== "passed" && options.screenshotOnFailure) {
-      try {
-        result.screenshot_path = await artifactPath(settings, "png");
-        await page.screenshot({ path: result.screenshot_path, fullPage: false });
-      } catch {
+    const shouldScreenshot = result.status === "passed" ? options.screenshotOnSuccess : options.screenshotOnFailure;
+    if (shouldScreenshot && !secretBearingFlow) {
+      try {
+        result.screenshot_path = await artifactPath(settings, "png");
+        await activePage.screenshot({ path: result.screenshot_path, fullPage: false });
+      } catch {
         delete result.screenshot_path;
-        artifactErrors.push("failure screenshot could not be saved");
-      }
-    }
+        artifactErrors.push("failure screenshot could not be saved");
+      }
+    }
+    const metrics = await collectPerformanceMetrics(activePage);
+    if (metrics) result.performance_metrics = metrics;
+    if (options.recordVideo && !secretBearingFlow) {
+      try {
+        const video = activePage.video?.();
+        if (!video) throw new Error("video capture was unavailable");
+        result.video_path = await artifactPath(settings, "webm");
+        await activePage.close();
+        await video.saveAs(result.video_path);
+        const nextContextOptions = { ...sessionConfiguration.contextOptions };
+        delete nextContextOptions.recordVideo;
+        await browserPool.getPage?.({ contextOptions: nextContextOptions, launchArgs: sessionConfiguration.launchArgs });
+      } catch {
+        delete result.video_path;
+        artifactErrors.push("video recording could not be saved");
+      }
+    }
+    if (popupPage && !popupPage.isClosed()) await popupPage.close().catch(() => {});
     try {
       await unroute?.();
     } catch {
@@ -2639,16 +3498,22 @@ 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 = groupConsoleErrors([...(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);
+  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 {
@@ -2660,7 +3525,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);
 }