@diegosouzacdv/jev-browser-mcp 0.6.1 → 0.6.2

package/README.md

@@ -17,7 +17,7 @@ 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.6.1"],
+      "args": ["--yes", "@diegosouzacdv/jev-browser-mcp@0.6.2"],
       "env": {
         "OPENROUTER_API_KEY": "${OPENROUTER_API_KEY}",
         "JEV_BROWSER_MODE": "computer"
@@ -32,7 +32,7 @@ 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@0.6.1
+npm install @diegosouzacdv/jev-browser-mcp@0.6.2
 ```
 
 Se o harness executa o MCP repetidamente nesta máquina, instale uma versão
@@ -40,7 +40,7 @@ fixa globalmente para evitar a resolução e o download feitos pelo `npx` em cad
 inicialização:
 
 ```sh
-npm install --global @diegosouzacdv/jev-browser-mcp@0.6.1
+npm install --global @diegosouzacdv/jev-browser-mcp@0.6.2
 ```
 
 Depois configure o servidor MCP com `command: "jev-browser-mcp"` e `args: []`.
@@ -49,7 +49,7 @@ Para atualizar, rode `npm install --global
 
 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@0.6.1 --install-browser`.
+pelo Playwright com `npx --yes @diegosouzacdv/jev-browser-mcp@0.6.2 --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
@@ -107,11 +107,17 @@ a página inicial, captura o snapshot acessível e pede ao Jev que escolha um
 plano. Em seguida, executa o plano inteiro na mesma sessão e confere o
 resultado esperado na tela.
 
-Cada plano pode usar:
-
-- `click`, `type`, `hover`, `select_option`, `press`, `assert_*` e upload com
-  papel/nome acessível ou um localizador: `label`, `placeholder`, `title`,
-  `text`, `test_id` ou `selector`;
+Cada plano pode usar:
+
+- `navigate` para mudar de página no meio do fluxo. Com a continuidade ligada,
+  um `initial_url` de mesma origem diferente da URL ativa produz erro claro; use
+  `navigate` ou `continue_from_current_page: false` para escolher o destino;
+- `click`, `type`, `clear`, `hover`, `select_option`, `press`, `assert_*` e upload com
+  papel/nome acessível ou um localizador: `label`, `placeholder`, `title`,
+  `text`, `test_id` ou `selector`;
+- `name_match: "exact" | "contains" | "regex"` para controlar a comparação do
+  nome acessível; regex rejeita construções com backtracking excessivo. O papel
+  `switch` funciona em cliques, verificações e asserções;
 - `near: {"text":"..."}` para localizar o controle logo depois de um texto,
   `within: {"row_containing":"..."}` para limitar por trecho e
   `within: {"row_containing_exact":"..."}` para exigir um elemento com o
@@ -128,25 +134,34 @@ Cada plano pode usar:
 - `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;
-- `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. Nesse modo, `\n` envia Enter e `\t` envia Tab;
-- `wait_for_text`, `wait_for_value`, `wait_for_enabled` e `wait_for_condition`
-  (`network_idle`, `hidden`, `text_hidden` ou `angular_idle`). `wait` recebe
+- `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. `text_env` lê o valor sensível de uma variável
+  de ambiente do processo MCP, sem colocá-lo no plano. Nesse modo, `\n` envia
+  Enter e `\t` envia Tab;
+- `wait_for_text`, `wait_for_value`, `wait_for_enabled` e `wait_for_condition`
+  (`url`, `network_idle`, `hidden`, `text_hidden` ou `angular_idle`). `wait` recebe
   `ms` para uma pausa curta e limitada. `angular_idle` aguarda requisições
   `$http` e digest do AngularJS. `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. Se o alerta contiver o texto esperado, a etapa passa; caso contrário,
-  o alerta interrompe a espera. `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;
+  o alerta interrompe a espera. `url` aguarda a URL conter `url_contains`.
+  `network_idle` aceita esse filtro e aguarda uma janela de silêncio usando
+  `ready_stable_ms`; WebSocket, EventSource e polling não relacionado não
+  bloqueiam a espera. Se não surgir requisição correspondente, o passo conclui
+  após a janela de silêncio;
+- `press` (o alias legado `press_key` também é aceito) com `PageDown`, `PageUp`,
+  `Home`, `End`, setas, `Enter`, `Escape`, `Tab`, `Shift+Tab`, `Space`,
+  `Backspace` ou `Delete`. `clear` limpa um campo sem exigir texto. Sem alvo,
+  `press` envia a tecla ao elemento focado; com alvo, usa o localizador informado;
 - `assert_text`, `assert_value`, `assert_visible`, `assert_hidden` e
   `assert_enabled`; `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;
+- `upload_file` para input rotulado, botão que abre o seletor de arquivo ou
+  dropzone;
+- `target_page: "popup"` para continuar no popup aberto com `expect_popup: true`;
+  locators semânticos também atravessam open Shadow DOM. Shadow DOM fechado não
+  é acessível ao Playwright;
 - `audit_accessibility` com axe-core para WCAG 2.1 A/AA;
 - `like_comment` e `unlike_comment`, que localizam uma linha pelo autor e texto,
   não repetem uma reação já no estado pedido e distinguem `Curtir` de
@@ -211,11 +226,12 @@ com `within: {"row_containing_exact":"{pedido}"}`, e use uma etapa
 `{"action":"extract","role":"cell","name":"{pedido}","within":{"row_containing_exact":"{pedido}"},"as":"documento"}`.
 A etapa seguinte pode localizar o mesmo documento com `name: "{documento}"`.
 
-Em `wait_for_condition` com `condition: "hidden"`, use qualquer um desses
-localizadores, `near` ou `within`; `text_hidden` recebe o texto direto. Para
-aguardar o fim de uma chamada específica, use `condition: "network_idle"` com
-`url_contains`; o MCP precisa observar a requisição depois da etapa anterior e
-esperar que ela termine.
+Em `wait_for_condition` com `condition: "hidden"`, use qualquer um desses
+localizadores, `near` ou `within`; `text_hidden` recebe o texto direto. Para
+aguardar o fim de uma chamada específica, use `condition: "network_idle"` com
+`url_contains`. O filtro considera somente a atividade correspondente e termina
+após a janela configurada sem atividade; também termina caso nenhuma requisição
+correspondente apareça. Para validar status e corpo, prefira `assert_network`.
 
 Quando vários controles têm o mesmo papel e nome, `within` limita a busca a um
 container acessível único, como uma linha, card ou diálogo. `index` escolhe uma
@@ -411,15 +427,17 @@ validadores.
 
 `browser.mode` aceita `harness` ou `computer`; o padrão é `computer`:
 
-- `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.
+- `harness` usa Chrome headless e contexto isolado, adequado a execuções do
+  harness e CI. O processo MCP conserva browser, contexto e página entre
+  chamadas; cookies, local storage e estado da página permanecem enquanto o
+  processo estiver ativo. Encerre o processo para descartar o contexto isolado.
 - `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
   reutiliza o perfil pessoal já aberto. Faça login uma vez nesse perfil; os
   cookies permanecem nele entre chamadas.
 
-`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
+`browser.max_flow_steps` limita os passos de cada plano candidato; os planos
+não são somados. `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
@@ -457,9 +475,12 @@ O `run_browser_flow` aceita `options` com `fast_path`, `snapshot_scope`,
 `auto_angular_idle`, `login_url_contains`, `login_text`, `capture_console_errors`,
 `capture_network_errors`, `capture_network_error_bodies`, `ready_timeout_seconds`,
 `ready_network_idle`, `ready_stable_ms`, `ready_text`, `continue_from_current_page`,
-`reuse_page`, `step_timeout_seconds`, `max_flow_steps`, `return_snapshot`,
-`screenshot_on_failure`, `trace_on_failure`, `snapshot_include_hidden`,
-`stop_on_expected`, `dry_run`, `confirmation_token` e `report_path`. Sem override,
+`reuse_page`, `step_timeout_seconds`, `max_flow_steps`, `return_snapshot`,
+`screenshot_on_failure`, `screenshot_on_success`, `trace_on_failure`,
+`trace_on_success`, `record_video`, `snapshot_include_hidden`, `stop_on_expected`,
+`dry_run`, `confirmation_token`, `report_path`, `permissions`, `fake_media`,
+`viewport`, `mobile`, `device_scale_factor`, `locale`, `timezone_id`,
+`color_scheme`, `geolocation` e `allow_mutations`. 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
@@ -471,26 +492,33 @@ chamadas na mesma origem, não repete `page.goto` e consulta um snapshot atual
 sem esperar novamente por `load`/`networkidle`. As etapas continuam aguardando
 seus próprios alvos e condições. `reuse_page` segue como alias legado; defina
 `continue_from_current_page: false` para iniciar cada chamada em `initial_url`.
-Se a página atual e `initial_url` tiverem origens diferentes, o MCP navega para
-`initial_url`. Se forem da mesma origem, continua a página atual e avisa quando
-as URLs completas forem diferentes. `snapshot_scope` aceita `body`, `main` ou
-`dialog`; se `main` não existir, o snapshot usa `body`.
-
-`block_trackers: true` bloqueia analytics/trackers e os tipos de recurso
-configurados. Fontes ficam habilitadas por padrão para preservar ícones e
-glyphs; `block_fonts: true` bloqueia fontes separadamente. `busy_selectors`
-complementa `aria-busy="true"` ao aguardar overlays de carregamento.
+Se a página atual e `initial_url` tiverem origens diferentes, o MCP navega para
+`initial_url`. Se forem da mesma origem mas URLs completas diferentes, o MCP
+recusa continuar silenciosamente e pede uma etapa `navigate` ou
+`continue_from_current_page: false`. `snapshot_scope` aceita `body`, `main` ou
+`dialog`; se `main` não existir, o snapshot usa `body`.
+
+`block_trackers: true` bloqueia analytics/trackers e os tipos de recurso
+configurados, mas preserva `media` quando há permissão de microfone ou
+`fake_media`. Fontes ficam habilitadas por padrão para preservar ícones e
+glyphs; `block_fonts: true` bloqueia fontes separadamente. `busy_selectors`
+complementa `aria-busy="true"` ao aguardar overlays; elementos ocultos ou fora
+da tela com esse atributo não seguram a prontidão da página.
 `auto_angular_idle` aguarda AngularJS depois de cliques e digitação quando a
 página expõe o injector. `login_url_contains` e `login_text` substituem a
 detecção padrão de autenticação. `local_only: true` recusa qualquer etapa que
-precisaria chamar o provedor Jev; use exatamente um plano com `fast_path: true`.
+precisaria chamar o provedor Jev; use exatamente um plano com `fast_path: true`.
+`allow_mutations: true` pula a confirmação humana somente para URLs em
+`localhost`, `127.0.0.1` ou `::1`; use esse modo apenas em ambientes locais
+controlados.
 `step_timeout_seconds` define o timeout padrão por etapa e cada etapa pode
 substituí-lo com `timeout_seconds`. `max_flow_steps` reduz o limite por chamada,
 sem superar o teto da configuração. `return_snapshot` aceita `full`, `diff` ou
 `none`; `diff` retorna linhas acessíveis novas desde o snapshot inicial.
 
-Com `capture_console_errors` e `capture_network_errors`, o retorno traz
-`console_errors` e `network_failures`, limitados em quantidade e tamanho.
+Com `capture_console_errors` e `capture_network_errors`, o retorno traz
+`console_errors` e `network_failures`, limitados em quantidade e tamanho.
+Mensagens de erro idênticas do console são agrupadas em uma entrada com `count`.
 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
@@ -506,9 +534,49 @@ compartilhe os arquivos somente se o teste permitir.
 
 Screenshots por etapa usam `screenshot: true` no próprio passo; o MCP os grava
 depois que a ação termina. `options.report_path` pode apontar para `.md` ou
-JUnit `.xml` dentro da raiz de artefatos. O relatório inclui a versão, tempos,
-localizadores resolvidos, respostas verificadas por `assert_network`, falhas de
-rede e caminhos dos screenshots, para anexar a um PR ou card.
+JUnit `.xml` dentro da raiz de artefatos. O relatório inclui a versão, tempos,
+localizadores resolvidos, respostas verificadas por `assert_network`, falhas de
+rede e caminhos dos screenshots, para anexar a um PR ou card.
+
+`screenshot_on_success` grava a captura final em fluxos aprovados;
+`trace_on_success` salva trace também em sucesso e `record_video` grava vídeo
+WebM. Fluxos que digitam texto sensível suprimem screenshots, traces e vídeos
+para não registrar credenciais. `performance_metrics` inclui métricas do
+navegador quando disponíveis. `jev_browser_mcp.browser.max_tool_response_bytes`
+impõe um teto global de bytes na resposta JSON da ferramenta; se necessário,
+evidências volumosas são reduzidas e marcadas com `output_truncated: true`.
+
+Para testar microfone, conceda permissão no escopo da chamada:
+
+```json
+{
+  "options": {
+    "permissions": ["microphone"],
+    "fake_media": "fixtures/resposta-aluno.wav",
+    "block_trackers": true
+  }
+}
+```
+
+`fake_media` exige um WAV RIFF válido dentro de `JEV_BROWSER_UPLOAD_ROOT` e
+respeita os mesmos limites de upload. O MCP adiciona as opções de dispositivo
+falso do Chromium e concede permissão ao contexto. Sem esse arquivo, a
+permissão de microfone usa o dispositivo autorizado pelo browser; no modo
+`computer`, o sistema operacional ainda pode pedir acesso ao dispositivo.
+
+As opções de emulação aceitam `viewport: {"width": 390, "height": 844}`,
+`mobile: true`, `device_scale_factor`, `locale`, `timezone_id`,
+`color_scheme: "dark"` e `geolocation: {"latitude": -23.55, "longitude": -46.63}`.
+Informar geolocalização concede também a permissão `geolocation`.
+
+`audit_accessibility` aceita `scope` com seletor CSS e `fail_on_impact` com
+`minor`, `moderate`, `serious` ou `critical`. O padrão é `minor`; violações
+abaixo do impacto escolhido continuam no relatório, mas não bloqueiam o passo.
+`violations_count` e `blocking_violations_count` separam total e bloqueadoras.
+
+Os cliques aguardam `DOMContentLoaded` quando acionam navegação completa e
+tratam a destruição do contexto durante a troca de documento como navegação em
+andamento, sem repetir o clique.
 
 Se o Chrome/Edge não iniciar porque o perfil persistente já está aberto, o erro
 identifica o PID que o mantém ocupado quando o sistema consegue associar o
@@ -565,18 +633,21 @@ sob demanda podem excedê-la. O MCP devolve `total_ms`, `browser_session_ms`,
 para localizar o custo. O teto observado em um fluxo sintético local anterior
 foi 6,411 s; isso não mede o Instagram nem garante o mesmo tempo em outros sites.
 
-O snapshot inicial, o fluxo, o resultado esperado e as descrições dos planos
-são enviados ao endpoint Decisions quando há mais de uma opção. Com fast-path,
-um plano não gera chamada remota. Os passos, valores digitados, valores
-esperados pelas asserções, caminhos e conteúdo dos arquivos não são enviados.
+O snapshot inicial, o fluxo, o resultado esperado e as descrições dos planos
+são enviados ao endpoint Decisions quando há mais de uma opção. Antes do envio,
+valores dos controles são substituídos e hrefs têm query string e fragmento
+removidos; padrões de PII também são mascarados. Com fast-path, um plano não
+gera chamada remota. Os passos, valores digitados, valores esperados pelas
+asserções, caminhos e conteúdo dos arquivos não são enviados.
 Não inclua segredos em `flow`, `expected_outcome` ou nas descrições. A resposta
 retorna o plano escolhido quando houver decisão, custo/confiança do provedor
 quando disponíveis e o snapshot final sanitizado. O fluxo passa quando o texto
 esperado aparece no snapshot ou quando todas as asserções declaradas passam.
 
-`network_idle` é uma espera limitada e opcional; páginas com polling ou conexões
-contínuas podem atingir o timeout. Prefira `wait_for_text` e asserções de
-elemento quando houver um sinal de interface específico.
+`network_idle` é uma espera limitada e opcional. Polling e conexões contínuas
+não relacionadas a `url_contains` não bloqueiam o modo filtrado; prefira
+`wait_for_text` ou `assert_network` quando houver sinal de interface ou uma
+resposta HTTP específica.
 
 Consulte a [introdução do Jev](https://docs.typesafe.ai/introduction) e o
 [tutorial da API Decisions no OpenRouter](https://openrouter.ai/docs/guides/community/jev-tutorial)

package/config/ui-testing.json

@@ -38,7 +38,14 @@
       "visibility_poll_interval_ms_default": 50,
       "capture_network_error_bodies_default": false,
       "max_network_error_body_bytes": 65536,
-      "max_network_error_message_chars": 300,
+      "max_network_error_message_chars": 300,
+      "max_network_history_events": 4096,
+      "max_tool_response_bytes": 131072,
+      "max_viewport_width": 3840,
+      "max_viewport_height": 2160,
+      "accessibility_fail_on_impact_default": "minor",
+      "record_video_width": 1280,
+      "record_video_height": 720,
       "max_upload_files": 5,
       "max_upload_path_chars": 4096,
       "max_upload_file_bytes": 10485760,
@@ -53,7 +60,8 @@
       "max_frame_snapshots": 5,
       "fast_path_single_plan_default": true,
       "screenshot_on_failure_default": true,
-      "trace_on_failure_default": false,
+      "trace_on_failure_default": false,
+      "trace_on_success_default": false,
       "capture_console_errors_default": true,
       "capture_network_errors_default": false,
       "block_trackers_default": false,

package/docs/jev-browser-mcp.md

@@ -17,7 +17,7 @@ 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.6.1"],
+      "args": ["--yes", "@diegosouzacdv/jev-browser-mcp@0.6.2"],
       "env": {
         "OPENROUTER_API_KEY": "${OPENROUTER_API_KEY}",
         "JEV_BROWSER_MODE": "computer"
@@ -32,7 +32,7 @@ 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@0.6.1
+npm install @diegosouzacdv/jev-browser-mcp@0.6.2
 ```
 
 Se o harness executa o MCP repetidamente nesta máquina, instale uma versão
@@ -40,7 +40,7 @@ fixa globalmente para evitar a resolução e o download feitos pelo `npx` em cad
 inicialização:
 
 ```sh
-npm install --global @diegosouzacdv/jev-browser-mcp@0.6.1
+npm install --global @diegosouzacdv/jev-browser-mcp@0.6.2
 ```
 
 Depois configure o servidor MCP com `command: "jev-browser-mcp"` e `args: []`.
@@ -49,7 +49,7 @@ Para atualizar, rode `npm install --global
 
 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@0.6.1 --install-browser`.
+pelo Playwright com `npx --yes @diegosouzacdv/jev-browser-mcp@0.6.2 --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
@@ -107,11 +107,17 @@ a página inicial, captura o snapshot acessível e pede ao Jev que escolha um
 plano. Em seguida, executa o plano inteiro na mesma sessão e confere o
 resultado esperado na tela.
 
-Cada plano pode usar:
-
-- `click`, `type`, `hover`, `select_option`, `press`, `assert_*` e upload com
-  papel/nome acessível ou um localizador: `label`, `placeholder`, `title`,
-  `text`, `test_id` ou `selector`;
+Cada plano pode usar:
+
+- `navigate` para mudar de página no meio do fluxo. Com a continuidade ligada,
+  um `initial_url` de mesma origem diferente da URL ativa produz erro claro; use
+  `navigate` ou `continue_from_current_page: false` para escolher o destino;
+- `click`, `type`, `clear`, `hover`, `select_option`, `press`, `assert_*` e upload com
+  papel/nome acessível ou um localizador: `label`, `placeholder`, `title`,
+  `text`, `test_id` ou `selector`;
+- `name_match: "exact" | "contains" | "regex"` para controlar a comparação do
+  nome acessível; regex rejeita construções com backtracking excessivo. O papel
+  `switch` funciona em cliques, verificações e asserções;
 - `near: {"text":"..."}` para localizar o controle logo depois de um texto,
   `within: {"row_containing":"..."}` para limitar por trecho e
   `within: {"row_containing_exact":"..."}` para exigir um elemento com o
@@ -128,25 +134,34 @@ Cada plano pode usar:
 - `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;
-- `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. Nesse modo, `\n` envia Enter e `\t` envia Tab;
-- `wait_for_text`, `wait_for_value`, `wait_for_enabled` e `wait_for_condition`
-  (`network_idle`, `hidden`, `text_hidden` ou `angular_idle`). `wait` recebe
+- `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. `text_env` lê o valor sensível de uma variável
+  de ambiente do processo MCP, sem colocá-lo no plano. Nesse modo, `\n` envia
+  Enter e `\t` envia Tab;
+- `wait_for_text`, `wait_for_value`, `wait_for_enabled` e `wait_for_condition`
+  (`url`, `network_idle`, `hidden`, `text_hidden` ou `angular_idle`). `wait` recebe
   `ms` para uma pausa curta e limitada. `angular_idle` aguarda requisições
   `$http` e digest do AngularJS. `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. Se o alerta contiver o texto esperado, a etapa passa; caso contrário,
-  o alerta interrompe a espera. `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;
+  o alerta interrompe a espera. `url` aguarda a URL conter `url_contains`.
+  `network_idle` aceita esse filtro e aguarda uma janela de silêncio usando
+  `ready_stable_ms`; WebSocket, EventSource e polling não relacionado não
+  bloqueiam a espera. Se não surgir requisição correspondente, o passo conclui
+  após a janela de silêncio;
+- `press` (o alias legado `press_key` também é aceito) com `PageDown`, `PageUp`,
+  `Home`, `End`, setas, `Enter`, `Escape`, `Tab`, `Shift+Tab`, `Space`,
+  `Backspace` ou `Delete`. `clear` limpa um campo sem exigir texto. Sem alvo,
+  `press` envia a tecla ao elemento focado; com alvo, usa o localizador informado;
 - `assert_text`, `assert_value`, `assert_visible`, `assert_hidden` e
   `assert_enabled`; `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;
+- `upload_file` para input rotulado, botão que abre o seletor de arquivo ou
+  dropzone;
+- `target_page: "popup"` para continuar no popup aberto com `expect_popup: true`;
+  locators semânticos também atravessam open Shadow DOM. Shadow DOM fechado não
+  é acessível ao Playwright;
 - `audit_accessibility` com axe-core para WCAG 2.1 A/AA;
 - `like_comment` e `unlike_comment`, que localizam uma linha pelo autor e texto,
   não repetem uma reação já no estado pedido e distinguem `Curtir` de
@@ -211,11 +226,12 @@ com `within: {"row_containing_exact":"{pedido}"}`, e use uma etapa
 `{"action":"extract","role":"cell","name":"{pedido}","within":{"row_containing_exact":"{pedido}"},"as":"documento"}`.
 A etapa seguinte pode localizar o mesmo documento com `name: "{documento}"`.
 
-Em `wait_for_condition` com `condition: "hidden"`, use qualquer um desses
-localizadores, `near` ou `within`; `text_hidden` recebe o texto direto. Para
-aguardar o fim de uma chamada específica, use `condition: "network_idle"` com
-`url_contains`; o MCP precisa observar a requisição depois da etapa anterior e
-esperar que ela termine.
+Em `wait_for_condition` com `condition: "hidden"`, use qualquer um desses
+localizadores, `near` ou `within`; `text_hidden` recebe o texto direto. Para
+aguardar o fim de uma chamada específica, use `condition: "network_idle"` com
+`url_contains`. O filtro considera somente a atividade correspondente e termina
+após a janela configurada sem atividade; também termina caso nenhuma requisição
+correspondente apareça. Para validar status e corpo, prefira `assert_network`.
 
 Quando vários controles têm o mesmo papel e nome, `within` limita a busca a um
 container acessível único, como uma linha, card ou diálogo. `index` escolhe uma
@@ -411,15 +427,17 @@ validadores.
 
 `browser.mode` aceita `harness` ou `computer`; o padrão é `computer`:
 
-- `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.
+- `harness` usa Chrome headless e contexto isolado, adequado a execuções do
+  harness e CI. O processo MCP conserva browser, contexto e página entre
+  chamadas; cookies, local storage e estado da página permanecem enquanto o
+  processo estiver ativo. Encerre o processo para descartar o contexto isolado.
 - `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
   reutiliza o perfil pessoal já aberto. Faça login uma vez nesse perfil; os
   cookies permanecem nele entre chamadas.
 
-`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
+`browser.max_flow_steps` limita os passos de cada plano candidato; os planos
+não são somados. `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
@@ -457,9 +475,12 @@ O `run_browser_flow` aceita `options` com `fast_path`, `snapshot_scope`,
 `auto_angular_idle`, `login_url_contains`, `login_text`, `capture_console_errors`,
 `capture_network_errors`, `capture_network_error_bodies`, `ready_timeout_seconds`,
 `ready_network_idle`, `ready_stable_ms`, `ready_text`, `continue_from_current_page`,
-`reuse_page`, `step_timeout_seconds`, `max_flow_steps`, `return_snapshot`,
-`screenshot_on_failure`, `trace_on_failure`, `snapshot_include_hidden`,
-`stop_on_expected`, `dry_run`, `confirmation_token` e `report_path`. Sem override,
+`reuse_page`, `step_timeout_seconds`, `max_flow_steps`, `return_snapshot`,
+`screenshot_on_failure`, `screenshot_on_success`, `trace_on_failure`,
+`trace_on_success`, `record_video`, `snapshot_include_hidden`, `stop_on_expected`,
+`dry_run`, `confirmation_token`, `report_path`, `permissions`, `fake_media`,
+`viewport`, `mobile`, `device_scale_factor`, `locale`, `timezone_id`,
+`color_scheme`, `geolocation` e `allow_mutations`. 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
@@ -471,26 +492,33 @@ chamadas na mesma origem, não repete `page.goto` e consulta um snapshot atual
 sem esperar novamente por `load`/`networkidle`. As etapas continuam aguardando
 seus próprios alvos e condições. `reuse_page` segue como alias legado; defina
 `continue_from_current_page: false` para iniciar cada chamada em `initial_url`.
-Se a página atual e `initial_url` tiverem origens diferentes, o MCP navega para
-`initial_url`. Se forem da mesma origem, continua a página atual e avisa quando
-as URLs completas forem diferentes. `snapshot_scope` aceita `body`, `main` ou
-`dialog`; se `main` não existir, o snapshot usa `body`.
-
-`block_trackers: true` bloqueia analytics/trackers e os tipos de recurso
-configurados. Fontes ficam habilitadas por padrão para preservar ícones e
-glyphs; `block_fonts: true` bloqueia fontes separadamente. `busy_selectors`
-complementa `aria-busy="true"` ao aguardar overlays de carregamento.
+Se a página atual e `initial_url` tiverem origens diferentes, o MCP navega para
+`initial_url`. Se forem da mesma origem mas URLs completas diferentes, o MCP
+recusa continuar silenciosamente e pede uma etapa `navigate` ou
+`continue_from_current_page: false`. `snapshot_scope` aceita `body`, `main` ou
+`dialog`; se `main` não existir, o snapshot usa `body`.
+
+`block_trackers: true` bloqueia analytics/trackers e os tipos de recurso
+configurados, mas preserva `media` quando há permissão de microfone ou
+`fake_media`. Fontes ficam habilitadas por padrão para preservar ícones e
+glyphs; `block_fonts: true` bloqueia fontes separadamente. `busy_selectors`
+complementa `aria-busy="true"` ao aguardar overlays; elementos ocultos ou fora
+da tela com esse atributo não seguram a prontidão da página.
 `auto_angular_idle` aguarda AngularJS depois de cliques e digitação quando a
 página expõe o injector. `login_url_contains` e `login_text` substituem a
 detecção padrão de autenticação. `local_only: true` recusa qualquer etapa que
-precisaria chamar o provedor Jev; use exatamente um plano com `fast_path: true`.
+precisaria chamar o provedor Jev; use exatamente um plano com `fast_path: true`.
+`allow_mutations: true` pula a confirmação humana somente para URLs em
+`localhost`, `127.0.0.1` ou `::1`; use esse modo apenas em ambientes locais
+controlados.
 `step_timeout_seconds` define o timeout padrão por etapa e cada etapa pode
 substituí-lo com `timeout_seconds`. `max_flow_steps` reduz o limite por chamada,
 sem superar o teto da configuração. `return_snapshot` aceita `full`, `diff` ou
 `none`; `diff` retorna linhas acessíveis novas desde o snapshot inicial.
 
-Com `capture_console_errors` e `capture_network_errors`, o retorno traz
-`console_errors` e `network_failures`, limitados em quantidade e tamanho.
+Com `capture_console_errors` e `capture_network_errors`, o retorno traz
+`console_errors` e `network_failures`, limitados em quantidade e tamanho.
+Mensagens de erro idênticas do console são agrupadas em uma entrada com `count`.
 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
@@ -506,9 +534,49 @@ compartilhe os arquivos somente se o teste permitir.
 
 Screenshots por etapa usam `screenshot: true` no próprio passo; o MCP os grava
 depois que a ação termina. `options.report_path` pode apontar para `.md` ou
-JUnit `.xml` dentro da raiz de artefatos. O relatório inclui a versão, tempos,
-localizadores resolvidos, respostas verificadas por `assert_network`, falhas de
-rede e caminhos dos screenshots, para anexar a um PR ou card.
+JUnit `.xml` dentro da raiz de artefatos. O relatório inclui a versão, tempos,
+localizadores resolvidos, respostas verificadas por `assert_network`, falhas de
+rede e caminhos dos screenshots, para anexar a um PR ou card.
+
+`screenshot_on_success` grava a captura final em fluxos aprovados;
+`trace_on_success` salva trace também em sucesso e `record_video` grava vídeo
+WebM. Fluxos que digitam texto sensível suprimem screenshots, traces e vídeos
+para não registrar credenciais. `performance_metrics` inclui métricas do
+navegador quando disponíveis. `jev_browser_mcp.browser.max_tool_response_bytes`
+impõe um teto global de bytes na resposta JSON da ferramenta; se necessário,
+evidências volumosas são reduzidas e marcadas com `output_truncated: true`.
+
+Para testar microfone, conceda permissão no escopo da chamada:
+
+```json
+{
+  "options": {
+    "permissions": ["microphone"],
+    "fake_media": "fixtures/resposta-aluno.wav",
+    "block_trackers": true
+  }
+}
+```
+
+`fake_media` exige um WAV RIFF válido dentro de `JEV_BROWSER_UPLOAD_ROOT` e
+respeita os mesmos limites de upload. O MCP adiciona as opções de dispositivo
+falso do Chromium e concede permissão ao contexto. Sem esse arquivo, a
+permissão de microfone usa o dispositivo autorizado pelo browser; no modo
+`computer`, o sistema operacional ainda pode pedir acesso ao dispositivo.
+
+As opções de emulação aceitam `viewport: {"width": 390, "height": 844}`,
+`mobile: true`, `device_scale_factor`, `locale`, `timezone_id`,
+`color_scheme: "dark"` e `geolocation: {"latitude": -23.55, "longitude": -46.63}`.
+Informar geolocalização concede também a permissão `geolocation`.
+
+`audit_accessibility` aceita `scope` com seletor CSS e `fail_on_impact` com
+`minor`, `moderate`, `serious` ou `critical`. O padrão é `minor`; violações
+abaixo do impacto escolhido continuam no relatório, mas não bloqueiam o passo.
+`violations_count` e `blocking_violations_count` separam total e bloqueadoras.
+
+Os cliques aguardam `DOMContentLoaded` quando acionam navegação completa e
+tratam a destruição do contexto durante a troca de documento como navegação em
+andamento, sem repetir o clique.
 
 Se o Chrome/Edge não iniciar porque o perfil persistente já está aberto, o erro
 identifica o PID que o mantém ocupado quando o sistema consegue associar o
@@ -565,18 +633,21 @@ sob demanda podem excedê-la. O MCP devolve `total_ms`, `browser_session_ms`,
 para localizar o custo. O teto observado em um fluxo sintético local anterior
 foi 6,411 s; isso não mede o Instagram nem garante o mesmo tempo em outros sites.
 
-O snapshot inicial, o fluxo, o resultado esperado e as descrições dos planos
-são enviados ao endpoint Decisions quando há mais de uma opção. Com fast-path,
-um plano não gera chamada remota. Os passos, valores digitados, valores
-esperados pelas asserções, caminhos e conteúdo dos arquivos não são enviados.
+O snapshot inicial, o fluxo, o resultado esperado e as descrições dos planos
+são enviados ao endpoint Decisions quando há mais de uma opção. Antes do envio,
+valores dos controles são substituídos e hrefs têm query string e fragmento
+removidos; padrões de PII também são mascarados. Com fast-path, um plano não
+gera chamada remota. Os passos, valores digitados, valores esperados pelas
+asserções, caminhos e conteúdo dos arquivos não são enviados.
 Não inclua segredos em `flow`, `expected_outcome` ou nas descrições. A resposta
 retorna o plano escolhido quando houver decisão, custo/confiança do provedor
 quando disponíveis e o snapshot final sanitizado. O fluxo passa quando o texto
 esperado aparece no snapshot ou quando todas as asserções declaradas passam.
 
-`network_idle` é uma espera limitada e opcional; páginas com polling ou conexões
-contínuas podem atingir o timeout. Prefira `wait_for_text` e asserções de
-elemento quando houver um sinal de interface específico.
+`network_idle` é uma espera limitada e opcional. Polling e conexões contínuas
+não relacionadas a `url_contains` não bloqueiam o modo filtrado; prefira
+`wait_for_text` ou `assert_network` quando houver sinal de interface ou uma
+resposta HTTP específica.
 
 Consulte a [introdução do Jev](https://docs.typesafe.ai/introduction) e o
 [tutorial da API Decisions no OpenRouter](https://openrouter.ai/docs/guides/community/jev-tutorial)