@diegosouzacdv/jev-browser-mcp 0.3.0 → 0.4.0

package/config/ui-testing.json

@@ -1,7 +1,7 @@
 {
   "version": 1,
   "browser": {
-    "mode": "harness",
+    "mode": "computer",
     "harness_browser": "chrome",
     "playwright_mcp_package": "@playwright/mcp@0.0.79",
     "computer_browser": "chrome",
@@ -22,8 +22,20 @@
   },
   "jev_browser_mcp": {
     "browser": {
-      "max_action_timeout_seconds": 8,
-      "max_upload_files": 5,
+      "max_action_timeout_seconds": 8,
+      "ready_timeout_seconds_default": 15,
+      "max_ready_timeout_seconds": 60,
+      "ready_network_idle_default": true,
+      "ready_stable_ms_default": 400,
+      "max_ready_stable_ms": 2000,
+      "post_step_ready_timeout_seconds_default": 5,
+      "max_step_timeout_seconds": 60,
+      "key_delay_ms_default": 30,
+      "reuse_page_default": false,
+      "capture_network_error_bodies_default": false,
+      "max_network_error_body_bytes": 65536,
+      "max_network_error_message_chars": 300,
+      "max_upload_files": 5,
       "max_upload_path_chars": 4096,
       "max_upload_file_bytes": 10485760,
       "max_upload_total_bytes": 26214400,

package/docs/jev-browser-mcp.md

@@ -17,10 +17,10 @@ versão em produção, use o número explícito no argumento do pacote:
   "mcpServers": {
     "jev-browser": {
       "command": "npx",
-      "args": ["--yes", "@diegosouzacdv/jev-browser-mcp@0.3.0"],
+      "args": ["--yes", "@diegosouzacdv/jev-browser-mcp@0.4.0"],
       "env": {
         "OPENROUTER_API_KEY": "${OPENROUTER_API_KEY}",
-        "JEV_BROWSER_MODE": "harness"
+        "JEV_BROWSER_MODE": "computer"
       }
     }
   }
@@ -31,15 +31,18 @@ O formato de interpolação de variáveis varia por harness. Injete a chave por
 um secret manager ou pelo ambiente do processo; não grave a chave no arquivo
 de configuração. Para instalar no projeto Node do próprio harness:
 
-```sh
-npm install @diegosouzacdv/jev-browser-mcp
-npx --yes @diegosouzacdv/jev-browser-mcp --install-browser
-```
-
-No modo `harness`, a instalação baixa uma vez o Chrome/Edge que o Playwright
-controlará. No modo `computer`, o pacote abre o Chrome/Edge instalado e usa um
-perfil persistente exclusivo em `browser.computer_user_data_dir`; personalize
-as escolhas com `JEV_BROWSER_MODE`, `JEV_BROWSER_CHANNEL` e
+```sh
+npm install @diegosouzacdv/jev-browser-mcp
+```
+
+O padrão `computer` exige Chrome ou Edge instalado. Se optar por `harness`,
+configure `JEV_BROWSER_MODE=harness` antes de instalar o navegador gerenciado
+pelo Playwright com `npx --yes @diegosouzacdv/jev-browser-mcp --install-browser`.
+
+O padrão é `computer`: o pacote abre o Chrome/Edge instalado e usa um perfil
+persistente exclusivo em `browser.computer_user_data_dir`. No modo `harness`, a
+instalação baixa uma vez o Chrome/Edge que o Playwright controlará. Personalize
+as escolhas com `JEV_BROWSER_MODE`, `JEV_BROWSER_CHANNEL` e
 `JEV_BROWSER_PROFILE`. O browser permanece aquecido enquanto o processo MCP
 estiver ativo e fecha quando o harness encerra o processo. `JEV_PROVIDER_URL`
 e `JEV_MODEL` podem substituir os valores centrais; a credencial continua no
@@ -49,11 +52,15 @@ Uma aplicação Node também pode importar `createJevBrowserServer` por
 `@diegosouzacdv/jev-browser-mcp/server` e conectar o servidor ao transporte MCP
 que ela já utiliza.
 
-O pacote é montado pela raiz do repositório, mas o campo `files` do `package.json`
-inclui somente o código Node, a configuração compartilhada e esta documentação
-(além do README que o npm inclui automaticamente). Ele não publica o restante
-do orquestrador. A instalação por npm é a recomendada; use a referência GitHub
-somente quando precisar experimentar uma revisão ainda não publicada.
+O pacote é montado em uma pasta temporária isolada: o publicador usa o campo
+`files` do `package.json` para copiar somente o código Node, a configuração
+compartilhada e esta documentação, que também vira o `README.md` da raiz do
+pacote. Assim, o npm não inclui o README geral do orquestrador na página do MCP.
+Para gerar e conferir o pacote antes de publicar, execute
+`npm run pack:jev-browser-mcp`; para publicar uma versão já autenticada no npm, execute
+`npm run publish:jev-browser-mcp`. A instalação por npm é a recomendada; use a
+referência GitHub somente quando precisar experimentar uma revisão ainda não
+publicada.
 
 ### Contrato do pacote
 
@@ -82,12 +89,17 @@ resultado esperado na tela.
 
 Cada plano pode usar:
 
-- `click`, `type`, `hover` e `select_option` com papel/nome acessível exatos;
-- `wait_for_text` e `wait_for_condition` (`network_idle`, limitado pelo timeout
-  de ação configurado);
+- `click`, `type`, `hover` e `select_option` com papel/nome acessível exatos;
+- `timeout_seconds` opcional em cada etapa, limitado pela configuração central;
+- `type` com `mode: "keys"` para digitar sequencialmente em campos com máscara,
+  `blur: true` para desfocar o campo e `sensitive: false` para permitir que o
+  valor apareça nas evidências;
+- `wait_for_text` e `wait_for_condition` (`network_idle`, `hidden` ou
+  `text_hidden`);
 - `press_key` com `PageDown`, `PageUp`, `Home`, `End`, `ArrowDown`, `ArrowUp`,
   `Enter`, `Escape` ou `Tab`;
-- `assert_text`, `assert_value`, `assert_visible` e `assert_hidden`;
+- `assert_text`, `assert_value`, `assert_visible` e `assert_hidden`; `assert_text`
+  pode receber apenas `role` quando a região, como `alert`, não tem nome acessível;
 - `upload_file` para input rotulado, botão que abre o seletor de arquivo ou
   dropzone;
 - `audit_accessibility` com axe-core para WCAG 2.1 A/AA;
@@ -235,9 +247,9 @@ do pacote Node ficam no bloco opcional `jev_browser_mcp`, que não altera o
 contrato lido pelo servidor Python. Preserve a estrutura completa exigida pelos
 validadores.
 
-`browser.mode` aceita `harness` ou `computer`:
+`browser.mode` aceita `harness` ou `computer`; o padrão é `computer`:
 
-- `harness` usa Chrome headless e perfil isolado, adequado a execuções do
+- `harness` usa Chrome headless e contexto isolado, adequado a execuções do
   harness e CI; o estado de autenticação é descartado ao final da chamada.
 - `computer` abre o Chrome ou Edge instalado em modo visível e usa o diretório
   persistente `browser.computer_user_data_dir`, separado por navegador. Não
@@ -246,12 +258,15 @@ validadores.
 
 `browser.max_flow_steps` limita a soma de passos declarados entre os planos e
 `browser.max_text_entry_chars` limita cada valor digitado. O resultado contém
-`status`, o plano escolhido, as ações executadas, a última captura acessível e
-se o critério esperado apareceu. Quando existem asserções explícitas, `status`
-também pode ser `passed` com todas elas satisfeitas; `assertions_passed` registra
-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.
+`status`, o plano escolhido, as ações executadas, a última captura acessível e
+se o critério esperado apareceu. Quando existem asserções explícitas, `status`
+também pode ser `passed` com todas elas satisfeitas; `assertions_passed` registra
+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.
 
 `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
@@ -267,12 +282,18 @@ Os limites de download ficam no mesmo bloco: `max_download_files`,
 limita quantas descrições de violações axe entram no resultado; a contagem total
 continua informada mesmo quando a lista é truncada.
 
-O `run_browser_flow` aceita `options` com `fast_path`, `snapshot_scope`,
-`block_trackers`, `capture_console_errors`, `capture_network_errors`,
-`screenshot_on_failure` e `trace_on_failure`. Sem override, os padrões são lidos
-de `jev_browser_mcp` em `config/ui-testing.json`: um plano candidato pula a chamada Decisions;
-captura de console e screenshot de falha ficam ligadas; trace, rede e bloqueio
-de recursos ficam desligados. `snapshot_scope` aceita `body`, `main` ou `dialog`.
+O `run_browser_flow` aceita `options` com `fast_path`, `snapshot_scope`,
+`block_trackers`, `capture_console_errors`, `capture_network_errors`,
+`capture_network_error_bodies`, `ready_timeout_seconds`, `ready_network_idle`,
+`ready_stable_ms`, `ready_text`, `reuse_page`, `screenshot_on_failure` e
+`trace_on_failure`. Sem override, os padrões são lidos de `jev_browser_mcp` em
+`config/ui-testing.json`: um plano candidato pula a chamada Decisions;
+captura de console e screenshot de falha ficam ligadas; trace, rede e bloqueio
+de recursos ficam desligados. O browser espera a SPA renderizar uma captura
+acessível estável. `ready_text` pode identificar o conteúdo que marca a
+prontidão. `reuse_page: true` pula a navegação somente quando a página e
+`initial_url` têm a mesma origem. `snapshot_scope` aceita `body`, `main` ou
+`dialog`.
 
 `block_trackers: true` bloqueia os domínios e tipos de recurso listados na
 configuração (analytics, Hotjar, fontes externas e mídia). Isso pode alterar o
@@ -280,9 +301,12 @@ layout ou o comportamento do site, então a opção é desligada por padrão.
 
 Com `capture_console_errors` e `capture_network_errors`, o retorno traz
 `console_errors` e `network_failures`, limitados em quantidade e tamanho.
-Respostas HTTP 4xx/5xx e requisições que falham são listadas; query strings,
-fragmentos, valores de formulário e nomes de arquivo são removidos ou
-sanitizados. Em falhas, `screenshot_on_failure` salva screenshot local e retorna
+Respostas HTTP 4xx/5xx e requisições que falham são listadas; query strings,
+fragmentos, valores de formulário e nomes de arquivo são removidos ou
+sanitizados. `capture_network_error_bodies: true` lê somente respostas JSON
+4xx/5xx da mesma origem, limita o corpo e inclui apenas o campo textual
+`message`, também sanitizado. Em falhas, `screenshot_on_failure` salva
+screenshot local e retorna
 `screenshot_path`. `trace_on_failure: true` também grava um `.zip` compatível
 com o Trace Viewer do Playwright e retorna `trace_path`. O diretório padrão é
 `~/.cache/orquestrador/jev-browser-artifacts`; `JEV_BROWSER_ARTIFACT_DIR` pode

package/mcp_servers/jev-browser-npm/bin/jev-browser-mcp.cjs

@@ -10,7 +10,7 @@ Usage:
   jev-browser-mcp --help           Show this help
 
 Configuration is read from config/ui-testing.json. Set OPENROUTER_API_KEY in
-the environment and use JEV_BROWSER_MODE=harness or computer to choose a browser.
+the environment. The default mode is computer; use JEV_BROWSER_MODE=harness to select isolated headless mode.
 For upload_file, set JEV_BROWSER_UPLOAD_ROOT to a dedicated fixture directory.
 `;
 

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

@@ -16,8 +16,20 @@ const CONFIG_KEYS = {
     "max_flow_steps",
     "max_text_entry_chars",
   ],
-  nodeBrowser: [
-    "max_action_timeout_seconds",
+  nodeBrowser: [
+    "max_action_timeout_seconds",
+    "ready_timeout_seconds_default",
+    "max_ready_timeout_seconds",
+    "ready_network_idle_default",
+    "ready_stable_ms_default",
+    "max_ready_stable_ms",
+    "post_step_ready_timeout_seconds_default",
+    "max_step_timeout_seconds",
+    "key_delay_ms_default",
+    "reuse_page_default",
+    "capture_network_error_bodies_default",
+    "max_network_error_body_bytes",
+    "max_network_error_message_chars",
     "max_upload_files",
     "max_upload_path_chars",
     "max_upload_file_bytes",
@@ -206,7 +218,7 @@ export function loadSettings({ env = process.env, configPath = CONFIG_PATH } = {
   const uploadRoot = configuredUploadRoot
     ? configuredDirectory(configuredUploadRoot, `environment ${uploadRootEnv}`)
     : null;
-  const snapshotScope = browserOptions.snapshot_scope_default;
+  const snapshotScope = browserOptions.snapshot_scope_default;
   if (!new Set(["body", "main", "dialog"]).has(snapshotScope)) {
     throw new JevBrowserError("config/ui-testing.json jev_browser_mcp.browser.snapshot_scope_default must be body, main, or dialog");
   }
@@ -215,11 +227,28 @@ export function loadSettings({ env = process.env, configPath = CONFIG_PATH } = {
     "jev_browser_mcp.browser.tracker_host_suffixes",
     (host) => /^[a-z0-9.-]+$/i.test(host) && !host.startsWith(".") && !host.endsWith("."),
   );
-  const blockedResourceTypes = stringList(
+  const blockedResourceTypes = stringList(
     browserOptions.blocked_resource_types,
     "jev_browser_mcp.browser.blocked_resource_types",
     (type) => new Set(["font", "media", "image"]).has(type),
-  );
+  );
+  const maxReadyTimeoutSeconds = positiveNumber(browserOptions.max_ready_timeout_seconds, "jev_browser_mcp.browser.max_ready_timeout_seconds");
+  const readyTimeoutSecondsDefault = positiveNumber(browserOptions.ready_timeout_seconds_default, "jev_browser_mcp.browser.ready_timeout_seconds_default");
+  const maxReadyStableMs = positiveNumber(browserOptions.max_ready_stable_ms, "jev_browser_mcp.browser.max_ready_stable_ms", true);
+  const readyStableMsDefault = positiveNumber(browserOptions.ready_stable_ms_default, "jev_browser_mcp.browser.ready_stable_ms_default", true);
+  if (readyTimeoutSecondsDefault > maxReadyTimeoutSeconds) {
+    throw new JevBrowserError("config/ui-testing.json ready timeout default exceeds its configured maximum");
+  }
+  if (readyStableMsDefault > maxReadyStableMs) {
+    throw new JevBrowserError("config/ui-testing.json stable snapshot default exceeds its configured maximum");
+  }
+  const postStepReadyTimeoutSeconds = positiveNumber(
+    browserOptions.post_step_ready_timeout_seconds_default,
+    "jev_browser_mcp.browser.post_step_ready_timeout_seconds_default",
+  );
+  if (postStepReadyTimeoutSeconds > maxReadyTimeoutSeconds) {
+    throw new JevBrowserError("config/ui-testing.json post-step readiness timeout exceeds its configured maximum");
+  }
 
   return Object.freeze({
     env,
@@ -229,7 +258,14 @@ export function loadSettings({ env = process.env, configPath = CONFIG_PATH } = {
       profileDir: profileDirectory(profileTemplate, channel, env.JEV_BROWSER_PROFILE),
       maxFlowSteps: positiveNumber(document.browser.max_flow_steps, "browser.max_flow_steps", true),
       maxTextEntryChars: positiveNumber(document.browser.max_text_entry_chars, "browser.max_text_entry_chars", true),
-      actionTimeoutMs: positiveNumber(browserOptions.max_action_timeout_seconds, "jev_browser_mcp.browser.max_action_timeout_seconds") * 1000,
+      actionTimeoutMs: positiveNumber(browserOptions.max_action_timeout_seconds, "jev_browser_mcp.browser.max_action_timeout_seconds") * 1000,
+      maxReadyTimeoutSeconds,
+      maxReadyStableMs,
+      postStepReadyTimeoutMs: postStepReadyTimeoutSeconds * 1000,
+      maxStepTimeoutSeconds: positiveNumber(browserOptions.max_step_timeout_seconds, "jev_browser_mcp.browser.max_step_timeout_seconds"),
+      keyDelayMs: positiveNumber(browserOptions.key_delay_ms_default, "jev_browser_mcp.browser.key_delay_ms_default", true),
+      maxNetworkErrorBodyBytes: positiveNumber(browserOptions.max_network_error_body_bytes, "jev_browser_mcp.browser.max_network_error_body_bytes", true),
+      maxNetworkErrorMessageChars: positiveNumber(browserOptions.max_network_error_message_chars, "jev_browser_mcp.browser.max_network_error_message_chars", true),
       maxUploadFiles: positiveNumber(browserOptions.max_upload_files, "jev_browser_mcp.browser.max_upload_files", true),
       maxUploadPathChars: positiveNumber(browserOptions.max_upload_path_chars, "jev_browser_mcp.browser.max_upload_path_chars", true),
       maxUploadFileBytes: positiveNumber(browserOptions.max_upload_file_bytes, "jev_browser_mcp.browser.max_upload_file_bytes", true),
@@ -246,8 +282,13 @@ export function loadSettings({ env = process.env, configPath = CONFIG_PATH } = {
         screenshotOnFailure: booleanValue(browserOptions.screenshot_on_failure_default, "jev_browser_mcp.browser.screenshot_on_failure_default"),
         traceOnFailure: booleanValue(browserOptions.trace_on_failure_default, "jev_browser_mcp.browser.trace_on_failure_default"),
         captureConsoleErrors: booleanValue(browserOptions.capture_console_errors_default, "jev_browser_mcp.browser.capture_console_errors_default"),
-        captureNetworkErrors: booleanValue(browserOptions.capture_network_errors_default, "jev_browser_mcp.browser.capture_network_errors_default"),
-        blockTrackers: booleanValue(browserOptions.block_trackers_default, "jev_browser_mcp.browser.block_trackers_default"),
+        captureNetworkErrors: booleanValue(browserOptions.capture_network_errors_default, "jev_browser_mcp.browser.capture_network_errors_default"),
+        captureNetworkErrorBodies: booleanValue(browserOptions.capture_network_error_bodies_default, "jev_browser_mcp.browser.capture_network_error_bodies_default"),
+        blockTrackers: booleanValue(browserOptions.block_trackers_default, "jev_browser_mcp.browser.block_trackers_default"),
+        readyNetworkIdle: booleanValue(browserOptions.ready_network_idle_default, "jev_browser_mcp.browser.ready_network_idle_default"),
+        reusePage: booleanValue(browserOptions.reuse_page_default, "jev_browser_mcp.browser.reuse_page_default"),
+        readyTimeoutSeconds: readyTimeoutSecondsDefault,
+        readyStableMs: readyStableMsDefault,
         snapshotScope,
       }),
       trackerHostSuffixes: Object.freeze(trackerHostSuffixes),