@diegosouzacdv/jev-browser-mcp 0.3.0 → 0.4.0

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

@@ -32,10 +32,11 @@ const MIME_TYPES = new Map([
   [".jpg", "image/jpeg"], [".jpeg", "image/jpeg"], [".png", "image/png"],
   [".txt", "text/plain"], [".webp", "image/webp"],
 ]);
-const FLOW_OPTION_KEYS = new Set([
-  "block_trackers", "capture_console_errors", "capture_network_errors", "fast_path",
-  "screenshot_on_failure", "snapshot_scope", "trace_on_failure",
-]);
+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",
+  "reuse_page", "screenshot_on_failure", "snapshot_scope", "trace_on_failure",
+]);
 
 function isRecord(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
@@ -79,28 +80,37 @@ export function validateCandidatePlans(candidatePlans, settings) {
       const rawStep = normalizeStepAliases(unprocessedStep);
       if (!isRecord(rawStep) || typeof rawStep.action !== "string") throw new JevBrowserError("each browser step must be an object with an action");
       const { action } = rawStep;
-      const targetSelection = ["frame", "comment", "within", "index"];
-      const schemas = {
-        click: { required: ["role", "name"], optional: [...targetSelection, "expect_download"] },
-        type: { required: ["role", "name", "text"], optional: targetSelection },
-        wait_for_text: { required: ["text"], optional: ["frame", "comment"] },
-        wait_for_condition: { required: ["condition"], optional: ["comment"] },
-        press_key: { required: ["key"], optional: ["frame", "comment"] },
-        select_option: { required: ["name", "option"], optional: targetSelection },
-        hover: { required: ["role", "name"], optional: targetSelection },
-        assert_text: { required: ["role", "name", "expected"], optional: targetSelection },
-        assert_value: { required: ["role", "name", "expected"], optional: targetSelection },
-        assert_visible: { required: ["role"], optional: ["name", ...targetSelection] },
-        assert_hidden: { required: ["role"], optional: ["name", ...targetSelection] },
-        upload_file: { required: ["file_paths"], optional: ["target", "label", "role", "name", ...targetSelection] },
-        audit_accessibility: { required: ["standard"], optional: ["comment"] },
-        like_comment: { required: ["author", "text", "like_label", "liked_label"], optional: ["frame", "comment"] },
-        unlike_comment: { required: ["author", "text", "like_label", "liked_label"], optional: ["frame", "comment"] },
+      const targetSelection = ["frame", "comment", "within", "index"];
+      const schemas = {
+        click: { required: ["role", "name"], optional: [...targetSelection, "expect_download", "timeout_seconds"] },
+        type: { required: ["role", "name", "text"], optional: [...targetSelection, "blur", "mode", "sensitive", "timeout_seconds"] },
+        wait_for_text: { required: ["text"], optional: ["frame", "comment", "timeout_seconds"] },
+        wait_for_condition: { required: ["condition"], optional: ["frame", "comment", "name", "role", "text", "timeout_seconds"] },
+        press_key: { required: ["key"], optional: ["frame", "comment", "timeout_seconds"] },
+        select_option: { required: ["name", "option"], optional: [...targetSelection, "timeout_seconds"] },
+        hover: { required: ["role", "name"], optional: [...targetSelection, "timeout_seconds"] },
+        assert_text: { required: ["role", "expected"], optional: ["name", ...targetSelection, "timeout_seconds"] },
+        assert_value: { required: ["role", "name", "expected"], optional: [...targetSelection, "timeout_seconds"] },
+        assert_visible: { required: ["role"], optional: ["name", ...targetSelection, "timeout_seconds"] },
+        assert_hidden: { required: ["role"], optional: ["name", ...targetSelection, "timeout_seconds"] },
+        upload_file: { required: ["file_paths"], optional: ["target", "label", "role", "name", ...targetSelection, "timeout_seconds"] },
+        audit_accessibility: { required: ["standard"], optional: ["comment", "timeout_seconds"] },
+        like_comment: { required: ["author", "text", "like_label", "liked_label"], optional: ["frame", "comment", "timeout_seconds"] },
+        unlike_comment: { required: ["author", "text", "like_label", "liked_label"], optional: ["frame", "comment", "timeout_seconds"] },
       };
       if (!Object.hasOwn(schemas, action)) throw new JevBrowserError("unsupported browser action");
       exactKeys(rawStep, ["action", ...schemas[action].required], schemas[action].optional, action);
 
-      const step = { action };
+      const step = { action };
+      if (rawStep.timeout_seconds !== undefined) {
+        if (typeof rawStep.timeout_seconds !== "number" || !Number.isFinite(rawStep.timeout_seconds) || rawStep.timeout_seconds <= 0) {
+          throw new JevBrowserError("timeout_seconds must be a positive number");
+        }
+        if (rawStep.timeout_seconds > settings.browser.maxStepTimeoutSeconds) {
+          throw new JevBrowserError("timeout_seconds exceeds the configured step-timeout limit");
+        }
+        step.timeoutMs = Math.ceil(rawStep.timeout_seconds * 1000);
+      }
       if (rawStep.comment !== undefined) requiredText(rawStep.comment, "comment", settings.jev.maxActionDescriptionChars);
       if (rawStep.within !== undefined) {
         if (!TARGET_SELECTION_ACTIONS.has(action) || !isRecord(rawStep.within)) {
@@ -134,7 +144,7 @@ export function validateCandidatePlans(candidatePlans, settings) {
         }
         step.role = rawStep.role;
         if (rawStep.name !== undefined) step.name = requiredText(rawStep.name, "accessible name", settings.jev.maxActionDescriptionChars);
-        if (["click", "type", "hover", "assert_text", "assert_value"].includes(action) && !step.name) {
+        if (["click", "type", "hover", "assert_value"].includes(action) && !step.name) {
           throw new JevBrowserError(`${action} step needs an accessible name`);
         }
       }
@@ -143,17 +153,38 @@ export function validateCandidatePlans(candidatePlans, settings) {
         step.name = requiredText(rawStep.name, "accessible name", settings.jev.maxActionDescriptionChars);
         step.option = requiredText(rawStep.option, "option", settings.jev.maxActionDescriptionChars);
       }
-      if (action === "type") {
-        if (typeof rawStep.text !== "string" || rawStep.text.length === 0) throw new JevBrowserError("type step needs non-empty text");
-        if (rawStep.text.length > settings.browser.maxTextEntryChars) throw new JevBrowserError("type text exceeds the configured character limit");
-        step.text = rawStep.text;
+      if (action === "type") {
+        if (typeof rawStep.text !== "string" || rawStep.text.length === 0) throw new JevBrowserError("type step needs non-empty text");
+        if (rawStep.text.length > settings.browser.maxTextEntryChars) throw new JevBrowserError("type text exceeds the configured character limit");
+        if (rawStep.mode !== undefined && !new Set(["fill", "keys"]).has(rawStep.mode)) {
+          throw new JevBrowserError("type mode must be fill or keys");
+        }
+        if (rawStep.blur !== undefined && typeof rawStep.blur !== "boolean") throw new JevBrowserError("type blur must be a boolean");
+        if (rawStep.sensitive !== undefined && typeof rawStep.sensitive !== "boolean") throw new JevBrowserError("type sensitive must be a boolean");
+        step.text = rawStep.text;
+        step.mode = rawStep.mode || "fill";
+        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_condition") {
-        if (rawStep.condition !== "network_idle") throw new JevBrowserError("wait_for_condition supports only network_idle");
-        step.condition = rawStep.condition;
+      if (action === "wait_for_condition") {
+        if (!new Set(["network_idle", "hidden", "text_hidden"]).has(rawStep.condition)) {
+          throw new JevBrowserError("wait_for_condition supports network_idle, hidden, or text_hidden");
+        }
+        step.condition = rawStep.condition;
+        if (rawStep.condition === "hidden") {
+          if (!ASSERT_ROLES.has(rawStep.role)) throw new JevBrowserError("hidden condition needs a supported accessible role");
+          step.role = rawStep.role;
+          if (rawStep.name !== undefined) step.name = requiredText(rawStep.name, "accessible name", settings.jev.maxActionDescriptionChars);
+          if (rawStep.text !== undefined) throw new JevBrowserError("hidden condition does not accept text");
+        } else if (rawStep.condition === "text_hidden") {
+          step.text = requiredText(rawStep.text, "hidden text", settings.jev.maxActionDescriptionChars);
+          if (rawStep.role !== undefined || rawStep.name !== undefined) throw new JevBrowserError("text_hidden condition does not accept role or name");
+        } else if (rawStep.role !== undefined || rawStep.name !== undefined || rawStep.text !== undefined) {
+          throw new JevBrowserError("network_idle condition does not accept role, name, or text");
+        }
       }
       if (action === "audit_accessibility") {
         if (typeof rawStep.standard !== "string" || !Object.hasOwn(ACCESSIBILITY_STANDARDS, rawStep.standard)) {
@@ -240,23 +271,42 @@ function resolveFlowOptions(rawOptions, settings) {
   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_errors", "fast_path",
-    "screenshot_on_failure", "trace_on_failure",
+  const booleanOptions = [
+    "block_trackers", "capture_console_errors", "capture_network_error_bodies", "capture_network_errors",
+    "fast_path", "ready_network_idle", "reuse_page", "screenshot_on_failure", "trace_on_failure",
   ];
   for (const key of booleanOptions) {
     if (rawOptions[key] !== undefined && typeof rawOptions[key] !== "boolean") {
       throw new JevBrowserError(`options.${key} must be a boolean`);
     }
   }
-  const scope = rawOptions.snapshot_scope ?? settings.browser.defaults.snapshotScope;
-  if (!new Set(["body", "main", "dialog"]).has(scope)) throw new JevBrowserError("options.snapshot_scope must be body, main, or dialog");
-  const defaults = settings.browser.defaults;
-  return Object.freeze({
-    blockTrackers: rawOptions.block_trackers ?? defaults.blockTrackers,
-    captureConsoleErrors: rawOptions.capture_console_errors ?? defaults.captureConsoleErrors,
-    captureNetworkErrors: rawOptions.capture_network_errors ?? defaults.captureNetworkErrors,
-    fastPath: rawOptions.fast_path ?? defaults.fastPath,
+  const scope = rawOptions.snapshot_scope ?? settings.browser.defaults.snapshotScope;
+  if (!new Set(["body", "main", "dialog"]).has(scope)) throw new JevBrowserError("options.snapshot_scope must be body, main, or dialog");
+  const defaults = settings.browser.defaults;
+  const readyTimeoutSeconds = rawOptions.ready_timeout_seconds ?? defaults.readyTimeoutSeconds;
+  if (typeof readyTimeoutSeconds !== "number" || !Number.isFinite(readyTimeoutSeconds) || readyTimeoutSeconds <= 0
+    || readyTimeoutSeconds > settings.browser.maxReadyTimeoutSeconds) {
+    throw new JevBrowserError(`options.ready_timeout_seconds must be positive and at most ${settings.browser.maxReadyTimeoutSeconds}`);
+  }
+  const readyStableMs = rawOptions.ready_stable_ms ?? defaults.readyStableMs;
+  if (!Number.isSafeInteger(readyStableMs) || readyStableMs <= 0 || readyStableMs > settings.browser.maxReadyStableMs
+    || readyStableMs > readyTimeoutSeconds * 1000) {
+    throw new JevBrowserError("options.ready_stable_ms must be a positive integer within the configured readiness limits");
+  }
+  const readyText = rawOptions.ready_text === undefined
+    ? ""
+    : requiredText(rawOptions.ready_text, "ready_text", settings.jev.maxActionDescriptionChars);
+  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,
+    fastPath: rawOptions.fast_path ?? defaults.fastPath,
+    readyTimeoutMs: Math.ceil(readyTimeoutSeconds * 1000),
+    readyNetworkIdle: rawOptions.ready_network_idle ?? defaults.readyNetworkIdle,
+    readyStableMs,
+    readyText,
+    reusePage: rawOptions.reuse_page ?? defaults.reusePage,
     screenshotOnFailure: rawOptions.screenshot_on_failure ?? defaults.screenshotOnFailure,
     traceOnFailure: rawOptions.trace_on_failure ?? defaults.traceOnFailure,
     snapshotScope: scope,
@@ -267,12 +317,11 @@ function escapeRegex(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 
-function planSecrets(plans) {
+function planSecrets(plans) {
   const secrets = new Set();
   for (const plan of Object.values(plans)) {
     for (const step of plan.steps) {
-      if (step.action === "type") secrets.add(step.text);
-      if (step.action === "assert_text" || step.action === "assert_value") secrets.add(step.expected);
+      if (step.action === "type" && step.sensitive) secrets.add(step.text);
       if (step.action === "upload_file") {
         for (const filePath of step.filePaths) {
           secrets.add(filePath);
@@ -354,19 +403,24 @@ async function frameDisplayName(frame) {
   return name;
 }
 
-async function snapshotPage(page, settings, secrets, snapshotScope = "body") {
+async function snapshotPage(page, settings, secrets, snapshotScope = "body", { allowEmpty = false, timeoutMs } = {}) {
   let snapshot;
   let root;
   try {
     root = snapshotScope === "body" ? page.locator("body") : page.getByRole(snapshotScope);
-    const rootCount = snapshotScope === "body" ? 1 : await root.count();
-    if (rootCount !== 1) throw new JevBrowserError(`snapshot scope ${snapshotScope} must match exactly one accessible region; found ${rootCount}`);
-    snapshot = (await root.ariaSnapshot()).trim();
-  } catch (error) {
-    if (error instanceof JevBrowserError) throw error;
-    throw new JevBrowserError(`Playwright could not read the accessible page snapshot (${error?.name || "BrowserError"})`);
-  }
-  if (!snapshot) throw new JevBrowserError("Playwright returned an empty page snapshot");
+    const rootCount = snapshotScope === "body" ? 1 : await root.count();
+    if (allowEmpty && rootCount !== 1) return "";
+    if (rootCount !== 1) throw new JevBrowserError(`snapshot scope ${snapshotScope} must match exactly one accessible region; found ${rootCount}`);
+    snapshot = (await root.ariaSnapshot(timeoutMs ? { timeout: timeoutMs } : undefined)).trim();
+  } catch (error) {
+    if (error instanceof JevBrowserError) throw error;
+    if (allowEmpty) return "";
+    throw new JevBrowserError(`Playwright could not read the accessible page snapshot (${error?.name || "BrowserError"})`);
+  }
+  if (!snapshot) {
+    if (allowEmpty) return "";
+    throw new JevBrowserError("Playwright returned an empty page snapshot");
+  }
   let scopedFrameNames;
   if (snapshotScope !== "body") {
     try {
@@ -389,16 +443,84 @@ async function snapshotPage(page, settings, secrets, snapshotScope = "body") {
     }
   }
   const combined = [snapshot, ...frameSnapshots].join("\n\n");
-  return compactSnapshot(redact(combined, secrets), settings.jev.maxSnapshotChars);
-}
-
-async function exactlyOne(locator, description) {
-  const count = await locator.count();
-  if (count !== 1) throw new JevBrowserError(`${description} must match exactly one visible control; found ${count}`);
-  return locator;
-}
+  return compactSnapshot(redact(combined, secrets), settings.jev.maxSnapshotChars);
+}
+
+function remainingMs(deadline) {
+  return Math.max(1, Math.ceil(deadline - performance.now()));
+}
+
+async function waitForPageReady(page, options, settings, secrets) {
+  const started = performance.now();
+  const deadline = started + options.readyTimeoutMs;
+  const bestEffortLoadState = async (state) => {
+    try {
+      await page.waitForLoadState(state, { timeout: Math.min(500, remainingMs(deadline)) });
+    } catch {
+      // SPAs may keep requests open; accessible snapshot stability is the final readiness signal.
+    }
+  };
+  await bestEffortLoadState("load");
+  if (options.readyNetworkIdle) await bestEffortLoadState("networkidle");
+
+  let previousSnapshot = "";
+  let stableSince = 0;
+  let lastSnapshot = "";
+  while (performance.now() < deadline) {
+    const snapshot = await snapshotPage(page, settings, secrets, options.snapshotScope, {
+      allowEmpty: true,
+      timeoutMs: remainingMs(deadline),
+    });
+    lastSnapshot = snapshot;
+    const readyTextVisible = !options.readyText || containsPhrase(snapshot, options.readyText);
+    const usefulSnapshot = await hasRenderedContent(page, snapshot);
+    if (snapshot && readyTextVisible && usefulSnapshot) {
+      if (snapshot === previousSnapshot) {
+        if (!stableSince) stableSince = performance.now();
+        if (performance.now() - stableSince >= options.readyStableMs) {
+          return { snapshot, readyMs: performance.now() - started };
+        }
+      } else {
+        previousSnapshot = snapshot;
+        stableSince = performance.now();
+      }
+    } else {
+      previousSnapshot = "";
+      stableSince = 0;
+    }
+    await new Promise((resolve) => setTimeout(resolve, Math.min(100, remainingMs(deadline))));
+  }
+  const seconds = Number((options.readyTimeoutMs / 1000).toFixed(1));
+  const error = new JevBrowserError(`page did not render an accessible snapshot within ${seconds}s${lastSnapshot ? " (ready_text was not visible or snapshot did not stabilize)" : " (still loading?)"}`);
+  error.readyMs = performance.now() - started;
+  throw error;
+}
+
+async function hasRenderedContent(page, snapshot) {
+  const lines = snapshot.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+  if (!lines.some((line, index) => index > 0 || /:\s+\S|"[^"]+"/.test(line))) return false;
+  try {
+    if (await page.locator('[aria-busy="true"]').count() > 0) return false;
+  } catch {
+    // The snapshot itself is the fallback when the DOM is transitioning.
+  }
+  return true;
+}
+
+async function snapshotAfterStep(page, settings, secrets, scope, previousSnapshot, stepNumber, warnings) {
+  const snapshot = await snapshotPage(page, settings, secrets, scope, { allowEmpty: true });
+  if (snapshot) return snapshot;
+  warnings.push(`empty snapshot after step ${stepNumber}; kept the last accessible snapshot while the SPA rendered`);
+  const deadline = performance.now() + settings.browser.postStepReadyTimeoutMs;
+  while (performance.now() < deadline) {
+    await new Promise((resolve) => setTimeout(resolve, Math.min(100, remainingMs(deadline))));
+    const recovered = await snapshotPage(page, settings, secrets, scope, { allowEmpty: true, timeoutMs: remainingMs(deadline) });
+    if (recovered) return recovered;
+  }
+  return previousSnapshot;
+}
 
-function normalizedName(value) {
+function normalizedName(value) {
   return value.toLocaleLowerCase().replace(/[^\p{L}\p{N}]/gu, "");
 }
 
@@ -420,40 +542,73 @@ function editDistance(left, right) {
   return previous[b.length];
 }
 
-function closestAccessibleNames(snapshot, role, requestedName, secrets) {
-  const names = new Set();
-  const pattern = new RegExp(`^\\s*-\\s+${escapeRegex(role)}\\s+"((?:\\\\.|[^"])*)"`, "gmi");
-  for (const match of snapshot.matchAll(pattern)) {
-    if (names.size >= 200) break;
-    if (match[1].length > 160) continue;
-    try {
-      names.add(JSON.parse(`"${match[1]}"`));
-    } catch {
-      names.add(match[1]);
-    }
-  }
-  const wanted = normalizedName(requestedName);
-  return [...names]
-    .map((name) => {
-      const normalized = normalizedName(name);
-      const score = normalized && wanted
-        ? editDistance(normalized, wanted) / Math.max(normalized.length, wanted.length)
-        : 1;
-      return { name, score };
-    })
-    .filter(({ score }) => score <= 0.75)
-    .sort((left, right) => left.score - right.score)
-    .slice(0, 3)
-    .map(({ name }) => JSON.stringify(redact(name, secrets)));
-}
-
-async function scopedRoot(root, within) {
-  if (!within) return root;
-  return exactlyOne(
-    root.getByRole(within.role, { name: within.name, exact: true }),
-    "accessible within container",
-  );
-}
+function closestAccessibleNames(snapshot, role, requestedName, secrets) {
+  const roles = [...new Set([role, "button", "link", "tab", "menuitem"] )];
+  const names = new Map();
+  for (const candidateRole of roles) {
+    const pattern = new RegExp(`^\\s*-\\s+${escapeRegex(candidateRole)}\\s+"((?:\\\\.|[^"])*)"`, "gmi");
+    for (const match of snapshot.matchAll(pattern)) {
+      if (names.size >= 200) break;
+      if (match[1].length > 160) continue;
+      let name;
+      try {
+        name = JSON.parse(`"${match[1]}"`);
+      } catch {
+        name = match[1];
+      }
+      names.set(`${candidateRole}\n${name}`, { role: candidateRole, name });
+    }
+  }
+  const wanted = normalizedName(requestedName);
+  return [...names.values()]
+    .map(({ role: foundRole, name }) => {
+      const normalized = normalizedName(name);
+      const score = normalized && wanted
+        ? editDistance(normalized, wanted) / Math.max(normalized.length, wanted.length)
+        : 1;
+      return { role: foundRole, name, score };
+    })
+    .filter(({ score }) => score <= 0.75)
+    .sort((left, right) => left.score - right.score)
+    .slice(0, 3)
+    .map(({ role: foundRole, name }) => `${foundRole} ${JSON.stringify(redact(name, secrets))}`);
+}
+
+function attachStepCause(error, cause) {
+  error.stepCause = cause;
+  return error;
+}
+
+async function exactlyOne(locator, description, timeout) {
+  const first = typeof locator.first === "function" ? locator.first() : null;
+  if (timeout !== undefined && typeof first?.waitFor === "function") {
+    try {
+      await first.waitFor({ state: "visible", timeout });
+    } catch (cause) {
+      const error = new JevBrowserError(`${description} did not become visible before the configured timeout`);
+      throw attachStepCause(error, cause);
+    }
+  }
+  const count = await locator.count();
+  if (count !== 1) throw new JevBrowserError(`${description} must match exactly one visible control; found ${count}`);
+  return locator;
+}
+
+async function scopedRoot(root, within, timeout) {
+  if (!within) return root;
+  try {
+    return await exactlyOne(
+    root.getByRole(within.role, { name: within.name, exact: true }),
+    "accessible within container",
+      timeout,
+    );
+  } catch (error) {
+    if (error instanceof JevBrowserError && error.stepCause) {
+      throw attachStepCause(new JevBrowserError(`accessible within container ${within.role} ${JSON.stringify(within.name)} was not found`), error.stepCause);
+    }
+    throw error;
+  }
+}
 
 function indexedTarget(locator, count, index, description) {
   if (index !== undefined) {
@@ -464,23 +619,70 @@ function indexedTarget(locator, count, index, description) {
   return locator;
 }
 
-async function roleLocator(root, role, name, within) {
-  const targetRoot = await scopedRoot(root, within);
-  const locator = name === undefined
-    ? targetRoot.getByRole(role)
-    : targetRoot.getByRole(role, { name, exact: true });
-  return { locator, count: await locator.count() };
-}
-
-async function namedTarget(root, role, name, snapshot, secrets, selection = {}) {
-  const { locator, count } = await roleLocator(root, role, name, selection.within);
-  if (count === 0) {
-    const suggestions = closestAccessibleNames(snapshot, role, name, secrets);
-    const suffix = suggestions.length ? `; nearby accessible names: ${suggestions.join(", ")}` : "";
-    throw new JevBrowserError(`accessible target ${role} ${JSON.stringify(redact(name, secrets))} not found${suffix}`);
-  }
-  return indexedTarget(locator, count, selection.index, `accessible target ${role} ${JSON.stringify(redact(name, secrets))}`);
-}
+async function roleLocator(root, role, name, within, timeout) {
+  const targetRoot = await scopedRoot(root, within, timeout);
+  const locator = name === undefined
+    ? targetRoot.getByRole(role)
+    : targetRoot.getByRole(role, { name, exact: true });
+  return { locator, count: await locator.count() };
+}
+
+async function namedTarget(root, role, name, snapshot, secrets, selection = {}) {
+  const { locator } = await roleLocator(root, role, name, selection.within, selection.timeoutMs);
+  let count = await locator.count();
+  const awaited = selection.index === undefined
+    ? typeof locator.first === "function" ? locator.first() : null
+    : typeof locator.nth === "function" ? locator.nth(selection.index) : null;
+  if ((selection.index === undefined ? count === 0 : selection.index >= count) && typeof awaited?.waitFor === "function") {
+    try {
+      await awaited.waitFor({ state: "visible", timeout: selection.timeoutMs });
+      count = await locator.count();
+    } catch (cause) {
+      if (count > 0 && selection.index !== undefined) {
+        throw new JevBrowserError(`accessible target ${role} ${JSON.stringify(redact(name, secrets))} index ${selection.index} is out of range; found ${count}`);
+      }
+      const suggestions = closestAccessibleNames(snapshot, role, name, secrets);
+      const suffix = suggestions.length ? `; nearby accessible controls: ${suggestions.join(", ")}` : "";
+      const error = new JevBrowserError(`accessible target ${role} ${JSON.stringify(redact(name, secrets))} not found${suffix}`);
+      throw attachStepCause(error, cause);
+    }
+  }
+  if (count === 0) {
+    const suggestions = closestAccessibleNames(snapshot, role, name, secrets);
+    const suffix = suggestions.length ? `; nearby accessible controls: ${suggestions.join(", ")}` : "";
+    throw new JevBrowserError(`accessible target ${role} ${JSON.stringify(redact(name, secrets))} not found${suffix}`);
+  }
+  const description = `accessible target ${role} ${JSON.stringify(redact(name, secrets))}`;
+  const target = indexedTarget(locator, count, selection.index, description);
+  if (typeof target.waitFor === "function") {
+    try {
+      await target.waitFor({ state: "visible", timeout: selection.timeoutMs });
+    } catch (cause) {
+      const detail = selection.index !== undefined && selection.index >= count
+        ? `${description} index ${selection.index} is out of range; found ${count}`
+        : `${description} did not become visible before the configured timeout`;
+      throw attachStepCause(new JevBrowserError(detail), cause);
+    }
+  }
+  return target;
+}
+
+async function visibleRoleTarget(root, step, timeout, description) {
+  const { locator } = await roleLocator(root, step.role, undefined, step.within, timeout);
+  const target = step.index === undefined ? locator.first() : locator.nth(step.index);
+  if (typeof target?.waitFor === "function") {
+    try {
+      await target.waitFor({ state: "visible", timeout });
+    } catch (cause) {
+      throw attachStepCause(new JevBrowserError(`${description} did not become visible before the configured timeout`), cause);
+    }
+  }
+  const count = await locator.count();
+  if (count === 0 || (step.index !== undefined && step.index >= count)) {
+    throw new JevBrowserError(`${description} has no matching accessible control`);
+  }
+  return { locator, target: step.index === undefined ? locator.first() : locator.nth(step.index), count };
+}
 
 async function stepRoot(page, frameName) {
   if (!frameName) return page;
@@ -504,8 +706,8 @@ function commentRow(root, author, text) {
   return root.getByRole("button", { name: new RegExp(`(?=.*${authorPattern})(?=.*${textPattern})`, "isu") });
 }
 
-async function reactToComment(root, step) {
-  const row = await exactlyOne(commentRow(root, step.author, step.text), "requested comment row");
+async function reactToComment(root, step, timeout) {
+  const row = await exactlyOne(commentRow(root, step.author, step.text), "requested comment row", timeout);
   const isLike = step.action === "like_comment";
   const desired = isLike ? step.liked_label : step.like_label;
   const current = isLike ? step.like_label : step.liked_label;
@@ -519,8 +721,8 @@ async function reactToComment(root, step) {
   if (desiredCount === 1) return isLike ? "already_liked" : "already_unliked";
   if (currentCount !== 1) throw new JevBrowserError("comment reaction control is not uniquely available in the targeted comment");
   const controls = row.getByRole("button").filter({ has: currentImages });
-  await (await exactlyOne(controls, "comment reaction button")).click();
-  await desiredImages.waitFor({ state: "visible" });
+  await (await exactlyOne(controls, "comment reaction button", timeout)).click({ timeout });
+  await desiredImages.waitFor({ state: "visible", timeout });
   return isLike ? "liked" : "unliked";
 }
 
@@ -671,71 +873,100 @@ async function saveDownload(download, settings, ledger) {
   }
 }
 
-async function executeStep(page, step, settings, snapshot, secrets, downloadLedger) {
-  const root = await stepRoot(page, step.frame);
-  const timeout = settings.browser.actionTimeoutMs;
-  if (step.action === "wait_for_text") {
-    await root.getByText(step.text, { exact: false }).first().waitFor({ state: "visible", timeout });
-    return { action: step.action };
-  }
-  if (step.action === "wait_for_condition") {
-    await root.waitForLoadState("networkidle", { timeout });
-    return { action: step.action, condition: step.condition };
-  }
-  if (step.action === "press_key") {
-    if (step.frame) await root.locator("body").press(step.key, { timeout });
-    else await page.keyboard.press(step.key);
-    return { action: step.action, key: step.key };
-  }
-  if (step.action === "like_comment" || step.action === "unlike_comment") {
-    return { action: step.action, result: await reactToComment(root, step) };
-  }
-  if (step.action === "audit_accessibility") {
-    return {
-      action: step.action,
-      accessibility_audit: await runAccessibilityAudit(page, step.standard, settings),
-    };
-  }
-  if (step.action === "upload_file") {
-    const files = await uploadFiles(step, settings);
-    if (step.target === "input") {
-      const targetRoot = await scopedRoot(root, step.within);
-      const input = targetRoot.getByLabel(step.label, { exact: true });
-      const count = await input.count();
-      const control = indexedTarget(input, count, step.index, "accessible file input");
-      await control.setInputFiles(files, { timeout });
-    } else {
-      const control = await namedTarget(root, step.role, step.name, snapshot, secrets, step);
-      if (step.target === "button") {
+async function executeStep(page, step, settings, snapshot, secrets, downloadLedger) {
+  const root = await stepRoot(page, step.frame);
+  const timeout = step.timeoutMs ?? settings.browser.actionTimeoutMs;
+  if (step.action === "wait_for_text") {
+    await root.getByText(step.text, { exact: false }).first().waitFor({ state: "visible", timeout });
+    return { action: step.action };
+  }
+  if (step.action === "wait_for_condition") {
+    if (step.condition === "network_idle") {
+      await root.waitForLoadState("networkidle", { timeout });
+    } else if (step.condition === "text_hidden") {
+      await root.getByText(step.text, { exact: false }).first().waitFor({ state: "hidden", timeout });
+    } else {
+      const { locator, count } = await roleLocator(root, step.role, step.name, undefined, timeout);
+      if (count > 1 && step.index === undefined) throw new JevBrowserError("hidden condition target is ambiguous; provide an index");
+      if (step.index !== undefined && step.index >= count) return { action: step.action, condition: step.condition };
+      await (step.index === undefined ? locator.first() : locator.nth(step.index)).waitFor({ state: "hidden", timeout });
+    }
+    return { action: step.action, condition: step.condition };
+  }
+  if (step.action === "press_key") {
+    await root.locator("body").press(step.key, { timeout });
+    return { action: step.action, key: step.key };
+  }
+  if (step.action === "like_comment" || step.action === "unlike_comment") {
+    return { action: step.action, result: await reactToComment(root, step, timeout) };
+  }
+  if (step.action === "audit_accessibility") {
+    return {
+      action: step.action,
+      accessibility_audit: await withTimeout(
+        runAccessibilityAudit(page, step.standard, settings),
+        timeout,
+        `accessibility audit exceeded the ${timeout}ms step timeout`,
+      ),
+    };
+  }
+  if (step.action === "upload_file") {
+    const files = await uploadFiles(step, settings);
+    if (step.target === "input") {
+      const targetRoot = await scopedRoot(root, step.within, timeout);
+      const input = targetRoot.getByLabel(step.label, { exact: true });
+      const selected = step.index === undefined ? input.first() : input.nth(step.index);
+      if (typeof selected?.waitFor === "function") {
+        try {
+          await selected.waitFor({ state: "attached", timeout });
+        } catch (cause) {
+          throw attachStepCause(new JevBrowserError("accessible file input did not appear before the configured timeout"), cause);
+        }
+      }
+      const count = await input.count();
+      const control = indexedTarget(input, count, step.index, "accessible file input");
+      await control.setInputFiles(files, { timeout });
+    } else {
+      const control = await namedTarget(root, step.role, step.name, snapshot, secrets, { ...step, timeoutMs: timeout });
+      if (step.target === "button") {
         const [chooser] = await Promise.all([
           page.waitForEvent("filechooser", { timeout }),
           control.click({ timeout }),
         ]);
-        await chooser.setFiles(files);
+        await withTimeout(chooser.setFiles(files), timeout, `file chooser exceeded the ${timeout}ms step timeout`);
       } else {
         await control.drop({ files }, { timeout });
       }
     }
     return { action: step.action, target: step.target, file_count: files.length };
-  }
-  if (step.action === "assert_hidden") {
-    const { locator, count } = await roleLocator(root, step.role, step.name, step.within);
-    if (step.index === undefined ? count > 0 : step.index < count) {
-      throw new JevBrowserError(`assert_hidden failed for ${step.role}${step.name ? ` ${JSON.stringify(redact(step.name, secrets))}` : ""}`);
-    }
-    return { action: step.action, asserted: true };
-  }
-  if (step.action === "assert_visible" && step.name === undefined) {
-    const { locator, count } = await roleLocator(root, step.role, undefined, step.within);
-    if (count === 0 || (step.index !== undefined && step.index >= count)) {
-      throw new JevBrowserError(`assert_visible failed for ${step.role}`);
-    }
-    if (step.index !== undefined && !(await locator.nth(step.index).isVisible())) {
-      throw new JevBrowserError(`assert_visible failed for ${step.role}`);
-    }
-    return { action: step.action, asserted: true };
-  }
-  const control = await namedTarget(root, step.role, step.name, snapshot, secrets, step);
+  }
+  if (step.action === "assert_hidden") {
+    const { locator, count } = await roleLocator(root, step.role, step.name, step.within, timeout);
+    if (step.index !== undefined) {
+      if (step.index < count) await locator.nth(step.index).waitFor({ state: "hidden", timeout });
+    } else {
+      for (let index = 0; index < count; index += 1) await locator.nth(index).waitFor({ state: "hidden", timeout });
+    }
+    return { action: step.action, asserted: true };
+  }
+  if (step.action === "assert_visible" && step.name === undefined) {
+    await visibleRoleTarget(root, step, timeout, `assert_visible ${step.role}`);
+    return { action: step.action, asserted: true };
+  }
+  if (step.action === "assert_text" && step.name === undefined) {
+    const { locator, count, target } = await visibleRoleTarget(root, step, timeout, `assert_text ${step.role}`);
+    if (step.index === undefined && count !== 1) {
+      throw new JevBrowserError(`assert_text ${step.role} must match exactly one accessible control; found ${count}`);
+    }
+    const control = step.index === undefined ? locator : target;
+    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 ${step.role}`);
+    }
+    return { action: step.action, asserted: true };
+  }
+  const control = await namedTarget(root, step.role, step.name, snapshot, secrets, { ...step, timeoutMs: timeout });
   if (step.action === "click") {
     if (!step.expectDownload) {
       await control.click({ timeout });
@@ -756,9 +987,16 @@ async function executeStep(page, step, settings, snapshot, secrets, downloadLedg
       name: step.name,
       downloaded_file: await saveDownload(download, settings, downloadLedger),
     };
-  }
-  if (step.action === "type") {
-    await control.fill(step.text, { timeout });
+  }
+  if (step.action === "type") {
+    if (step.mode === "keys") {
+      await control.fill("", { timeout });
+      await control.pressSequentially(step.text, { delay: settings.browser.keyDelayMs, timeout });
+      if (step.blur) await control.press("Tab", { timeout });
+    } else {
+      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 (step.action === "select_option") {
@@ -789,11 +1027,12 @@ async function executeStep(page, step, settings, snapshot, secrets, downloadLedg
   throw new JevBrowserError("unsupported browser action");
 }
 
-function flowTimings(started, browserSessionMs, navigationMs, initialSnapshotMs, jevDecisionMs, browserPlanMs) {
-  return {
-    browser_session_ms: Math.round(browserSessionMs * 10) / 10,
-    navigation_ms: Math.round(navigationMs * 10) / 10,
-    initial_snapshot_ms: Math.round(initialSnapshotMs * 10) / 10,
+function flowTimings(started, browserSessionMs, navigationMs, initialSnapshotMs, readyMs, jevDecisionMs, browserPlanMs) {
+  return {
+    browser_session_ms: Math.round(browserSessionMs * 10) / 10,
+    navigation_ms: Math.round(navigationMs * 10) / 10,
+    initial_snapshot_ms: Math.round(initialSnapshotMs * 10) / 10,
+    ready_ms: Math.round(readyMs * 10) / 10,
     jev_decision_ms: Math.round(jevDecisionMs * 10) / 10,
     browser_plan_ms: Math.round(browserPlanMs * 10) / 10,
     total_ms: Math.round((performance.now() - started) * 10) / 10,
@@ -825,10 +1064,11 @@ function sanitizeDiagnosticText(value, secrets, limit) {
   return result.slice(0, limit);
 }
 
-function createDiagnostics(page, options, settings, secrets) {
-  const diagnostics = { console_errors: [], network_failures: [] };
-  const limit = settings.jev.maxDiagnosticItems;
-  const messageLimit = settings.jev.maxDiagnosticChars;
+function createDiagnostics(page, options, settings, secrets) {
+  const diagnostics = { console_errors: [], network_failures: [] };
+  const pendingBodies = [];
+  const limit = settings.jev.maxDiagnosticItems;
+  const messageLimit = settings.jev.maxDiagnosticChars;
   const onConsole = (message) => {
     if (message.type() !== "error") return;
     addDiagnostic(diagnostics.console_errors, sanitizeDiagnosticText(message.text(), secrets, messageLimit), limit);
@@ -836,14 +1076,41 @@ function createDiagnostics(page, options, settings, secrets) {
   const onPageError = (error) => {
     addDiagnostic(diagnostics.console_errors, sanitizeDiagnosticText(error.message || error.name, secrets, messageLimit), limit);
   };
-  const onResponse = (response) => {
-    if (response.status() < 400) return;
-    const request = response.request();
-    addDiagnostic(diagnostics.network_failures, {
-      url: evidenceUrl(response.url(), secrets, messageLimit),
-      method: request.method(),
-      status: response.status(),
-    }, limit);
+  const addResponseMessage = async (response, entry) => {
+    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;
+      const body = await withTimeout(
+        response.body(),
+        settings.browser.actionTimeoutMs,
+        "error response body read timed out",
+      );
+      if (body.length > settings.browser.maxNetworkErrorBodyBytes) return;
+      const payload = JSON.parse(body.toString("utf8"));
+      if (!isRecord(payload) || typeof payload.message !== "string") 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.
+    }
+  };
+  const onResponse = (response) => {
+    if (response.status() < 400) return;
+    const request = response.request();
+    const failure = {
+      url: evidenceUrl(response.url(), secrets, messageLimit),
+      method: request.method(),
+      status: response.status(),
+    };
+    addDiagnostic(diagnostics.network_failures, failure, limit);
+    if (options.captureNetworkErrorBodies && diagnostics.network_failures.includes(failure)) {
+      pendingBodies.push(addResponseMessage(response, failure));
+    }
   };
   const onRequestFailed = (request) => {
     addDiagnostic(diagnostics.network_failures, {
@@ -856,20 +1123,41 @@ function createDiagnostics(page, options, settings, secrets) {
     page.on("console", onConsole);
     page.on("pageerror", onPageError);
   }
-  if (options.captureNetworkErrors) {
-    page.on("response", onResponse);
-    page.on("requestfailed", onRequestFailed);
+  if (options.captureNetworkErrors || options.captureNetworkErrorBodies) {
+    page.on("response", onResponse);
+  }
+  if (options.captureNetworkErrors) {
+    page.on("requestfailed", onRequestFailed);
   }
   return {
     diagnostics,
-    dispose() {
+    async dispose() {
       page.off("console", onConsole);
       page.off("pageerror", onPageError);
-      page.off("response", onResponse);
-      page.off("requestfailed", onRequestFailed);
+      page.off("response", onResponse);
+      page.off("requestfailed", onRequestFailed);
+      await Promise.allSettled(pendingBodies);
     },
-  };
-}
+  };
+}
+
+function stepFailureText(error, secrets, limit) {
+  const value = error?.message || error?.name || "BrowserError";
+  const timeout = String(value).match(/Timeout\s+\d+ms exceeded\./i);
+  return sanitizeDiagnosticText(timeout ? timeout[0] : String(value).split(/\r?\n/, 1)[0], secrets, limit);
+}
+
+function failedStepDetails(step, index, error, settings, secrets) {
+  const details = {
+    index,
+    action: step.action,
+  };
+  if (step.role !== undefined) details.role = step.role;
+  if (step.name !== undefined) details.name = redact(step.name, secrets);
+  details.timeout_ms = step.timeoutMs ?? settings.browser.actionTimeoutMs;
+  details.error = stepFailureText(error?.stepCause || error, secrets, settings.jev.maxDiagnosticChars);
+  return details;
+}
 
 function trackerUrl(url, settings) {
   let hostname;
@@ -927,7 +1215,8 @@ export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, ca
   const url = validateUrl(initialUrl);
   const plans = validateCandidatePlans(candidatePlans, settings);
   const options = resolveFlowOptions(rawOptions, settings);
-  const secrets = planSecrets(plans);
+  const secrets = [...planSecrets(plans), settings.env?.[settings.jev.credentialEnv]].filter(Boolean)
+    .sort((left, right) => right.length - left.length);
   const started = performance.now();
   const browser = await browserPool.getPage();
   const browserSessionMs = browser.sessionMs;
@@ -942,11 +1231,12 @@ export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, ca
     jev_decisions: 0,
     steps: [],
     downloaded_files: [],
-    accessibility_audits: [],
-    final_snapshot: "",
-  };
+    accessibility_audits: [],
+    warnings: [],
+    final_snapshot: "",
+  };
   const downloadLedger = { count: 0, bytes: 0 };
-  const timings = { navigationMs: 0, initialSnapshotMs: 0, decisionMs: 0, browserPlanMs: 0 };
+  const timings = { navigationMs: 0, initialSnapshotMs: 0, readyMs: 0, decisionMs: 0, browserPlanMs: 0 };
   let unroute;
   let tracingStarted = false;
   let tracePath;
@@ -964,12 +1254,37 @@ export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, ca
       }
     }
 
-    const navigationStarted = performance.now();
-    await page.goto(url, { waitUntil: "domcontentloaded", timeout: settings.browser.actionTimeoutMs * 4 });
-    timings.navigationMs = performance.now() - navigationStarted;
-    const snapshotStarted = performance.now();
-    result.final_snapshot = await snapshotPage(page, settings, secrets, options.snapshotScope);
-    timings.initialSnapshotMs = performance.now() - snapshotStarted;
+    let reusedPage = false;
+    if (options.reusePage) {
+      const currentUrl = page.url();
+      if (currentUrl && currentUrl !== "about:blank") {
+        let currentOrigin;
+        try {
+          currentOrigin = new URL(currentUrl).origin;
+        } catch {
+          currentOrigin = "";
+        }
+        if (currentOrigin !== new URL(url).origin) {
+          throw new JevBrowserError("reuse_page requires the current page to be on the same origin as initial_url");
+        }
+        reusedPage = true;
+      }
+    }
+    if (!reusedPage) {
+      const navigationStarted = performance.now();
+      await page.goto(url, { waitUntil: "domcontentloaded", timeout: settings.browser.actionTimeoutMs * 4 });
+      timings.navigationMs = performance.now() - navigationStarted;
+    }
+    const snapshotStarted = performance.now();
+    try {
+      const readiness = await waitForPageReady(page, options, settings, secrets);
+      result.final_snapshot = readiness.snapshot;
+      timings.readyMs = readiness.readyMs;
+    } catch (error) {
+      timings.readyMs = error.readyMs || performance.now() - snapshotStarted;
+      throw error;
+    }
+    timings.initialSnapshotMs = performance.now() - snapshotStarted;
 
     const initialVisible = containsPhrase(result.final_snapshot, outcome);
     const allSteps = Object.values(plans).flatMap(({ steps }) => steps);
@@ -1018,16 +1333,17 @@ export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, ca
 
       if (planId) {
         const plan = plans[planId];
-        const trace = [];
-        let failure = "";
-        let snapshot = result.final_snapshot;
+        const trace = [];
+        let failure = "";
+        let failedStep;
+        let snapshot = result.final_snapshot;
         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()) {
           try {
-            const traceStep = await executeStep(page, step, settings, snapshot, secrets, downloadLedger);
+            const traceStep = await executeStep(page, step, settings, snapshot, secrets, downloadLedger);
             traceStep.step = String(index + 1);
             trace.push(traceStep);
             if (traceStep.downloaded_file) result.downloaded_files.push(traceStep.downloaded_file);
@@ -1037,14 +1353,15 @@ export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, ca
                 failure = `accessibility audit reported ${traceStep.accessibility_audit.violations_count} violation(s)`;
               }
             }
-            snapshot = await snapshotPage(page, settings, secrets, options.snapshotScope);
+            snapshot = await snapshotAfterStep(page, settings, secrets, options.snapshotScope, snapshot, index + 1, result.warnings);
             if (failure) break;
             if (!runAllSteps && containsPhrase(snapshot, outcome)) break;
-          } catch (error) {
-            failure = error instanceof JevBrowserError
-              ? error.message
-              : `Playwright action failed (${error?.name || "BrowserError"})`;
-            break;
+          } catch (error) {
+            failure = error instanceof JevBrowserError
+              ? error.message
+              : `Playwright action failed (${error?.name || "BrowserError"})`;
+            failedStep = failedStepDetails(step, index, error, settings, secrets);
+            break;
           }
         }
         timings.browserPlanMs = performance.now() - planStarted;
@@ -1063,9 +1380,12 @@ export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, ca
         result.acceptance_criteria_met = !failure && (visible || assertionsPassed || auditsPassed || downloadsPassed);
         result.selected_plan = planId;
         result.steps_executed = trace.length;
-        result.steps = trace;
-        result.final_snapshot = snapshot;
-        if (failure) result.reason = failure;
+        result.steps = trace;
+        result.final_snapshot = snapshot;
+        if (failure) {
+          result.reason = failure;
+          result.failed_step = failedStep;
+        }
         if (assertionCount > 0) result.assertions_passed = assertionsPassed;
         if (auditCount > 0) result.accessibility_audit_passed = auditsPassed;
         if (decision) {
@@ -1080,7 +1400,7 @@ export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, ca
       ? error.message
       : `Playwright flow failed (${error?.name || "BrowserError"})`;
     try {
-      result.final_snapshot = await snapshotPage(page, settings, secrets, options.snapshotScope);
+      result.final_snapshot = await snapshotPage(page, settings, secrets, options.snapshotScope, { allowEmpty: true });
       result.expected_outcome_visible = containsPhrase(result.final_snapshot, outcome);
     } catch {
       // Keep the last accessible snapshot when the page is closing or unavailable.
@@ -1112,13 +1432,13 @@ export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, ca
     } catch {
       artifactErrors.push("tracker blocking cleanup failed");
     }
-    capture.dispose();
+    await capture.dispose();
   }
   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.timings_ms = flowTimings(started, browserSessionMs, timings.navigationMs, timings.initialSnapshotMs, timings.decisionMs, timings.browserPlanMs);
+  result.timings_ms = flowTimings(started, browserSessionMs, timings.navigationMs, timings.initialSnapshotMs, timings.readyMs, timings.decisionMs, timings.browserPlanMs);
   return redactObject(result, secrets);
 }