@diegosouzacdv/jev-browser-mcp 0.4.1 → 0.4.2

package/README.md

@@ -100,7 +100,10 @@ Cada plano pode usar:
   o MCP ignora diálogos visualmente ocultos, inclusive os que ficaram no DOM
   com `opacity: 0`;
 - `name: ""` com `index` não negativo para controles sem nome. O resultado
-  inclui um aviso porque a posição pode mudar entre execuções;
+  inclui um aviso porque a posição pode mudar entre execuções. O índice é
+  zero-based para o mesmo papel e segue o localizador Playwright
+  `{role, name: ""}`; controles desabilitados não aparecem no diagnóstico, mas
+  continuam contando para que o índice aponte ao controle correto;
 - `selector` com CSS ou XPath como último recurso. O MCP identifica essa escolha
   em `warnings`; não é permitido enviar JavaScript nem coordenadas;
 - `timeout_seconds` opcional em cada etapa, limitado pela configuração central;
@@ -108,8 +111,10 @@ Cada plano pode usar:
   `blur: true` para desfocar o campo e `sensitive: false` para permitir que o
   valor apareça nas evidências. Nesse modo, `\n` envia Enter e `\t` envia Tab;
 - `wait_for_text` e `wait_for_condition` (`network_idle`, `hidden` ou
-  `text_hidden`); `network_idle` aceita `url_contains` para aguardar só as
-  requisições correspondentes;
+  `text_hidden`). `wait_for_text` aceita `fail_on: {"role":"alert"}` para
+  interromper a espera assim que um alerta visível aparecer e incluir seu texto
+  no erro. `network_idle` aceita `url_contains` para aguardar só as requisições
+  correspondentes;
 - `press` (o alias legado `press_key` também é aceito) com `PageDown`, `PageUp`,
   `Home`, `End`, setas, `Enter`, `Escape`, `Tab` ou `Shift+Tab`. Sem alvo,
   envia a tecla ao elemento focado; com alvo, usa o localizador informado;
@@ -158,9 +163,12 @@ Exemplos para controles legados sem nome acessível:
 {"action":"click","selector":"#save-document"}
 ```
 
-O reconhecimento retorna `unnamed_controls` com papel, posição, rótulo mais
-próximo e um trecho HTML sanitizado dos controles interativos sem nome. O
-snapshot também resume campos de formulário com `id`, `name`, valor, estado
+O reconhecimento retorna `unnamed_controls_initial` e
+`unnamed_controls_final`, cada um com papel, índice Playwright por papel, rótulo
+mais próximo e um trecho HTML sanitizado dos controles visíveis e habilitados
+sem nome. `unnamed_controls` continua disponível como alias da lista final. O
+placeholder conta como nome acessível. O snapshot também resume campos de
+formulário com `id`, `name`, valor, estado
 desabilitado, rótulo e índice zero-based entre campos de mesmo nome. Valores
 sensíveis, como senha, token e cartão, são ocultados. `snapshot_include_hidden`
 é `false` por padrão; defina `true` somente quando precisar inspecionar campos
@@ -321,8 +329,16 @@ esse resultado e `expected_outcome_visible` continua descrevendo somente o
 texto global. `incomplete` significa que nenhum critério foi comprovado;
 confiança do Jev não substitui essa verificação. `timings_ms.ready_ms` mede a
 espera da SPA; `warnings` registra capturas vazias durante transições; e
-`failed_step` identifica índice, ação, alvo, timeout e erro resumido quando uma
-etapa falha.
+`failed_step` identifica índice, ação, localizador, timeout e erro resumido
+quando uma etapa falha. Cada etapa executada também registra a composição do
+localizador usado e, quando disponível, `resolved_target` com tag, `id`, papel
+e nome acessível do elemento resolvido. Etapas `type` só incluem o valor final
+do campo quando `sensitive: false`.
+
+Com `capture_network_error_bodies: true`, respostas JSON de erro da mesma
+origem são capturadas mesmo quando usam transferência chunked e não enviam
+`Content-Length`. Corpos acima do limite, com formato inválido ou que não
+podem ser lidos com segurança são omitidos e explicados em `warnings`.
 
 `jev_browser_mcp.browser.max_action_timeout_seconds` limita esperas por ações,
 seletores e condições. `JEV_BROWSER_UPLOAD_ROOT` libera uploads somente dentro

package/docs/jev-browser-mcp.md

@@ -100,7 +100,10 @@ Cada plano pode usar:
   o MCP ignora diálogos visualmente ocultos, inclusive os que ficaram no DOM
   com `opacity: 0`;
 - `name: ""` com `index` não negativo para controles sem nome. O resultado
-  inclui um aviso porque a posição pode mudar entre execuções;
+  inclui um aviso porque a posição pode mudar entre execuções. O índice é
+  zero-based para o mesmo papel e segue o localizador Playwright
+  `{role, name: ""}`; controles desabilitados não aparecem no diagnóstico, mas
+  continuam contando para que o índice aponte ao controle correto;
 - `selector` com CSS ou XPath como último recurso. O MCP identifica essa escolha
   em `warnings`; não é permitido enviar JavaScript nem coordenadas;
 - `timeout_seconds` opcional em cada etapa, limitado pela configuração central;
@@ -108,8 +111,10 @@ Cada plano pode usar:
   `blur: true` para desfocar o campo e `sensitive: false` para permitir que o
   valor apareça nas evidências. Nesse modo, `\n` envia Enter e `\t` envia Tab;
 - `wait_for_text` e `wait_for_condition` (`network_idle`, `hidden` ou
-  `text_hidden`); `network_idle` aceita `url_contains` para aguardar só as
-  requisições correspondentes;
+  `text_hidden`). `wait_for_text` aceita `fail_on: {"role":"alert"}` para
+  interromper a espera assim que um alerta visível aparecer e incluir seu texto
+  no erro. `network_idle` aceita `url_contains` para aguardar só as requisições
+  correspondentes;
 - `press` (o alias legado `press_key` também é aceito) com `PageDown`, `PageUp`,
   `Home`, `End`, setas, `Enter`, `Escape`, `Tab` ou `Shift+Tab`. Sem alvo,
   envia a tecla ao elemento focado; com alvo, usa o localizador informado;
@@ -158,9 +163,12 @@ Exemplos para controles legados sem nome acessível:
 {"action":"click","selector":"#save-document"}
 ```
 
-O reconhecimento retorna `unnamed_controls` com papel, posição, rótulo mais
-próximo e um trecho HTML sanitizado dos controles interativos sem nome. O
-snapshot também resume campos de formulário com `id`, `name`, valor, estado
+O reconhecimento retorna `unnamed_controls_initial` e
+`unnamed_controls_final`, cada um com papel, índice Playwright por papel, rótulo
+mais próximo e um trecho HTML sanitizado dos controles visíveis e habilitados
+sem nome. `unnamed_controls` continua disponível como alias da lista final. O
+placeholder conta como nome acessível. O snapshot também resume campos de
+formulário com `id`, `name`, valor, estado
 desabilitado, rótulo e índice zero-based entre campos de mesmo nome. Valores
 sensíveis, como senha, token e cartão, são ocultados. `snapshot_include_hidden`
 é `false` por padrão; defina `true` somente quando precisar inspecionar campos
@@ -321,8 +329,16 @@ esse resultado e `expected_outcome_visible` continua descrevendo somente o
 texto global. `incomplete` significa que nenhum critério foi comprovado;
 confiança do Jev não substitui essa verificação. `timings_ms.ready_ms` mede a
 espera da SPA; `warnings` registra capturas vazias durante transições; e
-`failed_step` identifica índice, ação, alvo, timeout e erro resumido quando uma
-etapa falha.
+`failed_step` identifica índice, ação, localizador, timeout e erro resumido
+quando uma etapa falha. Cada etapa executada também registra a composição do
+localizador usado e, quando disponível, `resolved_target` com tag, `id`, papel
+e nome acessível do elemento resolvido. Etapas `type` só incluem o valor final
+do campo quando `sensitive: false`.
+
+Com `capture_network_error_bodies: true`, respostas JSON de erro da mesma
+origem são capturadas mesmo quando usam transferência chunked e não enviam
+`Content-Length`. Corpos acima do limite, com formato inválido ou que não
+podem ser lidos com segurança são omitidos e explicados em `warnings`.
 
 `jev_browser_mcp.browser.max_action_timeout_seconds` limita esperas por ações,
 seletores e condições. `JEV_BROWSER_UPLOAD_ROOT` libera uploads somente dentro

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

@@ -102,7 +102,7 @@ export function validateCandidatePlans(candidatePlans, settings) {
       const schemas = {
         click: { required: [], optional: [...semanticTarget, "expect_download", "timeout_seconds"] },
         type: { required: ["text"], optional: [...semanticTarget, "blur", "mode", "sensitive", "timeout_seconds"] },
-        wait_for_text: { required: ["text"], optional: ["frame", "comment", "timeout_seconds"] },
+        wait_for_text: { required: ["text"], optional: ["frame", "comment", "fail_on", "timeout_seconds"] },
         wait_for_condition: { required: ["condition"], optional: [...semanticTarget, "url_contains", "timeout_seconds"] },
         press: { required: ["key"], optional: [...semanticTarget, "timeout_seconds"] },
         select_option: { required: ["option"], optional: [...semanticTarget, "timeout_seconds"] },
@@ -232,9 +232,20 @@ export function validateCandidatePlans(candidatePlans, settings) {
         step.blur = rawStep.blur ?? false;
         step.sensitive = rawStep.sensitive ?? true;
       }
-      if (action === "wait_for_text") {
-        step.text = requiredText(rawStep.text, "wait text", settings.jev.maxActionDescriptionChars);
-      }
+      if (action === "wait_for_text") {
+        step.text = requiredText(rawStep.text, "wait text", settings.jev.maxActionDescriptionChars);
+        if (rawStep.fail_on !== undefined) {
+          if (!isRecord(rawStep.fail_on)) throw new JevBrowserError("wait_for_text fail_on must be an object with a role");
+          exactKeys(rawStep.fail_on, ["role"], ["name"], "wait_for_text fail_on");
+          if (typeof rawStep.fail_on.role !== "string" || !ASSERT_ROLES.has(rawStep.fail_on.role)) {
+            throw new JevBrowserError(`wait_for_text fail_on role must be one of: ${[...ASSERT_ROLES].join(", ")}`);
+          }
+          step.failOn = { role: rawStep.fail_on.role };
+          if (rawStep.fail_on.name !== undefined) {
+            step.failOn.name = requiredText(rawStep.fail_on.name, "fail_on accessible name", settings.jev.maxActionDescriptionChars);
+          }
+        }
+      }
       if (action === "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");
@@ -569,6 +580,59 @@ async function snapshotPage(page, settings, secrets, snapshotScope = "body", { a
   return compactSnapshot(redact(combined, secrets), settings.jev.maxSnapshotChars);
 }
 
+async function collectUnnamedControls(root, roles, settings, secrets) {
+  const unnamedControls = [];
+  for (const role of roles) {
+    if (unnamedControls.length >= settings.jev.maxDiagnosticItems) break;
+    const locator = root.getByRole(role, { name: "", exact: true });
+    const controls = await locator.evaluateAll((elements, maxChars) => {
+      const textOf = (element) => (element?.innerText || element?.textContent || "").replace(/\s+/g, " ").trim();
+      const nearestLabel = (element) => {
+        const labels = [...element.ownerDocument.querySelectorAll("label")]
+          .filter((label) => label.compareDocumentPosition(element) & Node.DOCUMENT_POSITION_FOLLOWING).reverse();
+        for (const label of labels) {
+          const controlsBetween = [...element.ownerDocument.querySelectorAll("input,textarea,select,[role=textbox],[role=combobox]")]
+            .some((control) => (label.compareDocumentPosition(control) & Node.DOCUMENT_POSITION_FOLLOWING)
+              && (control.compareDocumentPosition(element) & Node.DOCUMENT_POSITION_FOLLOWING));
+          if (!controlsBetween) return textOf(label);
+        }
+        return "";
+      };
+      const allowedAttributes = new Set(["id", "name", "type", "title", "aria-label", "aria-labelledby", "placeholder", "role", "data-testid", "href", "alt", "disabled"]);
+      const safeHtml = (element) => {
+        const clone = element.cloneNode(true);
+        for (const node of [clone, ...clone.querySelectorAll("*")]) {
+          for (const attribute of [...node.attributes]) if (!allowedAttributes.has(attribute.name.toLowerCase())) node.removeAttribute(attribute.name);
+          if (node.matches("input,textarea")) {
+            node.removeAttribute("value");
+            if (node.matches("textarea")) node.textContent = "";
+          }
+        }
+        clone.querySelectorAll("script,style").forEach((node) => node.remove());
+        return clone.outerHTML.replace(/\s+/g, " ").slice(0, maxChars);
+      };
+      return elements.map((element, index) => ({
+        index,
+        disabled: Boolean(element.disabled || element.matches(":disabled") || element.getAttribute("aria-disabled") === "true"),
+        nearestLabel: nearestLabel(element),
+        html: safeHtml(element),
+      }));
+    }, settings.jev.maxDiagnosticChars);
+    for (const control of controls) {
+      if (control.disabled) continue;
+      unnamedControls.push({
+        role,
+        index: control.index,
+        name: "",
+        nearest_label: redact(control.nearestLabel, secrets),
+        html: redact(control.html, secrets),
+      });
+      if (unnamedControls.length >= settings.jev.maxDiagnosticItems) break;
+    }
+  }
+  return unnamedControls;
+}
+
 async function enrichSnapshot(page, snapshot, settings, secrets, snapshotScope, includeHidden) {
   let root;
   try {
@@ -603,6 +667,7 @@ async function enrichSnapshot(page, snapshot, settings, secrets, snapshotScope,
       };
       const accessibleName = (element) => element.getAttribute("aria-label") || referencedName(element)
         || [...(element.labels || [])].map(textOf).filter(Boolean).join(" ")
+        || (element.matches("input,textarea") ? element.getAttribute("placeholder") : "")
         || element.getAttribute("alt") || (element.matches("a,button,[role=button],[role=link],[role=menuitem]") ? textOf(element) : "")
         || element.getAttribute("title") || "";
       const sensitiveField = (element) => {
@@ -642,16 +707,21 @@ async function enrichSnapshot(page, snapshot, settings, secrets, snapshotScope,
         clone.querySelectorAll("script,style").forEach((node) => node.remove());
         return clone.outerHTML.replace(/\s+/g, " ").slice(0, limits.maxChars);
       };
-      const interactive = [...scope.querySelectorAll("a,button,input:not([type=hidden]),select,textarea,[role=button],[role=link],[role=menuitem]")]
-        .filter((element) => limits.includeHidden || isVisible(element));
-      const unnamed = interactive.filter((element) => !accessibleName(element).trim()).slice(0, limits.maxItems)
-        .map((element, index) => ({
-          role: element.getAttribute("role") || element.localName,
-          index,
-          nearestLabel: nearestLabel(element),
-          html: safeHtml(element),
-        }));
-      return { formLines, unnamed };
+      const roleForInteractive = (element) => {
+        const explicitRole = element.getAttribute("role");
+        if (explicitRole) return explicitRole;
+        if (element.matches("a[href]")) return "link";
+        if (element.matches("button,input[type=button],input[type=submit],input[type=reset]")) return "button";
+        if (element.matches("input[type=checkbox]")) return "checkbox";
+        if (element.matches("input[type=radio]")) return "radio";
+        if (element.matches("input[type=search]")) return "searchbox";
+        if (element.matches("input:not([type=hidden]),textarea")) return "textbox";
+        if (element.matches("select")) return element.multiple ? "listbox" : "combobox";
+        return "";
+      };
+      const interactive = [...scope.querySelectorAll("a,button,input:not([type=hidden]),select,textarea,[role=button],[role=link],[role=menuitem],[role=textbox],[role=searchbox],[role=combobox],[role=checkbox],[role=radio]")];
+      const interactiveRoles = [...new Set(interactive.map(roleForInteractive).filter(Boolean))];
+      return { formLines, interactiveRoles };
     }, {
       includeHidden,
       maxItems: settings.jev.maxDiagnosticItems,
@@ -659,16 +729,13 @@ async function enrichSnapshot(page, snapshot, settings, secrets, snapshotScope,
     });
     const sections = [];
     if (details.formLines.length) sections.push(`[form controls: ids, names, values (password/token fields redacted), disabled state and same-name index]\n${details.formLines.join("\n")}`);
-    if (details.unnamed.length) {
-      sections.push(`[interactive controls without accessible names]\n${details.unnamed.map(({ role, index, nearestLabel, html }) =>
-        `- ${role} index=${index}; nearest_label=${JSON.stringify(nearestLabel)}; html=${html}`).join("\n")}`);
+    const unnamedControls = typeof root.getByRole === "function"
+      ? await collectUnnamedControls(root, details.interactiveRoles, settings, secrets)
+      : [];
+    if (unnamedControls.length) {
+      sections.push(`[interactive controls without accessible names; indices match Playwright role/name locators, disabled controls omitted]\n${unnamedControls.map(({ role, index, nearest_label, html }) =>
+        `- ${role} name=${JSON.stringify("")} index=${index}; nearest_label=${JSON.stringify(nearest_label)}; html=${html}`).join("\n")}`);
     }
-    const unnamedControls = details.unnamed.map(({ role, index, nearestLabel, html }) => ({
-      role,
-      index,
-      nearest_label: redact(nearestLabel, secrets),
-      html: redact(html, secrets),
-    }));
     return {
       snapshot: compactSnapshot(redact([snapshot, ...sections].join("\n\n"), secrets), settings.jev.maxSnapshotChars),
       unnamedControls,
@@ -919,6 +986,38 @@ function locatorAt(locator, index) {
   throw new JevBrowserError(`locator does not support occurrence index ${index}`);
 }
 
+async function firstVisibleMatch(locator) {
+  const count = await locator.count();
+  for (let index = 0; index < count; index += 1) {
+    const candidate = locatorAt(locator, index);
+    if (await isActuallyVisible(candidate)) return candidate;
+  }
+  return undefined;
+}
+
+async function waitForTextOrFailure(root, step, timeout, settings, secrets) {
+  const expected = root.getByText(step.text, { exact: false });
+  const failure = root.getByRole(step.failOn.role, roleOptions(step.failOn));
+  const deadline = performance.now() + timeout;
+  while (true) {
+    const failedMatch = await firstVisibleMatch(failure);
+    if (failedMatch) {
+      const visibleText = await failedMatch.innerText().catch(() => "");
+      const message = sanitizeDiagnosticText(visibleText || step.failOn.name || step.failOn.role, secrets, settings.jev.maxDiagnosticChars);
+      const failureTarget = `role ${step.failOn.role}${step.failOn.name ? ` ${JSON.stringify(redact(step.failOn.name, secrets))}` : ""}`;
+      throw new JevBrowserError(
+        `wait_for_text ${JSON.stringify(redact(step.text, secrets))} stopped because ${failureTarget} appeared: ${JSON.stringify(message)}`,
+      );
+    }
+    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`);
+    }
+    await new Promise((resolve) => setTimeout(resolve, Math.min(settings.browser.visibilityPollMs, left)));
+  }
+}
+
 async function visibleIndexes(locator, timeout, description, settings, { allowNone = false } = {}) {
   const deadline = performance.now() + timeout;
   while (true) {
@@ -1027,11 +1126,70 @@ async function targetLocator(root, step, timeout, settings) {
 }
 
 function describeTarget(step, secrets) {
-  if (step.role) return `role ${step.role}${step.name === undefined ? "" : ` ${JSON.stringify(redact(step.name, secrets))}`}`;
-  const field = TARGET_LOCATOR_FIELDS.find((candidate) => step[LOCATOR_STEP_KEYS[candidate]] !== undefined);
-  if (field) return `${field} ${JSON.stringify(redact(step[LOCATOR_STEP_KEYS[field]], secrets))}`;
-  if (step.near) return `target near text ${JSON.stringify(redact(step.near.text, secrets))}`;
-  return "focused element";
+  const parts = [];
+  if (step.role) {
+    const name = step.name === undefined ? "" : ` ${JSON.stringify(redact(step.name, secrets))}`;
+    parts.push(`role ${step.role}${name}`);
+  }
+  for (const field of TARGET_LOCATOR_FIELDS) {
+    const value = step[LOCATOR_STEP_KEYS[field]];
+    if (value !== undefined) parts.push(`${field} ${JSON.stringify(redact(value, secrets))}`);
+  }
+  if (step.near) parts.push(`near text ${JSON.stringify(redact(step.near.text, secrets))}`);
+  if (step.within) {
+    parts.push(step.within.rowContaining !== undefined
+      ? `within row_containing ${JSON.stringify(redact(step.within.rowContaining, secrets))}`
+      : `within ${step.within.role}${step.within.name === undefined ? "" : ` ${JSON.stringify(redact(step.within.name, secrets))}`}`);
+  }
+  if (step.index !== undefined) parts.push(`index ${step.index}`);
+  return parts.length ? parts.join(" + ") : "focused element";
+}
+
+async function describeResolvedTarget(locator, step, secrets, settings) {
+  if (typeof locator?.evaluate !== "function") return undefined;
+  try {
+    const includeValue = step.action === "type" && step.sensitive === false;
+    const resolved = await locator.evaluate((element, includeFieldValue) => {
+      const textOf = (node) => (node?.innerText || node?.textContent || "").replace(/\s+/g, " ").trim();
+      const referenced = (element.getAttribute("aria-labelledby") || "").trim().split(/\s+/).filter(Boolean)
+        .map((id) => textOf(element.ownerDocument.getElementById(id))).filter(Boolean).join(" ");
+      const labels = [...(element.labels || [])].map(textOf).filter(Boolean).join(" ");
+      const controlPlaceholder = element.matches("input,textarea,select") ? element.getAttribute("placeholder") || "" : "";
+      const textAlternative = element.matches("a,button,[role=button],[role=link],[role=menuitem]") ? textOf(element) : "";
+      const role = element.getAttribute("role")
+        || (element.matches("a[href]") ? "link"
+          : element.matches("button,input[type=button],input[type=submit],input[type=reset]") ? "button"
+            : element.matches("input[type=checkbox]") ? "checkbox"
+              : element.matches("input[type=radio]") ? "radio"
+                : element.matches("input[type=search]") ? "searchbox"
+                  : element.matches("select") ? "combobox"
+                    : element.matches("input,textarea") ? "textbox" : "");
+      const result = {
+        tag: element.localName,
+        id: element.id || "",
+        role,
+        accessible_name: element.getAttribute("aria-label") || referenced || labels || controlPlaceholder
+          || element.getAttribute("alt") || textAlternative || element.getAttribute("title") || "",
+      };
+      if (includeFieldValue && "value" in element) result.value = String(element.value ?? "");
+      return result;
+    }, includeValue);
+    if (step.role) resolved.role = step.role;
+    resolved.id = redact(resolved.id, secrets);
+    resolved.accessible_name = redact(String(resolved.accessible_name).slice(0, settings.jev.maxDiagnosticChars), secrets);
+    if (Object.hasOwn(resolved, "value")) {
+      resolved.value = redact(resolved.value.slice(0, settings.browser.maxTextEntryChars), secrets);
+    }
+    return resolved;
+  } catch {
+    return undefined;
+  }
+}
+
+function targetEvidence(step, secrets, resolvedTarget) {
+  const evidence = { target: describeTarget(step, secrets) };
+  if (resolvedTarget) evidence.resolved_target = resolvedTarget;
+  return evidence;
 }
 
 async function namedTarget(root, step, snapshot, secrets, timeout, settings) {
@@ -1253,8 +1411,9 @@ async function executeStep(page, step, settings, snapshot, secrets, downloadLedg
   const timeout = step.timeoutMs ?? settings.browser.actionTimeoutMs;
   if (step.action === "wait_for_text") {
     const locator = root.getByText(step.text, { exact: false });
-    await visibleIndexes(locator, timeout, `text ${JSON.stringify(redact(step.text, secrets))}`, settings);
-    return { action: step.action };
+    if (step.failOn) await waitForTextOrFailure(root, step, timeout, settings, secrets);
+    else await visibleIndexes(locator, timeout, `text ${JSON.stringify(redact(step.text, secrets))}`, settings);
+    return { action: step.action, target: `text ${JSON.stringify(redact(step.text, secrets))}` };
   }
   if (step.action === "wait_for_condition") {
     if (step.condition === "network_idle") {
@@ -1273,16 +1432,24 @@ async function executeStep(page, step, settings, snapshot, secrets, downloadLedg
       const locator = await targetLocator(root, step, timeout, settings);
       await waitForLocatorHidden(locator, timeout, `hidden condition ${describeTarget(step, secrets)}`, settings, step.index);
     }
-    return { action: step.action, condition: step.condition };
+    return {
+      action: step.action,
+      condition: step.condition,
+      ...(step.condition === "network_idle"
+        ? (step.urlContains ? { url_contains: redact(step.urlContains, secrets) } : {})
+        : { target: describeTarget(step, secrets) }),
+    };
   }
   if (step.action === "press") {
+    let evidence = {};
     if (step.role || step.name !== undefined || hasLocatorField(step) || step.near) {
       const control = await namedTarget(root, step, snapshot, secrets, timeout, settings);
+      evidence = targetEvidence(step, secrets, await describeResolvedTarget(control, step, secrets, settings));
       await control.press(step.key, { timeout });
     } else {
       await page.keyboard.press(step.key, { timeout });
     }
-    return { action: step.action, key: step.key };
+    return { action: step.action, key: step.key, ...evidence };
   }
   if (step.action === "like_comment" || step.action === "unlike_comment") {
     return { action: step.action, result: await reactToComment(root, step, timeout, settings) };
@@ -1300,6 +1467,7 @@ async function executeStep(page, step, settings, snapshot, secrets, downloadLedg
   if (step.action === "upload_file") {
     const files = await uploadFiles(step, settings);
     const control = await namedTarget(root, step, snapshot, secrets, timeout, settings);
+    const resolvedTarget = await describeResolvedTarget(control, step, secrets, settings);
     if (step.target === "input") {
       await control.setInputFiles(files, { timeout });
     } else {
@@ -1313,23 +1481,34 @@ async function executeStep(page, step, settings, snapshot, secrets, downloadLedg
         await control.drop({ files }, { timeout });
       }
     }
-    return { action: step.action, target: step.target, file_count: files.length };
+    return {
+      action: step.action,
+      target: step.target,
+      target_locator: describeTarget(step, secrets),
+      ...(resolvedTarget ? { resolved_target: resolvedTarget } : {}),
+      file_count: files.length,
+    };
   }
   if (step.action === "assert_hidden") {
     const locator = await targetLocator(root, step, timeout, settings);
     await waitForLocatorHidden(locator, timeout, `assert_hidden ${describeTarget(step, secrets)}`, settings, step.index);
-    return { action: step.action, asserted: true };
+    return { action: step.action, asserted: true, target: describeTarget(step, secrets) };
   }
   if (step.action === "assert_visible") {
     const control = await namedTarget(root, step, snapshot, secrets, timeout, settings);
     if (!(await isActuallyVisible(control))) throw new JevBrowserError(`assert_visible failed for ${describeTarget(step, secrets)}`);
-    return { action: step.action, asserted: true };
+    return {
+      action: step.action,
+      asserted: true,
+      ...targetEvidence(step, secrets, await describeResolvedTarget(control, step, secrets, settings)),
+    };
   }
   const control = await namedTarget(root, step, snapshot, secrets, timeout, settings);
   if (step.action === "click") {
-    if (!step.expectDownload) {
+    const resolvedTarget = await describeResolvedTarget(control, step, secrets, settings);
+    if (!step.expectDownload) {
       await control.click({ timeout });
-      return { action: step.action, target: describeTarget(step, secrets) };
+      return { action: step.action, ...targetEvidence(step, secrets, resolvedTarget) };
     }
     let download;
     try {
@@ -1340,13 +1519,14 @@ async function executeStep(page, step, settings, snapshot, secrets, downloadLedg
     } catch {
       throw new JevBrowserError("click did not produce the expected download before the configured timeout");
     }
-    return {
-      action: step.action,
-      target: describeTarget(step, secrets),
-      downloaded_file: await saveDownload(download, settings, downloadLedger),
-    };
+    return {
+      action: step.action,
+      ...targetEvidence(step, secrets, resolvedTarget),
+      downloaded_file: await saveDownload(download, settings, downloadLedger),
+    };
   }
   if (step.action === "type") {
+    const resolvedTarget = await describeResolvedTarget(control, step, secrets, settings);
     if (step.mode === "keys") {
       await control.fill("", { timeout });
       const normalizedText = step.text.replace(/\r\n?/g, "\n");
@@ -1361,32 +1541,54 @@ async function executeStep(page, step, settings, snapshot, secrets, downloadLedg
       await control.fill(step.text, { timeout });
       if (step.blur) await control.press("Tab", { timeout });
     }
-    return { action: step.action, role: step.role, name: step.name };
-  }
+    if (resolvedTarget && step.sensitive === false) {
+      resolvedTarget.value = redact((await control.inputValue({ timeout })).slice(0, settings.browser.maxTextEntryChars), secrets);
+    }
+    return {
+      action: step.action,
+      role: step.role,
+      name: step.name,
+      ...targetEvidence(step, secrets, resolvedTarget),
+    };
+  }
   if (step.action === "select_option") {
+    const resolvedTarget = await describeResolvedTarget(control, step, secrets, settings);
     await control.selectOption({ label: step.option }, { timeout });
-    return { action: step.action, target: describeTarget(step, secrets) };
-  }
-  if (step.action === "hover") {
-    await control.hover({ timeout });
-    return { action: step.action, role: step.role, name: step.name };
-  }
-  if (step.action === "assert_visible") {
-    if (!(await control.isVisible())) throw new JevBrowserError(`assert_visible failed for ${step.role} ${JSON.stringify(redact(step.name, secrets))}`);
-    return { action: step.action, asserted: true };
-  }
+    return { action: step.action, ...targetEvidence(step, secrets, resolvedTarget) };
+  }
+  if (step.action === "hover") {
+    const resolvedTarget = await describeResolvedTarget(control, step, secrets, settings);
+    await control.hover({ timeout });
+    return { action: step.action, role: step.role, name: step.name, ...targetEvidence(step, secrets, resolvedTarget) };
+  }
+  if (step.action === "assert_visible") {
+    if (!(await control.isVisible())) throw new JevBrowserError(`assert_visible failed for ${step.role} ${JSON.stringify(redact(step.name, secrets))}`);
+    return {
+      action: step.action,
+      asserted: true,
+      ...targetEvidence(step, secrets, await describeResolvedTarget(control, step, secrets, settings)),
+    };
+  }
   if (step.action === "assert_text") {
-    const actual = (await control.innerText({ timeout })).replace(/\s+/g, " ").trim();
-    const expected = step.expected.replace(/\s+/g, " ").trim();
-    if (!actual.toLocaleLowerCase().includes(expected.toLocaleLowerCase())) {
+    const actual = (await control.innerText({ timeout })).replace(/\s+/g, " ").trim();
+    const expected = step.expected.replace(/\s+/g, " ").trim();
+    if (!actual.toLocaleLowerCase().includes(expected.toLocaleLowerCase())) {
       throw new JevBrowserError(`assert_text failed for ${describeTarget(step, secrets)}`);
-    }
-    return { action: step.action, asserted: true };
-  }
-  if (step.action === "assert_value") {
-    const actual = await control.inputValue({ timeout });
+    }
+    return {
+      action: step.action,
+      asserted: true,
+      ...targetEvidence(step, secrets, await describeResolvedTarget(control, step, secrets, settings)),
+    };
+  }
+  if (step.action === "assert_value") {
+    const actual = await control.inputValue({ timeout });
     if (actual !== step.expected) throw new JevBrowserError(`assert_value failed for ${describeTarget(step, secrets)}`);
-    return { action: step.action, asserted: true };
+    return {
+      action: step.action,
+      asserted: true,
+      ...targetEvidence(step, secrets, await describeResolvedTarget(control, step, secrets, settings)),
+    };
   }
   throw new JevBrowserError("unsupported browser action");
 }
@@ -1429,7 +1631,7 @@ function sanitizeDiagnosticText(value, secrets, limit) {
 }
 
 function createDiagnostics(page, options, settings, secrets) {
-  const diagnostics = { console_errors: [], network_failures: [] };
+  const diagnostics = { console_errors: [], network_failures: [], warnings: [] };
   const pendingBodies = [];
   const limit = settings.jev.maxDiagnosticItems;
   const messageLimit = settings.jev.maxDiagnosticChars;
@@ -1441,26 +1643,50 @@ function createDiagnostics(page, options, settings, secrets) {
     addDiagnostic(diagnostics.console_errors, sanitizeDiagnosticText(error.message || error.name, secrets, messageLimit), limit);
   };
   const addResponseMessage = async (response, entry) => {
+    const warn = (reason) => addDiagnostic(
+      diagnostics.warnings,
+      `network error response body omitted for ${entry.url}: ${reason}`,
+      limit,
+    );
     try {
       const responseUrl = new URL(response.url());
       const pageUrl = new URL(page.url());
       if (responseUrl.origin !== pageUrl.origin) return;
       const headers = await response.headers();
       const contentType = String(headers["content-type"] || "").toLowerCase();
-      const contentLength = Number(headers["content-length"]);
-      if (!contentType.includes("application/json") || !Number.isSafeInteger(contentLength)
-        || contentLength < 0 || contentLength > settings.browser.maxNetworkErrorBodyBytes) return;
+      if (!contentType.includes("application/json")) {
+        warn("content-type is not application/json");
+        return;
+      }
+      const contentLengthHeader = headers["content-length"];
+      if (contentLengthHeader !== undefined) {
+        const contentLength = Number(contentLengthHeader);
+        if (!Number.isSafeInteger(contentLength) || contentLength < 0) {
+          warn("Content-Length is invalid");
+          return;
+        }
+        if (contentLength > settings.browser.maxNetworkErrorBodyBytes) {
+          warn("declared Content-Length exceeds the configured limit");
+          return;
+        }
+      }
       const body = await withTimeout(
         response.body(),
         settings.browser.actionTimeoutMs,
         "error response body read timed out",
       );
-      if (body.length > settings.browser.maxNetworkErrorBodyBytes) return;
+      if (body.length > settings.browser.maxNetworkErrorBodyBytes) {
+        warn("received body exceeds the configured limit");
+        return;
+      }
       const payload = JSON.parse(body.toString("utf8"));
-      if (!isRecord(payload) || typeof payload.message !== "string") return;
+      if (!isRecord(payload) || typeof payload.message !== "string") {
+        warn("JSON body does not contain a text message");
+        return;
+      }
       entry.message = sanitizeDiagnosticText(payload.message, secrets, settings.browser.maxNetworkErrorMessageChars);
     } catch {
-      // A diagnostic body is optional; malformed, oversized, or late bodies do not fail the flow.
+      warn("body could not be read or parsed safely");
     }
   };
   const onResponse = (response) => {
@@ -1518,6 +1744,12 @@ function failedStepDetails(step, index, error, settings, secrets) {
   };
   if (step.role !== undefined) details.role = step.role;
   if (step.name !== undefined) details.name = redact(step.name, secrets);
+  if (step.role || hasLocatorField(step) || step.near || step.within) details.target = describeTarget(step, secrets);
+  if (step.action === "wait_for_text") details.text = redact(step.text, secrets);
+  if (step.failOn) {
+    details.fail_on = { role: step.failOn.role };
+    if (step.failOn.name !== undefined) details.fail_on.name = redact(step.failOn.name, secrets);
+  }
   details.timeout_ms = step.timeoutMs ?? settings.browser.actionTimeoutMs;
   details.error = stepFailureText(error?.stepCause || error, secrets, settings.jev.maxDiagnosticChars);
   return details;
@@ -1593,6 +1825,8 @@ export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, ca
     downloaded_files: [],
     accessibility_audits: [],
     unnamed_controls: [],
+    unnamed_controls_initial: [],
+    unnamed_controls_final: [],
     warnings: [],
     final_snapshot: "",
   };
@@ -1643,6 +1877,8 @@ export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, ca
       const enriched = await enrichSnapshot(page, readiness.snapshot, settings, secrets, options.snapshotScope, options.snapshotIncludeHidden);
       result.final_snapshot = enriched.snapshot;
       result.unnamed_controls = enriched.unnamedControls;
+      result.unnamed_controls_initial = enriched.unnamedControls;
+      result.unnamed_controls_final = enriched.unnamedControls;
       for (const control of enriched.unnamedControls) {
         addDiagnostic(
           result.warnings,
@@ -1772,9 +2008,8 @@ export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, ca
           options.snapshotIncludeHidden,
         );
         snapshot = finalDetails.snapshot;
-        result.unnamed_controls = [...result.unnamed_controls, ...finalDetails.unnamedControls]
-          .filter((control, index, all) => all.findIndex((candidate) => candidate.role === control.role
-            && candidate.html === control.html) === index);
+        result.unnamed_controls_final = finalDetails.unnamedControls;
+        result.unnamed_controls = finalDetails.unnamedControls;
         timings.browserPlanMs = performance.now() - planStarted;
         const visible = containsExpectedOutcome(snapshot, outcome);
         const assertionCount = plan.steps.filter(({ action }) => action.startsWith("assert_")).length;
@@ -1825,6 +2060,7 @@ export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, ca
           options.snapshotIncludeHidden,
         );
         result.final_snapshot = enriched.snapshot;
+        result.unnamed_controls_final = enriched.unnamedControls;
         result.unnamed_controls = enriched.unnamedControls;
       } else {
         result.final_snapshot = snapshot;
@@ -1865,8 +2101,9 @@ export async function executeBrowserFlow({ flow, initialUrl, expectedOutcome, ca
   }
   if (tracePath) result.trace_path = tracePath;
   if (artifactErrors.length) result.artifact_errors = artifactErrors;
-  result.console_errors = capture.diagnostics.console_errors;
-  result.network_failures = capture.diagnostics.network_failures;
+  result.console_errors = capture.diagnostics.console_errors;
+  result.network_failures = capture.diagnostics.network_failures;
+  result.warnings.push(...capture.diagnostics.warnings);
   result.timings_ms = flowTimings(started, browserSessionMs, timings.navigationMs, timings.initialSnapshotMs, timings.readyMs, timings.decisionMs, timings.browserPlanMs);
   return redactObject(result, secrets);
 }

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

@@ -132,7 +132,7 @@ export function createJevBrowserServer({ env = process.env, configPath, fetchImp
   server.registerTool(
     "run_browser_flow",
     {
-      description: "Run a bounded screen flow in one warm Playwright session. Supports role/name and label, placeholder, title, text, test_id, CSS/XPath fallback selectors, relative row/dialog scopes, press keys, SPA readiness, per-step timeouts, same-origin page reuse, key-based typing, filtered network-idle and hidden-state waits, assertions, uploads, bounded downloads, axe audits, unnamed-control diagnostics, rich form snapshots, and optional same-origin JSON error messages. All plan steps run before expected_outcome is checked unless stop_on_expected is enabled. Jev chooses among supplied plans; one plan skips the decision call when fast_path is enabled.",
+      description: "Run a bounded screen flow in one warm Playwright session. Supports role/name and label, placeholder, title, text, test_id, CSS/XPath fallback selectors, relative row/dialog scopes, press keys, SPA readiness, per-step timeouts, same-origin page reuse, key-based typing, filtered network-idle and hidden-state waits, wait_for_text fail_on alerts, assertions, uploads, bounded downloads, axe audits, Playwright-indexed unnamed-control diagnostics split by initial/final screen, resolved locator and element evidence, and bounded same-origin JSON error bodies including chunked responses. All plan steps run before expected_outcome is checked unless stop_on_expected is enabled. Jev chooses among supplied plans; one plan skips the decision call when fast_path is enabled.",
       inputSchema: {
         flow: z.string(),
         initial_url: z.string(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diegosouzacdv/jev-browser-mcp",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "Portable MCP server for bounded Playwright screen flows selected by Jev",
   "license": "MIT",
   "repository": {