@diegosouzacdv/jev-browser-mcp 0.6.1 → 0.6.2

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

@@ -6,8 +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", "checkbox", "radio", "cell", "gridcell", "option"]);
-const CHECK_ROLES = new Set(["checkbox", "radio"]);
+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"]);
@@ -16,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", "check", "uncheck", "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"],
@@ -39,10 +39,11 @@ 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",
-  "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",
+  "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",
 ]);
@@ -188,12 +189,14 @@ export function validateCandidatePlans(candidatePlans, settings, maxFlowSteps =
       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", "expect_popup", "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"] },
@@ -201,8 +204,8 @@ export function validateCandidatePlans(candidatePlans, settings, maxFlowSteps =
         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"] },
@@ -214,12 +217,12 @@ export function validateCandidatePlans(candidatePlans, settings, maxFlowSteps =
         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"]) {
@@ -255,7 +258,7 @@ export function validateCandidatePlans(candidatePlans, settings, maxFlowSteps =
         }
         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) {
@@ -264,8 +267,27 @@ export function validateCandidatePlans(candidatePlans, settings, maxFlowSteps =
         } 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) {
@@ -354,7 +376,7 @@ export function validateCandidatePlans(candidatePlans, settings, maxFlowSteps =
         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 (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");
         }
@@ -362,10 +384,19 @@ export function validateCandidatePlans(candidatePlans, settings, maxFlowSteps =
         step.toggleSelector = rawStep.toggle_selector === undefined
           ? "#open_btn"
           : requiredText(rawStep.toggle_selector, "toggle_selector", settings.jev.maxActionDescriptionChars);
-      }
-      if (action === "type") {
-        if (typeof rawStep.text !== "string" || rawStep.text.length === 0) throw new JevBrowserError("type step needs non-empty text");
-        if (rawStep.text.length > settings.browser.maxTextEntryChars) throw new JevBrowserError("type text exceeds the configured character limit");
+      }
+      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");
         }
@@ -374,11 +405,16 @@ export function validateCandidatePlans(candidatePlans, settings, maxFlowSteps =
         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) {
@@ -435,9 +471,9 @@ export function validateCandidatePlans(candidatePlans, settings, maxFlowSteps =
         }
         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") {
@@ -456,26 +492,40 @@ export function validateCandidatePlans(candidatePlans, settings, maxFlowSteps =
           }
           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)) {
@@ -554,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");
@@ -563,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",
-    "auto_angular_idle", "block_fonts", "continue_from_current_page", "dry_run", "fast_path", "local_only",
-    "ready_network_idle", "reuse_page", "screenshot_on_failure", "snapshot_include_hidden", "stop_on_expected", "trace_on_failure",
+  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") {
@@ -592,9 +643,60 @@ function resolveFlowOptions(rawOptions, settings) {
     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 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 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);
@@ -604,7 +706,7 @@ function resolveFlowOptions(rawOptions, settings) {
     || 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");
@@ -621,7 +723,8 @@ 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,
@@ -633,7 +736,19 @@ function resolveFlowOptions(rawOptions, settings) {
     fastPath: rawOptions.fast_path ?? defaults.fastPath,
     localOnly: rawOptions.local_only ?? defaults.localOnly,
     loginText: Object.freeze(loginText),
-    loginUrlContains: Object.freeze(loginUrlContains),
+    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,
@@ -676,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;
@@ -748,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()) {
@@ -1018,70 +1232,86 @@ function containsExpectedOutcome(snapshot, phrase) {
   return containsPhrase(expectedOutcomeText(snapshot), phrase);
 }
 
-function createNetworkTracker(page, settings, loginUrlContains = []) {
-  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) => {
       if (entry.sequence <= marker || entry.type !== "response" || ![401, 403].includes(entry.status)) return false;
       return loginUrlContains.some((needle) => entry.url.toLocaleLowerCase().includes(needle.toLocaleLowerCase()));
     }),
-    activeFor: (urlContains) => [...active.values()].filter((entry) => entry.url.includes(urlContains)),
-    dispose: () => {
-      page.off("request", onRequest);
-      page.off("response", onResponse);
-      page.off("requestfinished", onFinished);
-      page.off("requestfailed", onFailed);
-      active.clear();
-      history.length = 0;
+    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, optional = false) {
@@ -1123,7 +1353,7 @@ async function waitForAngularIdle(page, timeout, settings, optional = 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 {
@@ -1222,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) => {
@@ -1242,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) {
@@ -1251,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, 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))));
@@ -1282,8 +1547,12 @@ async function waitForPageReady(page, options, settings, secrets, continued = fa
 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.
   }
@@ -1322,29 +1591,45 @@ async function waitForText(locator, expected, timeout, description, settings) {
   throw new JevBrowserError(`${description} did not contain the expected text within ${timeout}ms`);
 }
 
-async function pageFingerprint(page, snapshot) {
-  let controls = [];
-  let visibleText = "";
-  try {
-    ({ controls, visibleText } = await page.evaluate(() => ({
-      visibleText: String(document.body?.innerText || "").slice(0, 30000),
-      controls: [...document.querySelectorAll("input,textarea,select")].slice(0, 1000).map((element) => ({
-        tag: element.localName,
-        type: element.getAttribute("type") || "",
-        name: element.getAttribute("name") || "",
-        id: element.id || "",
-        value: String(element.value ?? "").slice(0, 4000),
-        checked: "checked" in element ? Boolean(element.checked) : undefined,
-        disabled: Boolean(element.disabled),
-      })),
-    })));
-  } catch {
-    // The page may close between a browser event and an authorization check.
-  }
-  return createHash("sha256").update(JSON.stringify({
-    url: typeof page.url === "function" ? page.url() : "unavailable", snapshot, visibleText, controls,
-  })).digest("hex");
-}
+async function 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 });
@@ -1549,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 = {
@@ -1614,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");
@@ -1966,9 +2280,22 @@ async function navigateMenu(page, root, step, settings, execution) {
   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;
+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,
@@ -2046,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") {
@@ -2085,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") {
@@ -2154,35 +2485,33 @@ async function executeStep(page, step, settings, snapshot, secrets, downloadLedg
   }
   if (step.action === "click") {
     const resolvedTarget = await describeResolvedTarget(control, step, secrets, settings);
-    if (step.expectPopup) {
-      let popup;
-      try {
-        [popup] = await Promise.all([
-          page.waitForEvent("popup", { timeout: settings.browser.downloadTimeoutMs }),
-          control.click({ timeout }),
-        ]);
-      } catch {
-        throw new JevBrowserError("click did not open the expected popup before the configured timeout");
-      }
-      try {
-        await popup.waitForLoadState("domcontentloaded", { timeout: settings.browser.downloadTimeoutMs }).catch(() => {});
-        const popupUrl = popup.url();
-        const popupTitle = await popup.title().catch(() => "");
-        const isPdf = /\.pdf(?:$|[?#])/i.test(popupUrl)
-          || await popup.locator('embed[type="application/pdf"], iframe[src*=".pdf" i]').count().then((count) => count > 0).catch(() => false);
-        return {
-          action: step.action,
-          ...targetEvidence(step, secrets, resolvedTarget),
-          popup_url: evidenceUrl(popupUrl, secrets, settings.jev.maxDiagnosticChars),
-          ...(popupTitle ? { popup_title: redact(popupTitle, secrets).slice(0, settings.jev.maxDiagnosticChars) } : {}),
-          popup_document_type: isPdf ? "pdf" : "page",
-        };
-      } finally {
-        await popup.close().catch(() => {});
-      }
-    }
-    if (!step.expectDownload) {
-      await control.click({ timeout });
+    if (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))}`);
       }
@@ -2203,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 });
@@ -2228,7 +2557,12 @@ 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);
     if (step.optionMatch === "value") {
@@ -2310,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 {
@@ -2335,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(
@@ -2470,13 +2820,14 @@ function trackerUrl(url, settings) {
   return settings.browser.trackerHostSuffixes.some((suffix) => hostname === suffix || hostname.endsWith(`.${suffix}`));
 }
 
-async function installTrackerBlocking(context, settings, enabled, blockFonts = false) {
+async function installTrackerBlocking(context, settings, enabled, blockFonts = false, allowMedia = false) {
   if (!enabled && !blockFonts) return undefined;
   const handler = async (route) => {
     const request = route.request();
     const resourceType = request.resourceType();
     if ((enabled && trackerUrl(request.url(), settings))
-      || (enabled && settings.browser.blockedResourceTypes.includes(resourceType) && (resourceType !== "font" || blockFonts))
+      || (enabled && settings.browser.blockedResourceTypes.includes(resourceType)
+        && (resourceType !== "font" || blockFonts) && (resourceType !== "media" || !allowMedia))
       || (blockFonts && resourceType === "font")) {
       await route.abort("blockedbyclient");
       return;
@@ -2563,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),
     ])));
   }
@@ -2599,7 +2970,7 @@ function snapshotDiff(initialSnapshot, finalSnapshot) {
   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 }) {
+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");
   let variables = validateParams(rawParams, settings);
   const requestedFlow = replaceKnownParams(flow, variables).trim();
@@ -2608,20 +2979,29 @@ export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, ca
   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 options = resolveFlowOptions(rawOptions, settings);
-  const plans = validateCandidatePlans(replaceKnownParams(candidatePlans, variables), settings, options.maxFlowSteps);
-  if (options.localOnly && Object.keys(plans).length > 0 && !(options.fastPath && Object.keys(plans).length === 1)) {
-    throw new JevBrowserError("local_only does not call Jev; provide exactly one candidate plan and enable fast_path");
-  }
+  const 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;
@@ -2642,7 +3022,8 @@ export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, ca
     warnings: continuation?.warnings || [],
     final_snapshot: "",
   };
-  result.snapshot_mode = options.returnSnapshot;
+  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, options.loginUrlContains);
   const initialNetworkMarker = networkTracker.mark();
@@ -2650,9 +3031,11 @@ export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, ca
   let unroute;
   let tracingStarted = false;
   let tracePath;
-  const artifactErrors = [];
-  let navigationError;
-  let initialSnapshot = "";
+  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;
@@ -2678,14 +3061,22 @@ export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, ca
   try {
     page.setDefaultTimeout(settings.browser.actionTimeoutMs);
     context.setDefaultTimeout(settings.browser.actionTimeoutMs);
-    unroute = await installTrackerBlocking(context, settings, options.blockTrackers, options.blockFonts);
-    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;
@@ -2709,8 +3100,8 @@ export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, ca
         } else {
           reusedPage = true;
           result.navigation_strategy = "continued_current_page";
-          if (new URL(currentUrl).href !== new URL(url).href) {
-            addDiagnostic(result.warnings, "initial_url differs from the current same-origin URL; continued from the current page", settings.jev.maxDiagnosticItems);
+          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");
           }
         }
       }
@@ -2742,18 +3133,17 @@ export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, ca
       }
       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 currentUrl = typeof page.url === "function" ? page.url() : "unavailable";
-        const currentFingerprint = await pageFingerprint(page, result.final_snapshot);
-        if (continuation.pageUrl !== currentUrl || continuation.pageFingerprint !== currentFingerprint) {
-          throw new JevBrowserError("the page changed after dry_run; run dry_run again before confirming a mutation");
+        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");
@@ -2788,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,
@@ -2824,23 +3214,29 @@ export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, ca
         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);
         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);
-            step.timeoutMs ??= options.stepTimeoutMs;
-            const mutationInspection = await inferTargetMutation(page, step, snapshot, settings, secrets);
+          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) {
+            if (dynamicallyMutating && !pairedNativeConfirmation && index !== approvedMutationIndex
+              && !(options.allowMutations && !options.dryRun)) {
               mutationStop = { step: String(index + 1), action: step.action };
-              const enriched = await enrichSnapshot(page, snapshot, settings, secrets, options.snapshotScope, options.snapshotIncludeHidden);
+              const enriched = await enrichSnapshot(stepPage, snapshot, settings, secrets, options.snapshotScope, options.snapshotIncludeHidden);
               snapshot = enriched.snapshot;
               issuedToken = mutationAuthorizationStore.issue({
                 fingerprint,
@@ -2851,7 +3247,7 @@ export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, ca
                 snapshot,
                 initialSnapshot,
                 pageUrl: typeof page.url === "function" ? page.url() : "unavailable",
-                pageFingerprint: await pageFingerprint(page, snapshot),
+                pageFingerprint: await pageFingerprint(page),
                 downloadedFiles: [...result.downloaded_files],
                 accessibilityAudits: [...result.accessibility_audits],
                 warnings: [...result.warnings],
@@ -2871,17 +3267,23 @@ export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, ca
               nativeDialog.expectedStep = undefined;
               nativeDialog.result = undefined;
             }
-            const actionMarker = networkTracker.mark();
-            const traceStep = await executeStep(page, step, settings, snapshot, secrets, downloadLedger, {
-              networkTracker,
-              networkMarker,
-              autoAngularIdle: options.autoAngularIdle,
-              nativeDialog,
-              preResolvedTarget: mutationInspection.target,
-              variables,
-            });
-            if (options.autoAngularIdle && ["click", "type"].includes(step.action)) {
-              await waitForAngularIdle(page, step.timeoutMs ?? options.stepTimeoutMs, settings, true);
+            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;
@@ -2889,10 +3291,10 @@ export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, ca
             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`);
@@ -2901,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,
@@ -2937,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,
@@ -2949,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,
@@ -2965,8 +3367,8 @@ 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
@@ -3047,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();
         }
@@ -3060,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 {
@@ -3080,13 +3502,13 @@ export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, ca
   }
   if (tracePath) result.trace_path = tracePath;
   if (artifactErrors.length) result.artifact_errors = artifactErrors;
-  result.console_errors = [...(continuation?.consoleErrors || []), ...capture.diagnostics.console_errors];
+  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);