@diegosouzacdv/jev-browser-mcp 0.6.1 → 0.7.0

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.7.0"],
       "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.7.0
 ```
 
 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.7.0
 ```
 
 Depois configure o servidor MCP com `command: "jev-browser-mcp"` e `args: []`.
@@ -49,14 +49,23 @@ 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`.
-
-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`
+pelo Playwright com `npx --yes @diegosouzacdv/jev-browser-mcp@0.7.0 --install-browser`.
+
+O padrão é `computer`: o pacote abre o Chrome/Edge instalado e usa um perfil
+persistente exclusivo por processo MCP em `browser.computer_user_data_dir`. O
+template aceita `{browser}` e `{session}`; por padrão, `{session}` é `pid-<PID>`.
+Use um `JEV_BROWSER_SESSION_ID` único por instância para manter um nome estável
+entre reinicializações. Um
+`JEV_BROWSER_PROFILE` explícito também recebe o sufixo da sessão, a menos que o
+caminho contenha `{session}`. Assim, processos MCP independentes não disputam o
+mesmo perfil. Clientes conectados ao mesmo processo MCP compartilham a sessão;
+para isolamento entre harnesses, execute uma instância por sessão. 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`. Sem um ID estável, o perfil é específico do processo e
+uma reinicialização começa outra sessão. 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
 nome de variável declarado em `jev.credential_env`.
 
@@ -76,8 +85,12 @@ publicada.
 
 ### Contrato do pacote
 
-O executável oferece `browser_health`, `choose_next_action` e `run_browser_flow`, mantém uma
-sessão do browser por processo e reutiliza essa sessão entre chamadas. O plano
+O executável oferece `browser_health`, `describe_actions`, `choose_next_action`
+e `run_browser_flow`, mantém uma sessão do browser por processo e reutiliza
+essa sessão entre chamadas. `browser_health` informa versão, sessão e
+capacidades; `describe_actions` publica o schema atual das ações, opções,
+aliases e placeholders. Consulte essas ferramentas antes de construir um plano
+para evitar nomes de campos desatualizados. O plano
 passado ao Jev continua declarativo: clique, preenchimento, seleção nativa,
 hover, espera, teclas aprovadas, asserções por elemento, upload restrito a uma
 raiz local configurada e reações idempotentes a um comentário único. Também
@@ -107,11 +120,22 @@ 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`, `check`, `uncheck`, `type`, `clear`, `hover`, `select_option`,
+  `press` e `assert_*` aceitam papel/nome acessível ou localizadores como
+  `label`, `placeholder`, `title`, `text`, `test_id` e `selector`;
+- `screenshot` e `clear_storage` atuam na página/contexto atual; `upload_file`
+  recebe o arquivo e o alvo de upload. Os limites e formatos estão descritos nas
+  seções de evidências e upload;
+- `navigate_menu` para percorrer uma sequência de rótulos de menu; veja a seção
+  de navegação de menus para o formato e as opções;
+- `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
@@ -125,28 +149,64 @@ Cada plano pode usar:
   espaços/glyphs de uso privado, como ícones Font Awesome; 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;
+- `selector` com CSS ou XPath como último recurso. O MCP identifica essa escolha
+  em `warnings`; não é permitido enviar JavaScript nem coordenadas;
+- quando `click` falha porque o alvo está fora da viewport ou não está visível,
+  o MCP tenta rolar o alvo até a tela; se isso não bastar, tenta focar o controle
+  e enviar `Enter`, sem repetir cegamente o clique;
 - `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` 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;
+- `assert_network` valida resposta HTTP observada (inclusive sucesso 2xx ou erro
+  esperado); `wait_for_request` aguarda uma resposta usando `*` como curinga na
+  URL e filtros opcionais de método/status; `assert_ws` confere texto, pares
+  JSON esperados ou código de fechamento de WebSocket;
+- `evaluate` lê somente caminhos de propriedades como `navigator.mediaDevices`,
+  `document.readyState` ou `location.pathname`. Não aceita código, chamadas de
+  função, armazenamento local ou propriedades de credenciais. Strings e números
+  voltam diretamente; objetos e arrays retornam somente tipo, chaves e tamanho,
+  sem despejar seus valores;
+- `new_tab`, `switch_tab` e `new_context` abrem/selecionam abas e criam contexto
+  separado dentro do fluxo; `target_page: "popup"` mantém popups abertos para
+  passos posteriores;
+- `if_visible` em um clique torna a ação condicional e
+  `when: {"visible":"..."}` em cada plano limita as opções do Jev às que
+  correspondem à tela atual;
+- `fill` é alias de `type`, `press_key` de `press`, `duration_ms` de `wait.ms` e
+  `value` de campos de texto. `timeout_ms` funciona por etapa. Placeholders usam
+  `{nome}`; referências desconhecidas e `{{nome}}` são recusadas antes da
+  navegação;
+- `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;
+- `screenshot` grava uma imagem local; `full_page: true` inclui a página inteira.
+  Também é possível pedir uma captura após qualquer etapa com `screenshot: true`;
+- `clear_storage` limpa cookies, local/session storage, IndexedDB, Cache Storage
+  e service workers do contexto atual. Como opção de fluxo,
+  `options.clear_storage: true` também recarrega a página antes do snapshot inicial;
 - `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
@@ -154,19 +214,25 @@ Cada plano pode usar:
 
 As proteções e evidências por etapa usam estes campos:
 
-- `confirm_dialog` recebe `expected_text` e `button`. Em diálogos HTML, o MCP
-  confere o texto antes de localizar e clicar no botão. Também trata diálogos
-  nativos `alert`/`confirm`: precisa haver uma etapa `confirm_dialog` logo após
-  o clique que os abre, o texto deve corresponder e um diálogo inesperado é
-  fechado sem aceitar;
-- `mutating: true` marca etapas que gravam dados ou disparam efeitos externos.
+- `confirm_dialog` recebe `expected_text` e `button`. Em diálogos HTML, o MCP
+  confere o texto antes de localizar e clicar no botão. Também trata diálogos
+  nativos `alert`/`confirm`: precisa haver uma etapa `confirm_dialog` logo após
+  o clique que os abre, o texto deve corresponder e um diálogo inesperado é
+  fechado sem aceitar;
+- `confirm_modal` combina o clique no gatilho, a conferência do texto e o clique
+  afirmativo em uma única etapa protegida. Também aceita os aliases
+  `trigger`/`confirm`, por exemplo
+  `{"action":"confirm_modal","trigger":"Salvar","expected_text":"Confirma a alteração?","confirm":"OK"}`;
+- `mutating: true` marca etapas que gravam dados ou disparam efeitos externos.
   O MCP também classifica botões conhecidos como `Salvar`, `Emitir`, `Cancelar`
   ou `Sim` pelo nome e pelo controle resolvido, inclusive quando o plano usa um
   seletor CSS. `options.dry_run: true` executa até a primeira etapa mutável e
   para antes dela; retorna `dry_run_stopped_before_step` e um
-  `confirmation_token` temporário, de uso único e vinculado ao fluxo e à página.
-  Reenvie a mesma chamada com `options.confirmation_token` para autorizar essa
-  etapa. O MCP pausa novamente antes de cada outra etapa mutável. Sem `dry_run`,
+  `confirmation_token` temporário, de uso único e vinculado ao fluxo e à página.
+  Reenvie a mesma chamada com `options.confirmation_token` para retomar no passo
+  pausado sem repetir os passos anteriores; o MCP confere a rota e o alvo da
+  mutação antes de executá-la. Ele pausa novamente antes de cada outra etapa
+  mutável. Sem `dry_run`,
   o primeiro pedido de ação mutável também retorna `status: "confirmation_required"`
   e token; nenhuma etapa mutável roda sem essa autorização. O token expira após
   dez minutos por padrão;
@@ -202,20 +268,37 @@ incluindo respostas 2xx ou erros esperados como 404. Exemplo:
 }
 ```
 
-Essa asserção aparece na evidência como `response_status`, separado do campo
-`status` da etapa (`passed` ou `failed`). `message_contains` lê somente resposta
-da mesma origem e respeita o limite configurado para captura de corpos.
+Essa asserção aparece na evidência como `response_status`, separado do campo
+`status` da etapa (`passed` ou `failed`). `message_contains` lê somente resposta
+da mesma origem e respeita o limite configurado para captura de corpos.
+`assert_network`, `wait_for_request` e `expected_outcome.request` consultam o
+histórico limitado de respostas depois do marcador da etapa ou do início do
+fluxo. O limite vem de `jev_browser_mcp.browser.max_network_history_events` e
+está em 4096 eventos nesta configuração; assim, chamadas anteriores ao marcador
+não satisfazem a asserção.
+
+Para aguardar a API antes de abrir a interface, passe
+`options.wait_for_http: {"url":"http://localhost:8000/health","timeout_ms":30000}`.
+Também aceita apenas a URL como string ou `{ "url": "...", "timeout_seconds": 30 }`.
+O probe faz GET e tenta novamente até o limite; qualquer resposta abaixo de 500
+indica que o servidor respondeu (inclusive 4xx), enquanto 5xx e erros de conexão
+são repetidos. Ao expirar, `reason` inclui a última causa. Por segurança, a URL
+precisa ser loopback ou usar o mesmo host de `initial_url`; isso permite, por
+exemplo, Vite em `localhost:5173` e API em `localhost:8000`.
 
 Exemplo de parâmetro e extração: passe `params: {"pedido":"1528721"}`, filtre
 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`; para esperar texto desaparecer, use
+`{"condition":"hidden","text":"Carregando..."}`. Para esperar que texto suma
+antes do primeiro passo, use `options.ready: {"hidden_text":"Carregando..."}`.
+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
@@ -223,7 +306,7 @@ ocorrência zero-based dentro desse escopo; sem `index`, o MCP exige exatamente
 um alvo. Para uma página com rótulo `for` quebrado, `label` também procura o
 controle próximo ao texto visível do rótulo.
 
-`within` pode combinar um container e uma linha. Use, por exemplo,
+`within` pode combinar um container e uma linha. Use, por exemplo,
 `{"role":"cell","name":"Documento A","within":{"role":"table","row_containing_word":"1528721"}}`.
 `row_containing_word` usa limites de palavra para não confundir `1528721` com
 `15287210`; `row_containing_exact` continua disponível para texto de célula
@@ -258,13 +341,14 @@ Exemplos para controles legados sem nome acessível:
 {"action":"click","selector":"#save-document"}
 ```
 
-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. Nomes vazios ou compostos apenas por espaços e glyphs da área Unicode
-de uso privado (como ícones Font Awesome) entram nessa lista e podem ser
-selecionados com `name: ""` e o mesmo índice. `unnamed_controls` continua
-disponível como alias da lista final. O placeholder conta como nome acessível.
+Por padrão, controles sem nome não são devolvidos em listas separadas. Defina
+`options.include_unnamed_controls: true` para receber
+`unnamed_controls_initial` e `unnamed_controls_final`, cada uma com papel,
+índice Playwright por papel, rótulo mais próximo e um trecho HTML sanitizado.
+Nomes vazios ou compostos apenas por espaços e glyphs da área Unicode de uso
+privado (como ícones Font Awesome) entram nessa lista e podem ser selecionados
+com `name: ""` e o mesmo índice. O alias redundante `unnamed_controls` foi
+removido. 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`
@@ -275,10 +359,14 @@ Em uma etapa `type`, `text` contém o valor a digitar; use `target_text` para
 localizar pelo texto visível próximo ao campo. Esse localizador exige `role`
 `textbox`, `searchbox` ou `combobox`.
 
-Por padrão, o MCP executa todos os passos antes de avaliar `expected_outcome`.
-Valores dentro de campos não contam como resultado visível. `stop_on_expected:
-true` habilita parada antecipada quando o texto esperado aparece fora dos
-campos; mantenha `false` para fluxos com várias etapas.
+Por padrão, o MCP executa todos os passos antes de avaliar os critérios.
+`expected_outcome` aceita texto descritivo ou uma asserção estruturada, por
+exemplo `{"text":"Tecnologia atualizada com sucesso."}` ou
+`{"request":"PUT */api/tecnologia","status":200}`. A forma estruturada pode
+incluir `message_contains` e reprova se a resposta correspondente não for
+observada. Valores dentro de campos não contam como texto visível.
+`stop_on_expected: true` habilita parada antecipada quando o texto esperado
+aparece fora dos campos; mantenha `false` para fluxos com várias etapas.
 
 Os erros de validação apontam o campo inválido e os campos aceitos. Os limites
 de `timeout_seconds` informam o máximo configurado, em vez de exigir tentativa
@@ -314,11 +402,13 @@ verificar:
 {"action":"audit_accessibility","standard":"wcag2aa"}
 ```
 
-O MCP usa `@axe-core/playwright` com as tags WCAG 2.0 e 2.1 A/AA. O retorno
-resume as violações por regra, impacto e quantidade de nós, sem copiar HTML ou
-trechos da página. Qualquer violação reprova esse fluxo. A auditoria automática
-encontra problemas comuns, mas não comprova conformidade WCAG completa; combine-a
-com revisão manual e testes com usuários assistivos.
+O MCP usa `@axe-core/playwright` com as tags WCAG 2.0 e 2.1 A/AA. O retorno
+resume as violações por regra, impacto e quantidade de nós, sem copiar HTML ou
+trechos da página. A etapa falha quando encontra violações no impacto definido
+por `fail_on_impact`; o padrão é `minor`, e níveis abaixo do limite são relatados
+sem bloquear o fluxo. A auditoria automática encontra problemas comuns, mas não
+comprova conformidade WCAG completa; combine-a com revisão manual e testes com
+usuários assistivos.
 
 Para ações em iframe, acrescente `"frame": "payment-iframe"`; o valor precisa
 corresponder ao atributo `name` ou `title` do iframe. O snapshot inclui o
@@ -411,27 +501,67 @@ 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.
-- `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
-`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, 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,
-nome acessível, `title` casado e `href` sanitizado do elemento resolvido.
-Etapas `type` só incluem o valor final do campo quando `sensitive: false`.
+- `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 e por
+  processo MCP. Não
+  reutiliza o perfil pessoal já aberto. Faça login uma vez nesse perfil; os
+  cookies permanecem nele entre chamadas.
+
+`fresh_context: true` abre um contexto descartável, sem cookies nem storage do
+perfil persistente; requer `initial_url` e fecha esse contexto ao terminar. Use
+`clear_storage: true` para limpar cookies, local/session storage, IndexedDB,
+Cache Storage e service workers antes de recarregar a página atual. Para salvar
+e reutilizar o estado de autenticação de uma conta de teste, use um nome simples
+em `storage_state`:
+
+```json
+{"options":{"storage_state":"aluno-a"}}
+```
+
+O estado fica em `storage-state/<nome>.json` dentro da pasta de artefatos, com
+permissões restritas no sistema operacional; não use uma conta real nem
+compartilhe esse arquivo. `storage_state` não pode ser combinado com
+`fresh_context` ou `clear_storage`.
+
+`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 texto descritivo esperado apareceu. `expected_outcome`
+como string é descrição, não uma asserção: `expected_outcome_visible` é
+informado separadamente, e um plano concluído pode passar mesmo se a frase não
+estiver visível. Use `{ "text": "..." }` ou
+`{ "request": "...", "status": 200 }` para exigir uma condição; as
+verificações ficam em `expected_outcome_checks`, e uma condição não satisfeita
+reprova o fluxo. As asserções `assert_*`, auditorias de acessibilidade e
+downloads também aparecem em campos próprios do resultado.
+
+Os status do fluxo incluem `passed`, `failed`, `incomplete`, `environment_error`,
+`dry_run` e `confirmation_required`. O fluxo fica `passed` se não houve falha ou
+pausa de mutação e o texto esperado apareceu, uma asserção/auditoria/download
+passou ou todas as etapas do plano foram executadas. `incomplete` é devolvido
+quando nenhuma dessas condições se aplica; confiança do Jev, sozinha, não
+comprova o resultado. `environment_error` identifica falha de
+navegação, autenticação ou sessão do browser; `navigation_error` contém o código
+detectado, como `ERR_CONNECTION_REFUSED`, `AUTHENTICATION_REQUIRED` ou
+`BROWSER_DISCONNECTED`, e `reason` orienta a recuperação. Se uma navegação falhar
+e a chamada seguinte tentar reutilizar a página, o MCP informa que a navegação
+anterior não carregou; reinicie a navegação com
+`continue_from_current_page: false` (ou o alias `reuse_page: false`). Uma sessão
+desconectada pode ser reaberta por `browser_health`; o fluxo só é repetido
+automaticamente uma vez se nenhuma etapa mutável tiver sido executada.
+
+`current_url` é devolvido para diagnóstico sem query string nem fragmento; IDs
+longos no caminho também podem ser redigidos. `timings_ms.ready_ms` mede a espera
+da SPA; `warnings` registra capturas vazias durante transições; e `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, nome acessível,
+`title` casado e `href` sanitizado 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
@@ -455,42 +585,70 @@ continua informada mesmo quando a lista é truncada.
 O `run_browser_flow` aceita `options` com `fast_path`, `snapshot_scope`,
 `block_trackers`, `block_fonts`, `local_only`, `busy_selectors`,
 `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,
-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 plano roda até o fim e campos ocultos não são
-acrescentados ao snapshot. O browser espera a SPA renderizar uma captura
-acessível estável na navegação inicial. Depois, a continuidade fica ligada por
+`capture_network_errors`, `capture_network_error_bodies`, `ready_timeout_seconds`,
+`ready_network_idle`, `ready_stable_ms`, `ready_text`, `ready`, `continue_from_current_page`,
+`reuse_page`, `reuse_page_match`, `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`, `include_unnamed_controls`, `stop_on_expected`,
+`dry_run`, `confirmation_token`, `report_path`, `permissions`, `fake_media`,
+`viewport`, `mobile`, `device_scale_factor`, `locale`, `timezone_id`,
+`color_scheme`, `geolocation`, `console_levels`, `fresh_context`,
+`clear_storage`, `storage_state`, `wait_for_http` 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
+de recursos ficam desligados; o plano roda até o fim e campos ocultos não são
+acrescentados ao snapshot. `return_snapshot: "diff"` é o padrão, e as listas de
+controles sem nome só aparecem com `include_unnamed_controls: true`. O browser
+espera a SPA renderizar uma captura acessível estável na navegação inicial.
+Depois, a continuidade fica ligada por
 padrão: `continue_from_current_page: true` mantém a página e seu estado entre
 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`. URLs da mesma origem são comparadas após normalizar e ordenar a
+query string. Se a rota normalizada diferir, o MCP pede uma etapa `navigate` ou
+`continue_from_current_page: false`. `reuse_page_match: "path"` ignora a query;
+um plano cuja primeira etapa seja `navigate` pode trocar a rota explicitamente.
+`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`.
-`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.
+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 `diff`, `full` ou
+`none`; `diff` retorna linhas acessíveis novas desde o snapshot inicial.
+
+`options.ready` aguarda condições da aplicação antes do primeiro snapshot e da
+seleção do plano. Aceita `"network_idle"`,
+`{"hidden_text":"Aguarde."}` e `{"selector":"#cdTecnologia","has_value":true}`;
+uma lista combina condições, e todas precisam passar. `has_value` aceita
+`true` (valor não vazio), `false` (vazio) ou o valor textual exato.
+`ready_text` também pode exigir uma frase no snapshot inicial;
+`ready_network_idle: true` solicita uma espera best-effort por `networkidle`.
+`ready_timeout_seconds` limita a espera de inicialização e `ready_stable_ms`
+define a janela usada para considerar o snapshot estável.
+
+`console_levels` aceita `log`, `info`, `debug`, `warn` e `error`. Com
+`console_levels: ["log","warn","error"]` e `capture_network_errors`, o retorno
+traz mensagens do console agrupadas por texto e nível (`console_messages` com
+`count`), além de `console_errors` para compatibilidade. `network_failures`
+contém eventos limitados em quantidade e tamanho. Mensagens 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,15 +664,59 @@ 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": {"audio":"fixtures/resposta-aluno.wav"},
+    "block_trackers": true
+  }
+}
+```
+
+`fake_media` aceita tanto o caminho WAV direto quanto o objeto
+`{"audio":"caminho.wav"}`. Exige um WAV RIFF válido dentro de
+`JEV_BROWSER_UPLOAD_ROOT` e respeita os mesmos limites de upload. Ao informar
+`fake_media`, o MCP concede automaticamente a permissão `microphone`, adiciona
+as opções de dispositivo falso do Chromium e usa o arquivo como entrada de
+áudio. 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
-perfil ao processo. Em Windows, o MCP consulta a linha de comando dos processos
-Chrome/Edge; em outros sistemas, usa o `SingletonLock` do Chromium. Configure
-`JEV_BROWSER_PROFILE` com outro diretório absoluto para usar uma sessão isolada.
+perfil ao processo. Em Windows, o MCP consulta a linha de comando dos processos
+Chrome/Edge; em outros sistemas, usa o `SingletonLock` do Chromium. O caminho
+padrão já separa processos por PID; configure `JEV_BROWSER_PROFILE` para mudar
+a raiz e `JEV_BROWSER_SESSION_ID` para nomear a instância.
 Resultados MCP incluem `server_version`; erros também começam com a versão do
 servidor para facilitar a comparação entre instalações. A ferramenta
 `browser_health` informa se a sessão está ativa e tenta reconectar um browser
@@ -523,11 +725,50 @@ reiniciar somente o navegador administrado por este processo MCP. Um fluxo pode
 ser repetido automaticamente uma vez após `BROWSER_DISCONNECTED` quando nenhuma
 etapa mutável foi executada.
 
-`harness_browser` e `computer_browser` aceitam `chrome` ou `msedge`.
-`computer_user_data_dir` deve ficar fora do repositório e conter `{browser}`;
-o diretório persistente armazena dados de login e é resolvido sob a pasta home
-do usuário quando começa com `~`. O Playwright MCP fica desabilitado até
-`ORQUESTRADOR_MCP_PLAYWRIGHT_ENABLED=1` ser configurado no ambiente do harness.
+`harness_browser` e `computer_browser` aceitam `chrome` ou `msedge`.
+`computer_user_data_dir` deve ficar fora do repositório e conter `{browser}` e
+`{session}`;
+o diretório persistente armazena dados de login e é resolvido sob a pasta home
+do usuário quando começa com `~`. O Playwright MCP fica desabilitado até
+`ORQUESTRADOR_MCP_PLAYWRIGHT_ENABLED=1` ser configurado no ambiente do harness.
+
+## Preparar smoke autenticado local
+
+O MCP não cria a identidade nem os dados do sistema testado. Para um smoke de
+administração, suba a API e a UI locais, use um banco descartável com dados
+fictícios e uma identidade OIDC de teste que tenha explicitamente a claim
+`administrator`. Mantenha as regras de autorização de produção iguais; um token
+de operador legado não deve ser promovido para admin só para fazer o smoke.
+
+Faça o preflight nesta ordem:
+
+1. `browser_health` confirma a versão, o perfil/sessão e a conexão do navegador.
+   Se o perfil estiver ocupado, use outro `JEV_BROWSER_SESSION_ID` ou
+   `JEV_BROWSER_PROFILE`; não encerre o Chrome do operador.
+2. `options.wait_for_http` aguarda a API local responder antes de abrir a UI.
+   Informe a URL da interface em `initial_url` e a rota de health da API no
+   probe.
+3. `run_browser_flow` confirma que a tela administrativa esperada está visível
+   e que a identidade abriu com papel administrativo. Se aparecer a tela de
+   login, configure a conta de teste ou o provedor OIDC local; não copie o token
+   para `flow`, `params` ou logs. Use `text_env` para campos secretos.
+4. Valide primeiro uma prévia read-only com `assert_*`, `assert_network` e
+   captura de evidência. Para um fluxo que poderia gravar dados, use
+   `dry_run: true`; ele para antes da primeira etapa marcada como mutável.
+5. Só execute o passo de gravação em dados fictícios, depois de conferir o texto
+   do diálogo com `confirm_modal`/`confirm_dialog` e autorizar o token de
+   confirmação. Reinicializações de serviços e consultas diretas ao banco ficam
+   fora do smoke de tela.
+
+Esse preflight é um roteiro composto por `browser_health`, `wait_for_http` e
+asserções da própria aplicação; não há uma ferramenta genérica que valide a
+claim OIDC `administrator`. A checagem do papel precisa usar um sinal visível ou
+uma asserção específica do sistema consumidor.
+
+Um `expected_outcome` descreve o objetivo; o resultado `passed` vem das
+asserções explícitas ou da conclusão do plano. Verifique
+`expected_outcome_visible` separadamente quando a frase global fizer parte do
+critério do teste.
 
 Defina o valor secreto na variável indicada por `jev.credential_env`, usando o
 secret manager ou ambiente do processo que inicia o harness. Não grave a chave
@@ -565,18 +806,24 @@ 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.
-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.
+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. Um `expected_outcome` em
+texto simples é descritivo: `expected_outcome_visible` indica separadamente se
+a frase apareceu, e completar o plano pode resultar em `passed` mesmo que ela
+não apareça. Use a forma estruturada para tornar texto ou resposta de rede uma
+condição obrigatória; se ela não passar, o fluxo falha.
+
+`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)