@diegosouzacdv/jev-browser-mcp 0.4.1 → 0.5.0

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

@@ -1,5 +1,5 @@
 import { randomUUID } from "node:crypto";
-import { mkdir, readFile, realpath, rm, stat } from "node:fs/promises";
+import { lstat, mkdir, readFile, realpath, rm, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { ACCESSIBILITY_STANDARDS, runAccessibilityAudit } from "./accessibility.mjs";
 import { JevBrowserError } from "./config.mjs";
@@ -17,16 +17,17 @@ const CONTAINER_ROLES = new Set([
 ]);
 const TARGET_SELECTION_ACTIONS = new Set([
   "click", "type", "select_option", "hover", "press", "assert_text", "assert_value",
-  "assert_visible", "assert_hidden", "upload_file",
+  "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([
+const ASSERT_ROLES = new Set([
   "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", "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",
@@ -38,7 +39,8 @@ const MIME_TYPES = new Map([
 ]);
 const FLOW_OPTION_KEYS = new Set([
   "block_trackers", "capture_console_errors", "capture_network_error_bodies", "capture_network_errors",
-  "fast_path", "ready_network_idle", "ready_stable_ms", "ready_text", "ready_timeout_seconds",
+  "dry_run", "fast_path", "ready_network_idle", "ready_stable_ms", "ready_text", "ready_timeout_seconds",
+  "report_path",
   "reuse_page", "screenshot_on_failure", "snapshot_include_hidden", "snapshot_scope", "stop_on_expected",
   "trace_on_failure",
 ]);
@@ -70,8 +72,44 @@ function requiredText(value, field, limit) {
 function hasLocatorField(step) {
   return TARGET_LOCATOR_FIELDS.some((field) => step[LOCATOR_STEP_KEYS[field]] !== undefined);
 }
-
-export function validateCandidatePlans(candidatePlans, settings) {
+
+function validateParams(rawParams, settings) {
+  if (rawParams === undefined) return {};
+  if (!isRecord(rawParams) || Object.keys(rawParams).length > settings.browser.maxFlowSteps * 4) {
+    throw new JevBrowserError("params must be a bounded object of scalar values");
+  }
+  return Object.fromEntries(Object.entries(rawParams).map(([name, value]) => {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name) || !["string", "number", "boolean"].includes(typeof value)) {
+      throw new JevBrowserError("params keys must be simple variable names and values must be text, numbers, or booleans");
+    }
+    const text = String(value);
+    if (text.length > settings.browser.maxTextEntryChars) throw new JevBrowserError(`params.${name} exceeds the configured character limit`);
+    return [name, text];
+  }));
+}
+
+function replaceKnownParams(value, params) {
+  if (typeof value === "string") {
+    return value.replace(/\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (placeholder, name) => Object.hasOwn(params, name) ? params[name] : placeholder);
+  }
+  if (Array.isArray(value)) return value.map((item) => replaceKnownParams(item, params));
+  if (isRecord(value)) return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, replaceKnownParams(item, params)]));
+  return value;
+}
+
+function interpolateStep(value, variables) {
+  if (typeof value === "string") {
+    return value.replace(/\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (_placeholder, name) => {
+      if (!Object.hasOwn(variables, name)) throw new JevBrowserError(`step references {${name}} before it has been supplied or extracted`);
+      return variables[name];
+    });
+  }
+  if (Array.isArray(value)) return value.map((item) => interpolateStep(item, variables));
+  if (isRecord(value)) return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, interpolateStep(item, variables)]));
+  return value;
+}
+
+export function validateCandidatePlans(candidatePlans, settings) {
   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");
@@ -102,7 +140,10 @@ export function validateCandidatePlans(candidatePlans, settings) {
       const schemas = {
         click: { required: [], optional: [...semanticTarget, "expect_download", "timeout_seconds"] },
         type: { required: ["text"], optional: [...semanticTarget, "blur", "mode", "sensitive", "timeout_seconds"] },
-        wait_for_text: { required: ["text"], optional: ["frame", "comment", "timeout_seconds"] },
+        confirm_dialog: { required: ["expected_text", "button"], optional: ["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_for_text: { required: ["text"], optional: ["frame", "comment", "fail_on", "timeout_seconds"] },
         wait_for_condition: { required: ["condition"], optional: [...semanticTarget, "url_contains", "timeout_seconds"] },
         press: { required: ["key"], optional: [...semanticTarget, "timeout_seconds"] },
         select_option: { required: ["option"], optional: [...semanticTarget, "timeout_seconds"] },
@@ -117,9 +158,15 @@ export function validateCandidatePlans(candidatePlans, settings) {
         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");
-      exactKeys(rawStep, ["action", ...schemas[action].required], schemas[action].optional, action);
+      exactKeys(rawStep, ["action", ...schemas[action].required], [...schemas[action].optional, "mutating", "screenshot"], action);
 
       const step = { action };
+      for (const field of ["mutating", "screenshot"]) {
+        if (rawStep[field] !== undefined && typeof rawStep[field] !== "boolean") {
+          throw new JevBrowserError(`${action} ${field} must be a boolean`);
+        }
+        if (rawStep[field] !== undefined) step[field] = rawStep[field];
+      }
       const selectorFields = locatorFields.filter((field) => rawStep[field] !== undefined);
       const hasNear = rawStep.near !== undefined;
       if (selectorFields.length + Number(hasNear) > 1) {
@@ -185,9 +232,13 @@ 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) {
-          exactKeys(rawStep.within, ["row_containing"], [], "within");
-          step.within = { rowContaining: requiredText(rawStep.within.row_containing, "within row text", settings.jev.maxActionDescriptionChars) };
+        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)) {
@@ -232,9 +283,53 @@ export function validateCandidatePlans(candidatePlans, settings) {
         step.blur = rawStep.blur ?? false;
         step.sensitive = rawStep.sensitive ?? true;
       }
-      if (action === "wait_for_text") {
-        step.text = requiredText(rawStep.text, "wait text", settings.jev.maxActionDescriptionChars);
-      }
+      if (action === "wait_for_text") {
+        step.text = requiredText(rawStep.text, "wait text", settings.jev.maxActionDescriptionChars);
+        if (rawStep.fail_on !== undefined) {
+          if (!isRecord(rawStep.fail_on)) throw new JevBrowserError("wait_for_text fail_on must be an object with a role");
+          exactKeys(rawStep.fail_on, ["role"], ["name"], "wait_for_text fail_on");
+          if (typeof rawStep.fail_on.role !== "string" || !ASSERT_ROLES.has(rawStep.fail_on.role)) {
+            throw new JevBrowserError(`wait_for_text fail_on role must be one of: ${[...ASSERT_ROLES].join(", ")}`);
+          }
+          step.failOn = { role: rawStep.fail_on.role };
+          if (rawStep.fail_on.name !== undefined) {
+            step.failOn.name = requiredText(rawStep.fail_on.name, "fail_on accessible name", settings.jev.maxActionDescriptionChars);
+          }
+        }
+      }
+      if (action === "confirm_dialog") {
+        step.expectedText = requiredText(rawStep.expected_text, "expected dialog text", settings.jev.maxActionDescriptionChars);
+        step.button = requiredText(rawStep.button, "confirmation button", settings.jev.maxActionDescriptionChars);
+      }
+      if (action === "assert_network") {
+        step.urlContains = requiredText(rawStep.url_contains, "url_contains", settings.jev.maxActionDescriptionChars);
+        step.method = requiredText(rawStep.method, "network method", 16).toUpperCase();
+        if (!/^[A-Z]+$/.test(step.method)) throw new JevBrowserError("assert_network method must contain letters only");
+        if (!Number.isSafeInteger(rawStep.status) || rawStep.status < 100 || rawStep.status > 599) {
+          throw new JevBrowserError("assert_network status must be an HTTP status from 100 to 599");
+        }
+        step.status = rawStep.status;
+        if (rawStep.message_contains !== undefined) {
+          step.messageContains = requiredText(rawStep.message_contains, "network message", settings.browser.maxNetworkErrorMessageChars);
+        }
+      }
+      if (action === "extract") {
+        step.as = requiredText(rawStep.as, "extract variable name", 64);
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(step.as)) throw new JevBrowserError("extract as must be a simple variable name");
+        step.source = rawStep.source ?? "text";
+        if (!new Set(["text", "value", "attribute"]).has(step.source)) {
+          throw new JevBrowserError("extract source must be text, value, or attribute");
+        }
+        if (step.source === "attribute") {
+          step.attribute = requiredText(rawStep.attribute, "extract attribute", 128);
+        } else if (rawStep.attribute !== undefined) {
+          throw new JevBrowserError("extract attribute is only supported when source is attribute");
+        }
+        if (rawStep.sensitive !== undefined && typeof rawStep.sensitive !== "boolean") {
+          throw new JevBrowserError("extract sensitive must be a boolean");
+        }
+        step.sensitive = rawStep.sensitive ?? true;
+      }
       if (action === "wait_for_condition") {
         if (!new Set(["network_idle", "hidden", "text_hidden"]).has(rawStep.condition)) {
           throw new JevBrowserError("wait_for_condition condition must be network_idle, hidden, or text_hidden");
@@ -349,14 +444,14 @@ 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");
   }
   const booleanOptions = [
     "block_trackers", "capture_console_errors", "capture_network_error_bodies", "capture_network_errors",
-    "fast_path", "ready_network_idle", "reuse_page", "screenshot_on_failure", "snapshot_include_hidden",
+    "dry_run", "fast_path", "ready_network_idle", "reuse_page", "screenshot_on_failure", "snapshot_include_hidden",
     "stop_on_expected", "trace_on_failure",
   ];
   for (const key of booleanOptions) {
@@ -380,16 +475,27 @@ function resolveFlowOptions(rawOptions, settings) {
   const readyText = rawOptions.ready_text === undefined
     ? ""
     : requiredText(rawOptions.ready_text, "ready_text", settings.jev.maxActionDescriptionChars);
+  let reportPath;
+  if (rawOptions.report_path !== undefined) {
+    if (typeof rawOptions.report_path !== "string" || !path.isAbsolute(rawOptions.report_path)) {
+      throw new JevBrowserError("options.report_path must be an absolute path inside the configured artifact directory");
+    }
+    const extension = path.extname(rawOptions.report_path).toLowerCase();
+    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({
     blockTrackers: rawOptions.block_trackers ?? defaults.blockTrackers,
     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,
     readyTimeoutMs: Math.ceil(readyTimeoutSeconds * 1000),
     readyNetworkIdle: rawOptions.ready_network_idle ?? defaults.readyNetworkIdle,
     readyStableMs,
     readyText,
+    reportPath,
     reusePage: rawOptions.reuse_page ?? defaults.reusePage,
     screenshotOnFailure: rawOptions.screenshot_on_failure ?? defaults.screenshotOnFailure,
     snapshotIncludeHidden: rawOptions.snapshot_include_hidden ?? defaults.snapshotIncludeHidden,
@@ -569,6 +675,59 @@ async function snapshotPage(page, settings, secrets, snapshotScope = "body", { a
   return compactSnapshot(redact(combined, secrets), settings.jev.maxSnapshotChars);
 }
 
+async function collectUnnamedControls(root, roles, settings, secrets) {
+  const unnamedControls = [];
+  for (const role of roles) {
+    if (unnamedControls.length >= settings.jev.maxDiagnosticItems) break;
+    const locator = root.getByRole(role, { name: UNNAMED_ACCESSIBLE_NAME });
+    const controls = await locator.evaluateAll((elements, maxChars) => {
+      const textOf = (element) => (element?.innerText || element?.textContent || "").replace(/\s+/g, " ").trim();
+      const nearestLabel = (element) => {
+        const labels = [...element.ownerDocument.querySelectorAll("label")]
+          .filter((label) => label.compareDocumentPosition(element) & Node.DOCUMENT_POSITION_FOLLOWING).reverse();
+        for (const label of labels) {
+          const controlsBetween = [...element.ownerDocument.querySelectorAll("input,textarea,select,[role=textbox],[role=combobox]")]
+            .some((control) => (label.compareDocumentPosition(control) & Node.DOCUMENT_POSITION_FOLLOWING)
+              && (control.compareDocumentPosition(element) & Node.DOCUMENT_POSITION_FOLLOWING));
+          if (!controlsBetween) return textOf(label);
+        }
+        return "";
+      };
+      const allowedAttributes = new Set(["id", "name", "type", "title", "aria-label", "aria-labelledby", "placeholder", "role", "data-testid", "href", "alt", "disabled"]);
+      const safeHtml = (element) => {
+        const clone = element.cloneNode(true);
+        for (const node of [clone, ...clone.querySelectorAll("*")]) {
+          for (const attribute of [...node.attributes]) if (!allowedAttributes.has(attribute.name.toLowerCase())) node.removeAttribute(attribute.name);
+          if (node.matches("input,textarea")) {
+            node.removeAttribute("value");
+            if (node.matches("textarea")) node.textContent = "";
+          }
+        }
+        clone.querySelectorAll("script,style").forEach((node) => node.remove());
+        return clone.outerHTML.replace(/\s+/g, " ").slice(0, maxChars);
+      };
+      return elements.map((element, index) => ({
+        index,
+        disabled: Boolean(element.disabled || element.matches(":disabled") || element.getAttribute("aria-disabled") === "true"),
+        nearestLabel: nearestLabel(element),
+        html: safeHtml(element),
+      }));
+    }, settings.jev.maxDiagnosticChars);
+    for (const control of controls) {
+      if (control.disabled) continue;
+      unnamedControls.push({
+        role,
+        index: control.index,
+        name: "",
+        nearest_label: redact(control.nearestLabel, secrets),
+        html: redact(control.html, secrets),
+      });
+      if (unnamedControls.length >= settings.jev.maxDiagnosticItems) break;
+    }
+  }
+  return unnamedControls;
+}
+
 async function enrichSnapshot(page, snapshot, settings, secrets, snapshotScope, includeHidden) {
   let root;
   try {
@@ -603,6 +762,7 @@ async function enrichSnapshot(page, snapshot, settings, secrets, snapshotScope,
       };
       const accessibleName = (element) => element.getAttribute("aria-label") || referencedName(element)
         || [...(element.labels || [])].map(textOf).filter(Boolean).join(" ")
+        || (element.matches("input,textarea") ? element.getAttribute("placeholder") : "")
         || element.getAttribute("alt") || (element.matches("a,button,[role=button],[role=link],[role=menuitem]") ? textOf(element) : "")
         || element.getAttribute("title") || "";
       const sensitiveField = (element) => {
@@ -642,16 +802,21 @@ async function enrichSnapshot(page, snapshot, settings, secrets, snapshotScope,
         clone.querySelectorAll("script,style").forEach((node) => node.remove());
         return clone.outerHTML.replace(/\s+/g, " ").slice(0, limits.maxChars);
       };
-      const interactive = [...scope.querySelectorAll("a,button,input:not([type=hidden]),select,textarea,[role=button],[role=link],[role=menuitem]")]
-        .filter((element) => limits.includeHidden || isVisible(element));
-      const unnamed = interactive.filter((element) => !accessibleName(element).trim()).slice(0, limits.maxItems)
-        .map((element, index) => ({
-          role: element.getAttribute("role") || element.localName,
-          index,
-          nearestLabel: nearestLabel(element),
-          html: safeHtml(element),
-        }));
-      return { formLines, unnamed };
+      const roleForInteractive = (element) => {
+        const explicitRole = element.getAttribute("role");
+        if (explicitRole) return explicitRole;
+        if (element.matches("a[href]")) return "link";
+        if (element.matches("button,input[type=button],input[type=submit],input[type=reset]")) return "button";
+        if (element.matches("input[type=checkbox]")) return "checkbox";
+        if (element.matches("input[type=radio]")) return "radio";
+        if (element.matches("input[type=search]")) return "searchbox";
+        if (element.matches("input:not([type=hidden]),textarea")) return "textbox";
+        if (element.matches("select")) return element.multiple ? "listbox" : "combobox";
+        return "";
+      };
+      const interactive = [...scope.querySelectorAll("a,button,input:not([type=hidden]),select,textarea,[role=button],[role=link],[role=menuitem],[role=textbox],[role=searchbox],[role=combobox],[role=checkbox],[role=radio]")];
+      const interactiveRoles = [...new Set(interactive.map(roleForInteractive).filter(Boolean))];
+      return { formLines, interactiveRoles };
     }, {
       includeHidden,
       maxItems: settings.jev.maxDiagnosticItems,
@@ -659,16 +824,13 @@ async function enrichSnapshot(page, snapshot, settings, secrets, snapshotScope,
     });
     const sections = [];
     if (details.formLines.length) sections.push(`[form controls: ids, names, values (password/token fields redacted), disabled state and same-name index]\n${details.formLines.join("\n")}`);
-    if (details.unnamed.length) {
-      sections.push(`[interactive controls without accessible names]\n${details.unnamed.map(({ role, index, nearestLabel, html }) =>
-        `- ${role} index=${index}; nearest_label=${JSON.stringify(nearestLabel)}; html=${html}`).join("\n")}`);
+    const unnamedControls = typeof root.getByRole === "function"
+      ? await collectUnnamedControls(root, details.interactiveRoles, settings, secrets)
+      : [];
+    if (unnamedControls.length) {
+      sections.push(`[interactive controls without accessible names; indices match Playwright role/name locators, disabled controls omitted]\n${unnamedControls.map(({ role, index, nearest_label, html }) =>
+        `- ${role} name=${JSON.stringify("")} index=${index}; nearest_label=${JSON.stringify(nearest_label)}; html=${html}`).join("\n")}`);
     }
-    const unnamedControls = details.unnamed.map(({ role, index, nearestLabel, html }) => ({
-      role,
-      index,
-      nearest_label: redact(nearestLabel, secrets),
-      html: redact(html, secrets),
-    }));
     return {
       snapshot: compactSnapshot(redact([snapshot, ...sections].join("\n\n"), secrets), settings.jev.maxSnapshotChars),
       unnamedControls,
@@ -693,25 +855,35 @@ function createNetworkTracker(page, settings) {
   const history = [];
   let sequence = 0;
   const record = (type, request) => {
-    const entry = { sequence: ++sequence, type, url: request.url(), at: performance.now(), request };
+    const entry = { sequence: ++sequence, type, url: request.url(), method: request.method(), at: performance.now(), request };
     if (type === "request") active.set(request, entry);
-    else active.delete(request);
+    else if (type === "finished" || type === "failed") active.delete(request);
     history.push(entry);
     const historyLimit = settings.browser.maxFlowSteps * 8;
     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());
+    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)),
+    responsesSince: (marker, urlContains, method) => history.filter((entry) => entry.sequence > marker
+      && entry.type === "response" && entry.url.includes(urlContains) && entry.method === method),
     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();
@@ -740,6 +912,60 @@ async function waitForFilteredNetworkIdle(tracker, urlContains, marker, timeout,
   throw new JevBrowserError(`requests matching url_contains ${JSON.stringify(urlContains)} did not become idle within ${timeout}ms`);
 }
 
+async function networkResponseMessage(response, page, settings, secrets) {
+  try {
+    if (new URL(response.url()).origin !== new URL(page.url()).origin) {
+      throw new JevBrowserError("assert_network message checks are limited to same-origin responses");
+    }
+    await withTimeout(response.finished(), settings.browser.actionTimeoutMs, "network response did not finish before the assertion timeout");
+    const headers = await response.headers();
+    const declaredLength = Number(headers["content-length"]);
+    if (Number.isFinite(declaredLength) && declaredLength > settings.browser.maxNetworkErrorBodyBytes) {
+      throw new JevBrowserError("assert_network response body exceeds the configured capture limit");
+    }
+    const body = await withTimeout(response.body(), settings.browser.actionTimeoutMs, "network response body read timed out");
+    if (body.length > settings.browser.maxNetworkErrorBodyBytes) {
+      throw new JevBrowserError("assert_network response body exceeds the configured capture limit");
+    }
+    const text = body.toString("utf8");
+    try {
+      const payload = JSON.parse(text);
+      if (isRecord(payload) && typeof payload.message === "string") {
+        return sanitizeDiagnosticText(payload.message, secrets, settings.browser.maxNetworkErrorMessageChars);
+      }
+    } catch {
+      // Plain text responses remain useful to a bounded message_contains assertion.
+    }
+    return sanitizeDiagnosticText(text, secrets, settings.browser.maxNetworkErrorMessageChars);
+  } catch (error) {
+    if (error instanceof JevBrowserError) throw error;
+    throw new JevBrowserError("assert_network could not read the response message safely");
+  }
+}
+
+async function waitForNetworkAssertion(tracker, step, marker, timeout, page, settings, secrets) {
+  const started = performance.now();
+  while (performance.now() - started < timeout) {
+    const [entry] = tracker.responsesSince(marker, step.urlContains, step.method);
+    if (entry) {
+      if (entry.status !== step.status) {
+        throw new JevBrowserError(`assert_network expected ${step.method} ${JSON.stringify(redact(step.urlContains, secrets))} status ${step.status}, received ${entry.status}`);
+      }
+      const message = step.messageContains === undefined
+        ? undefined
+        : await networkResponseMessage(entry.response, page, settings, secrets);
+      if (message !== undefined && !message.toLocaleLowerCase().includes(step.messageContains.toLocaleLowerCase())) {
+        throw new JevBrowserError(`assert_network response message did not contain ${JSON.stringify(redact(step.messageContains, secrets))}`);
+      }
+      return { url: entry.url, method: entry.method, status: entry.status, ...(message !== undefined ? { message } : {}) };
+    }
+    const left = timeout - (performance.now() - started);
+    if (left <= 0) break;
+    await new Promise((resolve) => setTimeout(resolve, Math.min(settings.browser.visibilityPollMs, left)));
+  }
+  throw new JevBrowserError(`assert_network observed no ${step.method} response matching ${JSON.stringify(redact(step.urlContains, secrets))} within ${timeout}ms`);
+}
+
 async function waitForLocatorHidden(locator, timeout, description, settings, index) {
   const deadline = performance.now() + timeout;
   while (true) {
@@ -919,6 +1145,38 @@ function locatorAt(locator, index) {
   throw new JevBrowserError(`locator does not support occurrence index ${index}`);
 }
 
+async function firstVisibleMatch(locator) {
+  const count = await locator.count();
+  for (let index = 0; index < count; index += 1) {
+    const candidate = locatorAt(locator, index);
+    if (await isActuallyVisible(candidate)) return candidate;
+  }
+  return undefined;
+}
+
+async function waitForTextOrFailure(root, step, timeout, settings, secrets) {
+  const expected = root.getByText(step.text, { exact: false });
+  const failure = root.getByRole(step.failOn.role, roleOptions(step.failOn));
+  const deadline = performance.now() + timeout;
+  while (true) {
+    if (await firstVisibleMatch(expected)) return;
+    const failedMatch = await firstVisibleMatch(failure);
+    if (failedMatch) {
+      const visibleText = await failedMatch.innerText().catch(() => "");
+      const message = sanitizeDiagnosticText(visibleText || step.failOn.name || step.failOn.role, secrets, settings.jev.maxDiagnosticChars);
+      const failureTarget = `role ${step.failOn.role}${step.failOn.name ? ` ${JSON.stringify(redact(step.failOn.name, secrets))}` : ""}`;
+      throw new JevBrowserError(
+        `wait_for_text ${JSON.stringify(redact(step.text, secrets))} stopped because ${failureTarget} appeared: ${JSON.stringify(message)}`,
+      );
+    }
+    const left = deadline - performance.now();
+    if (left <= 0) {
+      throw new JevBrowserError(`text ${JSON.stringify(redact(step.text, secrets))} has no visible match within ${timeout}ms; ${step.failOn.role} did not appear`);
+    }
+    await new Promise((resolve) => setTimeout(resolve, Math.min(settings.browser.visibilityPollMs, left)));
+  }
+}
+
 async function visibleIndexes(locator, timeout, description, settings, { allowNone = false } = {}) {
   const deadline = performance.now() + timeout;
   while (true) {
@@ -947,6 +1205,9 @@ async function scopedRoot(root, within, timeout, settings) {
   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 {
     const options = within.name === undefined ? {} : { name: within.name, exact: true };
     locator = root.getByRole(within.role, options);
@@ -958,6 +1219,7 @@ async function scopedRoot(root, within, timeout, settings) {
 }
 
 function roleOptions(step) {
+  if (step.name === "") return { name: UNNAMED_ACCESSIBLE_NAME };
   return step.name === undefined ? {} : { name: step.name, exact: true };
 }
 
@@ -995,7 +1257,12 @@ async function targetLocator(root, step, timeout, settings) {
     locator = targetRoot.locator(step.selector);
   } else if (field === "label") {
     locator = targetRoot.getByLabel(step.label, { exact: true });
-    if (await locator.count() === 0) locator = relativeTarget(targetRoot.getByText(step.label, { exact: true }).first(), step.role);
+    if (await locator.count() === 0) {
+      step.matchStrategy = "label-proximity";
+      locator = relativeTarget(targetRoot.getByText(step.label, { exact: true }).first(), step.role);
+    } else {
+      step.matchStrategy = "label";
+    }
   } else if (field === "placeholder") {
     locator = targetRoot.getByPlaceholder(step.placeholder, { exact: true });
   } else if (field === "title") {
@@ -1027,11 +1294,79 @@ async function targetLocator(root, step, timeout, settings) {
 }
 
 function describeTarget(step, secrets) {
-  if (step.role) return `role ${step.role}${step.name === undefined ? "" : ` ${JSON.stringify(redact(step.name, secrets))}`}`;
-  const field = TARGET_LOCATOR_FIELDS.find((candidate) => step[LOCATOR_STEP_KEYS[candidate]] !== undefined);
-  if (field) return `${field} ${JSON.stringify(redact(step[LOCATOR_STEP_KEYS[field]], secrets))}`;
-  if (step.near) return `target near text ${JSON.stringify(redact(step.near.text, secrets))}`;
-  return "focused element";
+  const parts = [];
+  if (step.role) {
+    const name = step.name === undefined ? "" : ` ${JSON.stringify(redact(step.name, secrets))}`;
+    parts.push(`role ${step.role}${name}`);
+  }
+  for (const field of TARGET_LOCATOR_FIELDS) {
+    const value = step[LOCATOR_STEP_KEYS[field]];
+    if (value !== undefined) parts.push(`${field} ${JSON.stringify(redact(value, 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.index !== undefined) parts.push(`index ${step.index}`);
+  return parts.length ? parts.join(" + ") : "focused element";
+}
+
+async function describeResolvedTarget(locator, step, secrets, settings) {
+  if (typeof locator?.evaluate !== "function") return undefined;
+  try {
+    const includeValue = step.action === "type" && step.sensitive === false;
+    const resolved = await locator.evaluate((element, options) => {
+      const textOf = (node) => (node?.innerText || node?.textContent || "").replace(/\s+/g, " ").trim();
+      const referenced = (element.getAttribute("aria-labelledby") || "").trim().split(/\s+/).filter(Boolean)
+        .map((id) => textOf(element.ownerDocument.getElementById(id))).filter(Boolean).join(" ");
+      const labels = [...(element.labels || [])].map(textOf).filter(Boolean).join(" ");
+      const controlPlaceholder = element.matches("input,textarea,select") ? element.getAttribute("placeholder") || "" : "";
+      const textAlternative = element.matches("a,button,[role=button],[role=link],[role=menuitem]") ? textOf(element) : "";
+      const role = element.getAttribute("role")
+        || (element.matches("a[href]") ? "link"
+          : element.matches("button,input[type=button],input[type=submit],input[type=reset]") ? "button"
+            : element.matches("input[type=checkbox]") ? "checkbox"
+              : element.matches("input[type=radio]") ? "radio"
+                : element.matches("input[type=search]") ? "searchbox"
+                  : element.matches("select") ? "combobox"
+                    : element.matches("input,textarea") ? "textbox" : "");
+      const result = {
+        tag: element.localName,
+        id: element.id || "",
+        role,
+        accessible_name: element.getAttribute("aria-label") || referenced || labels || controlPlaceholder
+          || element.getAttribute("alt") || textAlternative || element.getAttribute("title") || "",
+        title: options.matchedTitle || element.getAttribute("title") || "",
+        href: element.matches("a[href]") ? element.href : element.getAttribute("href") || "",
+      };
+      if (options.includeFieldValue && "value" in element) result.value = String(element.value ?? "");
+      return result;
+    }, { includeFieldValue: includeValue, matchedTitle: step.title || "" });
+    if (step.role) resolved.role = step.role;
+    if (step.matchStrategy) resolved.match_strategy = step.matchStrategy;
+    resolved.id = redact(resolved.id, secrets);
+    resolved.accessible_name = redact(String(resolved.accessible_name).slice(0, settings.jev.maxDiagnosticChars), secrets);
+    if (resolved.title) resolved.title = redact(String(resolved.title).slice(0, settings.jev.maxDiagnosticChars), secrets);
+    else delete resolved.title;
+    if (resolved.href) resolved.href = evidenceUrl(resolved.href, secrets, settings.jev.maxDiagnosticChars);
+    else delete resolved.href;
+    if (Object.hasOwn(resolved, "value")) {
+      resolved.value = redact(resolved.value.slice(0, settings.browser.maxTextEntryChars), secrets);
+    }
+    return resolved;
+  } catch {
+    return undefined;
+  }
+}
+
+function targetEvidence(step, secrets, resolvedTarget) {
+  const evidence = { target: describeTarget(step, secrets) };
+  if (resolvedTarget) evidence.resolved_target = resolvedTarget;
+  return evidence;
 }
 
 async function namedTarget(root, step, snapshot, secrets, timeout, settings) {
@@ -1251,10 +1586,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;
+  if (step.action === "assert_network") {
+    const response = await waitForNetworkAssertion(
+      execution.networkTracker,
+      step,
+      execution.networkMarker,
+      timeout,
+      page,
+      settings,
+      secrets,
+    );
+    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 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();
+    if (!actualText.includes(expectedText)) {
+      throw new JevBrowserError(`confirm_dialog refused to click ${JSON.stringify(redact(step.button, secrets))}: expected dialog text was not present`);
+    }
+    const button = await exactlyOne(dialog.getByRole("button", { name: step.button, exact: true }), `dialog button ${JSON.stringify(redact(step.button, secrets))}`, timeout, settings);
+    const resolvedTarget = await describeResolvedTarget(button, { ...step, action: "click", role: "button", name: step.button }, secrets, settings);
+    await button.click({ timeout });
+    return {
+      action: step.action,
+      confirmed_text: redact(expectedText, secrets),
+      ...targetEvidence({ action: step.action, role: "dialog", name: step.expectedText }, secrets, resolvedTarget),
+    };
+  }
+  if (step.action === "extract") {
+    const control = await namedTarget(root, step, snapshot, secrets, timeout, settings);
+    const resolvedTarget = await describeResolvedTarget(control, step, secrets, settings);
+    let value;
+    if (step.source === "value") value = await control.inputValue({ timeout });
+    else if (step.source === "attribute") value = await control.getAttribute(step.attribute, { timeout }) || "";
+    else value = (await control.innerText({ timeout })).replace(/\s+/g, " ").trim();
+    if (value.length > settings.browser.maxTextEntryChars) {
+      throw new JevBrowserError("extracted value exceeds the configured character limit");
+    }
+    execution.variables[step.as] = value;
+    if (step.sensitive && value && !secrets.includes(value)) {
+      secrets.push(value);
+      secrets.sort((left, right) => right.length - left.length);
+    }
+    return {
+      action: step.action,
+      variable: step.as,
+      ...(step.sensitive ? { value_redacted: Boolean(value) } : { value: redact(value, secrets) }),
+      ...targetEvidence(step, secrets, resolvedTarget),
+    };
+  }
   if (step.action === "wait_for_text") {
     const locator = root.getByText(step.text, { exact: false });
-    await visibleIndexes(locator, timeout, `text ${JSON.stringify(redact(step.text, secrets))}`, settings);
-    return { action: step.action };
+    if (step.failOn) await waitForTextOrFailure(root, step, timeout, settings, secrets);
+    else await visibleIndexes(locator, timeout, `text ${JSON.stringify(redact(step.text, secrets))}`, settings);
+    return { action: step.action, target: `text ${JSON.stringify(redact(step.text, secrets))}` };
   }
   if (step.action === "wait_for_condition") {
     if (step.condition === "network_idle") {
@@ -1273,16 +1659,24 @@ async function executeStep(page, step, settings, snapshot, secrets, downloadLedg
       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 };
+    return {
+      action: step.action,
+      condition: step.condition,
+      ...(step.condition === "network_idle"
+        ? (step.urlContains ? { url_contains: redact(step.urlContains, secrets) } : {})
+        : { target: describeTarget(step, secrets) }),
+    };
   }
   if (step.action === "press") {
+    let evidence = {};
     if (step.role || step.name !== undefined || hasLocatorField(step) || step.near) {
       const control = await namedTarget(root, step, snapshot, secrets, timeout, settings);
+      evidence = targetEvidence(step, secrets, await describeResolvedTarget(control, step, secrets, settings));
       await control.press(step.key, { timeout });
     } else {
       await page.keyboard.press(step.key, { timeout });
     }
-    return { action: step.action, key: step.key };
+    return { action: step.action, key: step.key, ...evidence };
   }
   if (step.action === "like_comment" || step.action === "unlike_comment") {
     return { action: step.action, result: await reactToComment(root, step, timeout, settings) };
@@ -1300,6 +1694,7 @@ async function executeStep(page, step, settings, snapshot, secrets, downloadLedg
   if (step.action === "upload_file") {
     const files = await uploadFiles(step, settings);
     const control = await namedTarget(root, step, snapshot, secrets, timeout, settings);
+    const resolvedTarget = await describeResolvedTarget(control, step, secrets, settings);
     if (step.target === "input") {
       await control.setInputFiles(files, { timeout });
     } else {
@@ -1313,23 +1708,34 @@ async function executeStep(page, step, settings, snapshot, secrets, downloadLedg
         await control.drop({ files }, { timeout });
       }
     }
-    return { action: step.action, target: step.target, file_count: files.length };
+    return {
+      action: step.action,
+      target: step.target,
+      target_locator: describeTarget(step, secrets),
+      ...(resolvedTarget ? { resolved_target: resolvedTarget } : {}),
+      file_count: files.length,
+    };
   }
   if (step.action === "assert_hidden") {
     const locator = await targetLocator(root, step, timeout, settings);
     await waitForLocatorHidden(locator, timeout, `assert_hidden ${describeTarget(step, secrets)}`, settings, step.index);
-    return { action: step.action, asserted: true };
+    return { action: step.action, asserted: true, target: describeTarget(step, secrets) };
   }
   if (step.action === "assert_visible") {
     const control = await namedTarget(root, step, snapshot, secrets, timeout, settings);
     if (!(await isActuallyVisible(control))) throw new JevBrowserError(`assert_visible failed for ${describeTarget(step, secrets)}`);
-    return { action: step.action, asserted: true };
+    return {
+      action: step.action,
+      asserted: true,
+      ...targetEvidence(step, secrets, await describeResolvedTarget(control, step, secrets, settings)),
+    };
   }
   const control = await namedTarget(root, step, snapshot, secrets, timeout, settings);
   if (step.action === "click") {
-    if (!step.expectDownload) {
+    const resolvedTarget = await describeResolvedTarget(control, step, secrets, settings);
+    if (!step.expectDownload) {
       await control.click({ timeout });
-      return { action: step.action, target: describeTarget(step, secrets) };
+      return { action: step.action, ...targetEvidence(step, secrets, resolvedTarget) };
     }
     let download;
     try {
@@ -1340,13 +1746,14 @@ async function executeStep(page, step, settings, snapshot, secrets, downloadLedg
     } catch {
       throw new JevBrowserError("click did not produce the expected download before the configured timeout");
     }
-    return {
-      action: step.action,
-      target: describeTarget(step, secrets),
-      downloaded_file: await saveDownload(download, settings, downloadLedger),
-    };
+    return {
+      action: step.action,
+      ...targetEvidence(step, secrets, resolvedTarget),
+      downloaded_file: await saveDownload(download, settings, downloadLedger),
+    };
   }
   if (step.action === "type") {
+    const resolvedTarget = await describeResolvedTarget(control, step, secrets, settings);
     if (step.mode === "keys") {
       await control.fill("", { timeout });
       const normalizedText = step.text.replace(/\r\n?/g, "\n");
@@ -1361,32 +1768,54 @@ async function executeStep(page, step, settings, snapshot, secrets, downloadLedg
       await control.fill(step.text, { timeout });
       if (step.blur) await control.press("Tab", { timeout });
     }
-    return { action: step.action, role: step.role, name: step.name };
-  }
+    if (resolvedTarget && step.sensitive === false) {
+      resolvedTarget.value = redact((await control.inputValue({ timeout })).slice(0, settings.browser.maxTextEntryChars), secrets);
+    }
+    return {
+      action: step.action,
+      role: step.role,
+      name: step.name,
+      ...targetEvidence(step, secrets, resolvedTarget),
+    };
+  }
   if (step.action === "select_option") {
+    const resolvedTarget = await describeResolvedTarget(control, step, secrets, settings);
     await control.selectOption({ label: step.option }, { timeout });
-    return { action: step.action, target: describeTarget(step, secrets) };
-  }
-  if (step.action === "hover") {
-    await control.hover({ timeout });
-    return { action: step.action, role: step.role, name: step.name };
-  }
-  if (step.action === "assert_visible") {
-    if (!(await control.isVisible())) throw new JevBrowserError(`assert_visible failed for ${step.role} ${JSON.stringify(redact(step.name, secrets))}`);
-    return { action: step.action, asserted: true };
-  }
+    return { action: step.action, ...targetEvidence(step, secrets, resolvedTarget) };
+  }
+  if (step.action === "hover") {
+    const resolvedTarget = await describeResolvedTarget(control, step, secrets, settings);
+    await control.hover({ timeout });
+    return { action: step.action, role: step.role, name: step.name, ...targetEvidence(step, secrets, resolvedTarget) };
+  }
+  if (step.action === "assert_visible") {
+    if (!(await control.isVisible())) throw new JevBrowserError(`assert_visible failed for ${step.role} ${JSON.stringify(redact(step.name, secrets))}`);
+    return {
+      action: step.action,
+      asserted: true,
+      ...targetEvidence(step, secrets, await describeResolvedTarget(control, step, secrets, settings)),
+    };
+  }
   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())) {
+    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)}`);
-    }
-    return { action: step.action, asserted: true };
-  }
-  if (step.action === "assert_value") {
-    const actual = await control.inputValue({ timeout });
+    }
+    return {
+      action: step.action,
+      asserted: true,
+      ...targetEvidence(step, secrets, await describeResolvedTarget(control, step, secrets, settings)),
+    };
+  }
+  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)}`);
-    return { action: step.action, asserted: true };
+    return {
+      action: step.action,
+      asserted: true,
+      ...targetEvidence(step, secrets, await describeResolvedTarget(control, step, secrets, settings)),
+    };
   }
   throw new JevBrowserError("unsupported browser action");
 }
@@ -1429,7 +1858,7 @@ function sanitizeDiagnosticText(value, secrets, limit) {
 }
 
 function createDiagnostics(page, options, settings, secrets) {
-  const diagnostics = { console_errors: [], network_failures: [] };
+  const diagnostics = { console_errors: [], network_failures: [], warnings: [] };
   const pendingBodies = [];
   const limit = settings.jev.maxDiagnosticItems;
   const messageLimit = settings.jev.maxDiagnosticChars;
@@ -1441,26 +1870,50 @@ function createDiagnostics(page, options, settings, secrets) {
     addDiagnostic(diagnostics.console_errors, sanitizeDiagnosticText(error.message || error.name, secrets, messageLimit), limit);
   };
   const addResponseMessage = async (response, entry) => {
+    const warn = (reason) => addDiagnostic(
+      diagnostics.warnings,
+      `network error response body omitted for ${entry.url}: ${reason}`,
+      limit,
+    );
     try {
       const responseUrl = new URL(response.url());
       const pageUrl = new URL(page.url());
       if (responseUrl.origin !== pageUrl.origin) return;
       const headers = await response.headers();
       const contentType = String(headers["content-type"] || "").toLowerCase();
-      const contentLength = Number(headers["content-length"]);
-      if (!contentType.includes("application/json") || !Number.isSafeInteger(contentLength)
-        || contentLength < 0 || contentLength > settings.browser.maxNetworkErrorBodyBytes) return;
+      if (!contentType.includes("application/json")) {
+        warn("content-type is not application/json");
+        return;
+      }
+      const contentLengthHeader = headers["content-length"];
+      if (contentLengthHeader !== undefined) {
+        const contentLength = Number(contentLengthHeader);
+        if (!Number.isSafeInteger(contentLength) || contentLength < 0) {
+          warn("Content-Length is invalid");
+          return;
+        }
+        if (contentLength > settings.browser.maxNetworkErrorBodyBytes) {
+          warn("declared Content-Length exceeds the configured limit");
+          return;
+        }
+      }
       const body = await withTimeout(
         response.body(),
         settings.browser.actionTimeoutMs,
         "error response body read timed out",
       );
-      if (body.length > settings.browser.maxNetworkErrorBodyBytes) return;
+      if (body.length > settings.browser.maxNetworkErrorBodyBytes) {
+        warn("received body exceeds the configured limit");
+        return;
+      }
       const payload = JSON.parse(body.toString("utf8"));
-      if (!isRecord(payload) || typeof payload.message !== "string") return;
+      if (!isRecord(payload) || typeof payload.message !== "string") {
+        warn("JSON body does not contain a text message");
+        return;
+      }
       entry.message = sanitizeDiagnosticText(payload.message, secrets, settings.browser.maxNetworkErrorMessageChars);
     } catch {
-      // A diagnostic body is optional; malformed, oversized, or late bodies do not fail the flow.
+      warn("body could not be read or parsed safely");
     }
   };
   const onResponse = (response) => {
@@ -1518,6 +1971,12 @@ function failedStepDetails(step, index, error, settings, secrets) {
   };
   if (step.role !== undefined) details.role = step.role;
   if (step.name !== undefined) details.name = redact(step.name, secrets);
+  if (step.role || hasLocatorField(step) || step.near || step.within) details.target = describeTarget(step, secrets);
+  if (step.action === "wait_for_text") details.text = redact(step.text, secrets);
+  if (step.failOn) {
+    details.fail_on = { role: step.failOn.role };
+    if (step.failOn.name !== undefined) details.fail_on.name = redact(step.failOn.name, secrets);
+  }
   details.timeout_ms = step.timeoutMs ?? settings.browser.actionTimeoutMs;
   details.error = stepFailureText(error?.stepCause || error, secrets, settings.jev.maxDiagnosticChars);
   return details;
@@ -1547,10 +2006,87 @@ async function installTrackerBlocking(context, settings, enabled) {
   return async () => context.unroute("**/*", handler);
 }
 
-async function artifactPath(settings, extension) {
+async function artifactPath(settings, extension) {
   await mkdir(settings.browser.artifactDirectory, { recursive: true });
   return path.join(settings.browser.artifactDirectory, `jev-browser-${Date.now()}-${randomUUID()}.${extension}`);
-}
+}
+
+async function safeReportPath(requestedPath, settings) {
+  await mkdir(settings.browser.artifactDirectory, { recursive: true });
+  const root = await realpath(settings.browser.artifactDirectory);
+  const target = path.resolve(requestedPath);
+  const relative = path.relative(root, target);
+  if (!relative || relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+    throw new JevBrowserError("report_path must name a file inside the configured artifact directory");
+  }
+  await mkdir(path.dirname(target), { recursive: true });
+  const actualParent = await realpath(path.dirname(target));
+  const parentRelative = path.relative(root, actualParent);
+  if (parentRelative === ".." || parentRelative.startsWith(`..${path.sep}`) || path.isAbsolute(parentRelative)) {
+    throw new JevBrowserError("report_path cannot resolve outside the configured artifact directory");
+  }
+  const outputPath = path.join(actualParent, path.basename(target));
+  try {
+    if ((await lstat(outputPath)).isSymbolicLink()) throw new JevBrowserError("report_path cannot replace a symbolic link");
+  } catch (error) {
+    if (error instanceof JevBrowserError) throw error;
+    if (error?.code !== "ENOENT") throw error;
+  }
+  return outputPath;
+}
+
+function xmlEscape(value) {
+  return String(value).replace(/[&<>"']/g, (char) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&apos;" })[char]);
+}
+
+function reportContent(result, extension) {
+  if (extension === ".xml") {
+    const steps = result.steps || [];
+    const failures = steps.filter(({ status }) => status === "failed");
+    const cases = steps.map((step) => {
+      const name = `${step.step || "?"} ${step.action || "step"}`;
+      const evidence = [
+        step.target ? `target: ${step.target}` : "",
+        step.resolved_target ? `resolved_target: ${JSON.stringify(step.resolved_target)}` : "",
+        step.method ? `network: ${step.method} ${step.url || ""} -> ${step.response_status ?? ""}${step.message ? ` (${step.message})` : ""}` : "",
+        step.screenshot_path ? `screenshot: ${step.screenshot_path}` : "",
+        step.mutating === true ? "mutating: true" : "",
+      ].filter(Boolean).join("\n");
+      const output = evidence ? `<system-out>${xmlEscape(evidence)}</system-out>` : "";
+      const failure = step.status === "failed" ? `<failure message="${xmlEscape(step.error || "step failed")}">${xmlEscape(step.error || "step failed")}</failure>` : "";
+      return `<testcase name="${xmlEscape(name)}" time="${Math.max(0, Number(step.duration_ms || 0) / 1000).toFixed(3)}">${failure}${output}</testcase>`;
+    }).join("");
+    const suiteEvidence = [
+      `server_version: ${result.server_version || "unknown"}`,
+      `status: ${result.status || "unknown"}`,
+      result.navigation_error ? `navigation_error: ${result.navigation_error}` : "",
+      ...(result.network_failures || []).map((entry) => `network_failure: ${entry.method || ""} ${entry.url || ""} -> ${entry.status ?? entry.failure ?? "error"}${entry.message ? ` (${entry.message})` : ""}`),
+    ].filter(Boolean).join("\n");
+    return `<?xml version="1.0" encoding="UTF-8"?>\n<testsuite name="jev-browser" tests="${steps.length}" failures="${failures.length}" time="${(Number(result.timings_ms?.total_ms || 0) / 1000).toFixed(3)}"><system-out>${xmlEscape(suiteEvidence)}</system-out>${cases}</testsuite>\n`;
+  }
+  const rows = (result.steps || []).map((step) => {
+    const details = [step.target, step.resolved_target ? JSON.stringify(step.resolved_target) : "", step.screenshot_path ? `screenshot: ${step.screenshot_path}` : ""]
+      .filter(Boolean).join("; ");
+    return `| ${step.step || ""} | ${step.action || ""} | ${step.status || "passed"} | ${step.duration_ms ?? ""} | ${String(details).replace(/\|/g, "\\|")} |`;
+  });
+  return [
+    "# Jev Browser flow report", "", `- Status: ${result.status}`, `- Server: ${result.server_version || "unknown"}`,
+    `- Selected plan: ${result.selected_plan || "none"}`, `- Total: ${result.timings_ms?.total_ms ?? "unknown"} ms`,
+    `- Navigation error: ${result.navigation_error || "none"}`, "", "## Steps", "",
+    "| # | Action | Status | Duration (ms) | Evidence |", "| -: | --- | --- | ---: | --- |", ...rows,
+    "", "## Network", "", ...(result.steps || []).filter(({ action }) => action === "assert_network")
+      .map(({ step, method, response_status: status, url, message }) => `- Step ${step}: ${method} ${url} → ${status}${message ? ` — ${message}` : ""}`),
+    ...(result.steps || []).some(({ action }) => action === "assert_network") ? [] : ["No network assertions."],
+    "", "## Errors", "", ...(result.network_failures || []).map((failure) => `- ${failure.method || ""} ${failure.url || ""} — ${failure.status ?? failure.failure ?? "error"}${failure.message ? `: ${failure.message}` : ""}`),
+    ...(result.network_failures || []).length ? [] : ["No network failures."], "",
+  ].join("\n");
+}
+
+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 redactObject(value, secrets) {
   if (typeof value === "string") return redact(value, secrets);
@@ -1565,15 +2101,16 @@ function hasAssertions(steps) {
   return steps.some(({ action }) => action.startsWith("assert_"));
 }
 
-export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, candidatePlans, options: rawOptions, settings, browserPool, fetchImpl = fetch }) {
-  if (typeof flow !== "string" || typeof expectedOutcome !== "string") throw new JevBrowserError("flow and expected_outcome must be text");
-  const requestedFlow = flow.trim();
-  const outcome = expectedOutcome.trim();
+export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, candidatePlans, params: rawParams, options: rawOptions, settings, browserPool, fetchImpl = fetch, serverVersion }) {
+  if (typeof flow !== "string" || typeof expectedOutcome !== "string") throw new JevBrowserError("flow and expected_outcome must be text");
+  const 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(candidatePlans, settings);
+  const plans = validateCandidatePlans(replaceKnownParams(candidatePlans, variables), settings);
   const options = resolveFlowOptions(rawOptions, settings);
   const secrets = [...planSecrets(plans), settings.env?.[settings.jev.credentialEnv]].filter(Boolean)
     .sort((left, right) => right.length - left.length);
@@ -1583,7 +2120,8 @@ export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, ca
   const page = browser.page;
   const context = browser.context;
   const capture = createDiagnostics(page, options, settings, secrets);
-  const result = {
+  const result = {
+    ...(serverVersion ? { server_version: serverVersion } : {}),
     status: "failed",
     expected_outcome_visible: false,
     acceptance_criteria_met: false,
@@ -1593,6 +2131,8 @@ export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, ca
     downloaded_files: [],
     accessibility_audits: [],
     unnamed_controls: [],
+    unnamed_controls_initial: [],
+    unnamed_controls_final: [],
     warnings: [],
     final_snapshot: "",
   };
@@ -1602,7 +2142,8 @@ export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, ca
   let unroute;
   let tracingStarted = false;
   let tracePath;
-  const artifactErrors = [];
+  const artifactErrors = [];
+  let navigationError;
   try {
     page.setDefaultTimeout(settings.browser.actionTimeoutMs);
     context.setDefaultTimeout(settings.browser.actionTimeoutMs);
@@ -1618,6 +2159,11 @@ export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, ca
 
     let reusedPage = false;
     if (options.reusePage) {
+      navigationError = browserPool.getNavigationError?.();
+      if (navigationError) {
+        result.navigation_error = navigationError;
+        throw new JevBrowserError(`reuse_page cannot continue because the previous navigation failed with ${navigationError}; run once with reuse_page: false to navigate again`);
+      }
       const currentUrl = page.url();
       if (currentUrl && currentUrl !== "about:blank") {
         let currentOrigin;
@@ -1634,7 +2180,14 @@ export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, ca
     }
     if (!reusedPage) {
       const navigationStarted = performance.now();
-      await page.goto(url, { waitUntil: "domcontentloaded", timeout: settings.browser.actionTimeoutMs * 4 });
+      try {
+        await page.goto(url, { waitUntil: "domcontentloaded", timeout: settings.browser.actionTimeoutMs * 4 });
+        browserPool.setNavigationError?.(null);
+      } catch (error) {
+        navigationError = String(error?.message || "").match(/\b(?:net::)?(ERR_[A-Z0-9_]+)\b/)?.[1] || "NAVIGATION_FAILED";
+        if (navigationError) browserPool.setNavigationError?.(navigationError);
+        throw error;
+      }
       timings.navigationMs = performance.now() - navigationStarted;
     }
     const snapshotStarted = performance.now();
@@ -1643,6 +2196,8 @@ export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, ca
       const enriched = await enrichSnapshot(page, readiness.snapshot, settings, secrets, options.snapshotScope, options.snapshotIncludeHidden);
       result.final_snapshot = enriched.snapshot;
       result.unnamed_controls = enriched.unnamedControls;
+      result.unnamed_controls_initial = enriched.unnamedControls;
+      result.unnamed_controls_final = enriched.unnamedControls;
       for (const control of enriched.unnamedControls) {
         addDiagnostic(
           result.warnings,
@@ -1651,6 +2206,7 @@ export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, ca
         );
       }
       timings.readyMs = readiness.readyMs;
+      browserPool.setNavigationError?.(null);
     } catch (error) {
       timings.readyMs = error.readyMs || performance.now() - snapshotStarted;
       throw error;
@@ -1704,26 +2260,47 @@ export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, ca
         const trace = [];
         let failure = "";
         let failedStep;
+        let dryRunStop;
         let snapshot = result.final_snapshot;
         let networkMarker = networkTracker.mark();
         const planStarted = performance.now();
         const runAllSteps = plan.steps.some(({ action, expectDownload }) => action.startsWith("assert_")
           || ["upload_file", "select_option", "hover", "like_comment", "unlike_comment", "audit_accessibility"].includes(action)
           || expectDownload === true);
-        for (const [index, step] of plan.steps.entries()) {
+        for (const [index, templateStep] of plan.steps.entries()) {
+          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 };
+              break;
+            }
             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 (!["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);
-            trace.push(traceStep);
+            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 });
+              } catch {
+                delete traceStep.screenshot_path;
+                artifactErrors.push(`step ${index + 1} screenshot could not be saved`);
+              }
+            }
+            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);
@@ -1747,6 +2324,15 @@ export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, ca
             failure = error instanceof JevBrowserError
               ? error.message
               : `Playwright action failed (${error?.name || "BrowserError"})`;
+            const failedTraceStep = {
+              step: String(index + 1),
+              action: step?.action || templateStep.action,
+              status: "failed",
+              duration_ms: Math.round((performance.now() - stepStarted) * 10) / 10,
+              error: sanitizeDiagnosticText(failure, secrets, settings.jev.maxDiagnosticChars),
+              ...(step?.mutating === true ? { mutating: true } : {}),
+            };
+            trace.push(failedTraceStep);
             failedStep = failedStepDetails(step, index, error, settings, secrets);
             break;
           }
@@ -1772,9 +2358,8 @@ export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, ca
           options.snapshotIncludeHidden,
         );
         snapshot = finalDetails.snapshot;
-        result.unnamed_controls = [...result.unnamed_controls, ...finalDetails.unnamedControls]
-          .filter((control, index, all) => all.findIndex((candidate) => candidate.role === control.role
-            && candidate.html === control.html) === index);
+        result.unnamed_controls_final = finalDetails.unnamedControls;
+        result.unnamed_controls = finalDetails.unnamedControls;
         timings.browserPlanMs = performance.now() - planStarted;
         const visible = containsExpectedOutcome(snapshot, outcome);
         const assertionCount = plan.steps.filter(({ action }) => action.startsWith("assert_")).length;
@@ -1786,12 +2371,17 @@ export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, ca
         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 ? "failed" : visible || assertionsPassed || auditsPassed || downloadsPassed ? "passed" : "incomplete";
-        result.expected_outcome_visible = visible;
-        result.acceptance_criteria_met = !failure && (visible || assertionsPassed || auditsPassed || downloadsPassed);
+        result.status = failure ? "failed" : dryRunStop ? "dry_run" : visible || assertionsPassed || auditsPassed || downloadsPassed ? "passed" : "incomplete";
+        result.expected_outcome_visible = visible;
+        result.acceptance_criteria_met = !failure && !dryRunStop && (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})`;
+        }
         result.final_snapshot = snapshot;
         if (failure) {
           result.reason = failure;
@@ -1805,11 +2395,13 @@ export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, ca
       }
     }
   } catch (error) {
-    result.status = "failed";
-    result.acceptance_criteria_met = false;
+    result.status = navigationError ? "environment_error" : "failed";
+    result.acceptance_criteria_met = false;
+    if (navigationError) result.navigation_error = navigationError;
     result.reason = error instanceof JevBrowserError
       ? error.message
-      : `Playwright flow failed (${error?.name || "BrowserError"})`;
+      : navigationError ? `Navigation failed with ${navigationError}; verify that the application server is running and reachable`
+        : `Playwright flow failed (${error?.name || "BrowserError"})`;
     try {
       const snapshot = await snapshotPage(page, settings, secrets, options.snapshotScope, {
         allowEmpty: true,
@@ -1825,6 +2417,7 @@ export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, ca
           options.snapshotIncludeHidden,
         );
         result.final_snapshot = enriched.snapshot;
+        result.unnamed_controls_final = enriched.unnamedControls;
         result.unnamed_controls = enriched.unnamedControls;
       } else {
         result.final_snapshot = snapshot;
@@ -1865,11 +2458,20 @@ export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, ca
   }
   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 = capture.diagnostics.console_errors;
+  result.network_failures = 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);
-  return redactObject(result, secrets);
-}
+  const safeResult = await redactObject(result, secrets);
+  if (options.reportPath) {
+    try {
+      safeResult.report_path = await writeFlowReport(safeResult, options.reportPath, settings);
+    } catch (error) {
+      safeResult.artifact_errors = [...(safeResult.artifact_errors || []), error instanceof JevBrowserError ? error.message : "flow report could not be saved"];
+    }
+  }
+  return safeResult;
+}
 
 export async function chooseNextAction({ flow, pageSnapshot, actions, completedSteps = [], settings, fetchImpl = fetch }) {
   const { request, criteria } = buildChoicePayload({ flow, pageSnapshot, actions, completedSteps }, settings.jev);