@diegosouzacdv/jev-browser-mcp 0.4.2 → 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,6 +140,9 @@ 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"] },
+        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"] },
@@ -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)) {
@@ -246,6 +297,39 @@ export function validateCandidatePlans(candidatePlans, settings) {
           }
         }
       }
+      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");
@@ -360,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) {
@@ -391,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,
@@ -584,7 +679,7 @@ 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: "", exact: true });
+    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) => {
@@ -760,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();
@@ -807,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) {
@@ -1000,6 +1159,7 @@ async function waitForTextOrFailure(root, step, timeout, settings, secrets) {
   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(() => "");
@@ -1009,7 +1169,6 @@ async function waitForTextOrFailure(root, step, timeout, settings, secrets) {
         `wait_for_text ${JSON.stringify(redact(step.text, secrets))} stopped because ${failureTarget} appeared: ${JSON.stringify(message)}`,
       );
     }
-    if (await firstVisibleMatch(expected)) return;
     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`);
@@ -1046,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);
@@ -1057,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 };
 }
 
@@ -1094,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") {
@@ -1137,9 +1305,11 @@ function describeTarget(step, secrets) {
   }
   if (step.near) parts.push(`near text ${JSON.stringify(redact(step.near.text, secrets))}`);
   if (step.within) {
-    parts.push(step.within.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))}`}`);
+    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";
@@ -1149,7 +1319,7 @@ 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, includeFieldValue) => {
+    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(" ");
@@ -1170,13 +1340,20 @@ async function describeResolvedTarget(locator, step, secrets, settings) {
         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 (includeFieldValue && "value" in element) result.value = String(element.value ?? "");
+      if (options.includeFieldValue && "value" in element) result.value = String(element.value ?? "");
       return result;
-    }, includeValue);
+    }, { 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);
     }
@@ -1409,6 +1586,56 @@ 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 });
     if (step.failOn) await waitForTextOrFailure(root, step, timeout, settings, secrets);
@@ -1779,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);
@@ -1797,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);
@@ -1815,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,
@@ -1836,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);
@@ -1852,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;
@@ -1868,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();
@@ -1887,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;
@@ -1940,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);
@@ -1983,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;
           }
@@ -2021,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;
@@ -2040,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,
@@ -2105,8 +2462,16 @@ export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, ca
   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);