@diegosouzacdv/jev-browser-mcp 0.5.0 → 0.6.1

package/README.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.5.0"],
+      "args": ["--yes", "@diegosouzacdv/jev-browser-mcp@0.6.1"],
       "env": {
         "OPENROUTER_API_KEY": "${OPENROUTER_API_KEY}",
-        "JEV_BROWSER_MODE": "computer"
+        "JEV_BROWSER_MODE": "computer"
       }
     }
   }
@@ -31,30 +31,30 @@ 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
-```
-
-Se o harness executa o MCP repetidamente nesta máquina, instale uma versão
-fixa globalmente para evitar a resolução e o download feitos pelo `npx` em cada
-inicialização:
-
-```sh
-npm install --global @diegosouzacdv/jev-browser-mcp@0.5.0
-```
-
-Depois configure o servidor MCP com `command: "jev-browser-mcp"` e `args: []`.
-Para atualizar, rode `npm install --global
-@diegosouzacdv/jev-browser-mcp@<versão>` e reinicie o processo do harness.
-
-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
+```sh
+npm install @diegosouzacdv/jev-browser-mcp@0.6.1
+```
+
+Se o harness executa o MCP repetidamente nesta máquina, instale uma versão
+fixa globalmente para evitar a resolução e o download feitos pelo `npx` em cada
+inicialização:
+
+```sh
+npm install --global @diegosouzacdv/jev-browser-mcp@0.6.1
+```
+
+Depois configure o servidor MCP com `command: "jev-browser-mcp"` e `args: []`.
+Para atualizar, rode `npm install --global
+@diegosouzacdv/jev-browser-mcp@<versão>` e reinicie o processo do harness.
+
+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`
 e `JEV_MODEL` podem substituir os valores centrais; a credencial continua no
@@ -64,35 +64,41 @@ 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 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.
+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
 
-O executável oferece `choose_next_action` e `run_browser_flow`, mantém uma
+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
 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
-aceita um nome de iframe para as ações que ocorrem dentro dele. Não aceita
-JavaScript enviado pelo harness nem coordenadas. Além de papel/nome acessível,
-aceita `label`, `placeholder`, `title`, `text`, `test_id` e `selector`; CSS/XPath
-são o último recurso e geram um aviso no resultado. Ele usa a
-biblioteca Playwright diretamente, sem iniciar um segundo servidor MCP do
+aceita um nome de iframe para as ações que ocorrem dentro dele. Não aceita
+JavaScript enviado pelo harness nem coordenadas. Além de papel/nome acessível,
+aceita `label`, `placeholder`, `title`, `text`, `test_id` e `selector`; CSS/XPath
+são o último recurso e geram um aviso no resultado. Ele usa a
+biblioteca Playwright diretamente, sem iniciar um segundo servidor MCP do
 Playwright. O transporte MCP usa `stdio`; toda saída de diagnóstico vai para
 `stderr` para não misturar com JSON-RPC.
 
 O modo `computer` grava cookies no perfil exclusivo configurado, e conteúdo da
 página pode conter instruções maliciosas. O Jev recebe a captura acessível com
 uma instrução para tratar esse conteúdo como dado não confiável; não inclua
-segredos no fluxo, no resultado esperado ou nas descrições dos planos.
+segredos no fluxo, no resultado esperado ou nas descrições dos planos. Antes de
+enviar contexto ao provedor, o cliente mascara valores de campos e padrões
+detectados de CPF/CNPJ, email, telefone, nome de cliente e valores monetários.
+Isso reduz exposição acidental, mas não substitui o cuidado com os dados que o
+harness escolhe incluir no fluxo. Use `local_only: true` quando nenhuma chamada
+externa ao Jev puder ocorrer; esse modo recusa fluxos que precisam escolher
+entre vários planos.
 
 Para um fluxo conhecido, o LLM do harness procura o cenário e os critérios de
 aceitação no projeto e chama `jev_browser.run_browser_flow` com planos
@@ -101,111 +107,132 @@ 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`;
-- `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
-  texto exato na linha, sem casar com `15287210` ao procurar `1528721`;
-- `within: {"role":"dialog"}` sem `name` para usar o único diálogo visível;
-  o MCP ignora diálogos visualmente ocultos, inclusive os que ficaram no DOM
-  com `opacity: 0`;
-- `name: ""` com `index` não negativo para controles sem nome. O resultado
-  inclui um aviso porque a posição pode mudar entre execuções. O índice é
-  zero-based para o mesmo papel e inclui nomes vazios ou compostos só por
-  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;
-- `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` e `wait_for_condition` (`network_idle`, `hidden` ou
-  `text_hidden`). `wait_for_text` aceita `fail_on: {"role":"alert"}` para
-  interromper a espera assim que um alerta visível aparecer e incluir seu texto
-  no erro. 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;
-- `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;
+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`;
+- `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
+  texto exato na linha, sem casar com `15287210` ao procurar `1528721`;
+- `within: {"role":"dialog"}` sem `name` para usar o único diálogo visível;
+  o MCP ignora diálogos visualmente ocultos, inclusive os que ficaram no DOM
+  com `opacity: 0`;
+- `name: ""` com `index` não negativo para controles sem nome. O resultado
+  inclui um aviso porque a posição pode mudar entre execuções. O índice é
+  zero-based para o mesmo papel e inclui nomes vazios ou compostos só por
+  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;
+- `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
+  `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;
+- `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;
 - `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
-  `Descurtir`.
-
-As proteções e evidências por etapa usam estes campos:
-
-- `confirm_dialog` recebe `expected_text` e `button`. O MCP exige um diálogo
-  visível único e confere se ele contém o texto esperado antes de clicar; se o
-  alerta mudou, a etapa falha sem clicar no botão. Reserve `click` comum para
-  ações que não dependem do conteúdo de uma confirmação;
-- `mutating: true` marca etapas que gravam dados ou disparam efeitos externos.
-  Com `options.dry_run: true`, o fluxo para imediatamente antes da primeira
-  etapa marcada e retorna `dry_run_stopped_before_step` e `mutating_steps`.
-  Marque toda ação que grava ou envia algo, mesmo quando não for um botão
-  chamado Salvar;
-- `duration_ms` aparece em cada etapa concluída ou falha. `mutating_steps`
-  lista as etapas marcadas e informa quais foram executadas;
-- `screenshot: true` salva uma captura depois da etapa e inclui seu caminho na
-  evidência da etapa;
-- `options.report_path` grava um resumo `.md` ou JUnit `.xml`. O caminho deve
-  ser absoluto e estar dentro de `JEV_BROWSER_ARTIFACT_DIR` (ou do diretório de
-  artefatos configurado). O relatório resume versão/status, duração, alvo e
-  `resolved_target`, asserções de rede, falhas de rede e caminhos das capturas.
-
-`run_browser_flow` também aceita `params` como mapa de texto, números e
-booleanos. Use `{pedido}` em `flow`, `expected_outcome` e nos campos textuais do
-plano para reutilizar um valor sem editar o roteiro em vários lugares. A ação
-`extract` lê `text` (padrão), `value` ou `attribute` de um elemento e salva o
-resultado na variável indicada por `as`; etapas seguintes podem usar
-`{documento}`. O valor extraído é tratado como sensível e fica oculto no
-resultado por padrão; use `sensitive: false` só quando for apropriado exibi-lo.
-`resolved_target.match_strategy` informa quando um rótulo foi
-associado por proximidade (`label-proximity`) em vez de um `label[for]` direto.
-
-A ação `assert_network` verifica respostas observadas depois da etapa anterior,
-incluindo respostas 2xx ou erros esperados como 404. Exemplo:
-
-```json
-{
-  "action": "assert_network",
-  "url_contains": "/documentoFinanceiro/atualizar",
-  "method": "PUT",
-  "status": 404,
-  "message_contains": "Boleto não encontrado"
-}
-```
-
-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.
-
-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.
-
-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
-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.
+- `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
+  `Descurtir`.
+
+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.
+  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`,
+  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;
+- `duration_ms` aparece em cada etapa concluída ou falha. `mutating_steps`
+  lista etapas mutáveis que foram executadas ou falharam;
+- `screenshot: true` salva uma captura depois da etapa e inclui seu caminho na
+  evidência da etapa;
+- `options.report_path` grava um resumo `.md` ou JUnit `.xml`. O caminho deve
+  ser absoluto e estar dentro de `JEV_BROWSER_ARTIFACT_DIR` (ou do diretório de
+  artefatos configurado). O relatório resume versão/status, duração, alvo e
+  `resolved_target`, asserções de rede, falhas de rede e caminhos das capturas.
+
+`run_browser_flow` também aceita `params` como mapa de texto, números e
+booleanos. Use `{pedido}` em `flow`, `expected_outcome` e nos campos textuais do
+plano para reutilizar um valor sem editar o roteiro em vários lugares. A ação
+`extract` lê `text` (padrão), `value` ou `attribute` de um elemento e salva o
+resultado na variável indicada por `as`; etapas seguintes podem usar
+`{documento}`. O valor extraído é tratado como sensível e fica oculto no
+resultado por padrão; use `sensitive: false` só quando for apropriado exibi-lo.
+`resolved_target.match_strategy` informa quando um rótulo foi
+associado por proximidade (`label-proximity`) em vez de um `label[for]` direto.
+
+A ação `assert_network` verifica respostas observadas depois da etapa anterior,
+incluindo respostas 2xx ou erros esperados como 404. Exemplo:
+
+```json
+{
+  "action": "assert_network",
+  "url_contains": "/documentoFinanceiro/atualizar",
+  "method": "PUT",
+  "status": 404,
+  "message_contains": "Boleto não encontrado"
+}
+```
+
+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.
+
+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.
+
+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
+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,
+`{"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
+exato. `check` e `uncheck` alteram checkboxes, e `select_option` aceita rótulo
+exato (`option`), valor (`value`) ou rótulo parcial único (`label_contains`).
+`navigate_menu` percorre uma lista de rótulos exatos e abre `#open_btn` quando o
+primeiro item ainda está oculto. Se vários itens visíveis tiverem o mesmo
+rótulo, seleciona a última ocorrência, útil quando o submenu recém-aberto
+repete o nome da categoria pai.
 
 ```json
 {
@@ -217,51 +244,52 @@ controle próximo ao texto visível do rótulo.
 ```
 
 ```json
-{"action":"click","role":"button","name":"Add to cart","index":0}
-```
-
-Exemplos para controles legados sem nome acessível:
-
-```json
-{"action":"type","role":"textbox","label":"Vencimento","text":"05/10/2026"}
-{"action":"type","role":"textbox","target_text":"Vencimento","text":"05/10/2026"}
-{"action":"click","role":"link","title":"Editar documento","within":{"row_containing":"1528721"}}
-{"action":"press","key":"Enter","role":"textbox","placeholder":"Busca rápida"}
-{"action":"click","role":"button","name":"","index":0}
-{"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.
-O snapshot também resume campos de formulário com `id`, `name`, valor, estado
-desabilitado, rótulo e índice zero-based entre campos de mesmo nome. Valores
-sensíveis, como senha, token e cartão, são ocultados. `snapshot_include_hidden`
-é `false` por padrão; defina `true` somente quando precisar inspecionar campos
-ocultos também.
-
-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.
-
-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
-e erro.
+{"action":"click","role":"button","name":"Add to cart","index":0}
+```
+
+Exemplos para controles legados sem nome acessível:
+
+```json
+{"action":"type","role":"textbox","label":"Vencimento","text":"05/10/2026"}
+{"action":"type","role":"textbox","target_text":"Vencimento","text":"05/10/2026"}
+{"action":"click","role":"link","title":"Editar documento","within":{"row_containing":"1528721"}}
+{"action":"press","key":"Enter","role":"textbox","placeholder":"Busca rápida"}
+{"action":"click","role":"button","name":"","index":0}
+{"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.
+O snapshot também resume campos de formulário com `id`, `name`, valor, estado
+desabilitado, rótulo e índice zero-based entre campos de mesmo nome. Valores
+sensíveis, como senha, token e cartão, são ocultados. `snapshot_include_hidden`
+é `false` por padrão; defina `true` somente quando precisar inspecionar campos
+ocultos também.
+
+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.
+
+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
+e erro.
 
 ### Captura de downloads
 
 Marque o clique que deve iniciar um download com `expect_download: true`. O
-Playwright começa a aguardar o evento antes do clique; após a transferência
-terminar, o MCP verifica o tamanho, sanitiza o nome sugerido e copia o arquivo
+Playwright começa a aguardar o evento antes do clique; isso também captura
+downloads gerados por `URL.createObjectURL` (por exemplo, PDFs Blob). Após a
+transferência terminar, o MCP verifica o tamanho, sanitiza o nome sugerido e copia o arquivo
 para `JEV_BROWSER_ARTIFACT_DIR` (ou para o diretório de artefatos configurado).
 O resultado inclui a lista `downloaded_files`, com nome, caminho local e bytes;
 cada passo também contém o arquivo capturado. Os limites contam arquivos e bytes
@@ -292,13 +320,13 @@ trechos da página. Qualquer violação reprova esse fluxo. A auditoria automát
 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
-conteúdo acessível dos iframes nomeados dentro do escopo, limitado pela
-configuração. Se um alvo estiver ausente, o erro inclui até três nomes acessíveis
-próximos quando o snapshot os encontrar. CSS/XPath são permitidos somente como
-localizadores explícitos de último recurso e geram aviso. O plano não aceita
-JavaScript enviado pelo harness nem coordenadas.
+Para ações em iframe, acrescente `"frame": "payment-iframe"`; o valor precisa
+corresponder ao atributo `name` ou `title` do iframe. O snapshot inclui o
+conteúdo acessível dos iframes nomeados dentro do escopo, limitado pela
+configuração. Se um alvo estiver ausente, o erro inclui até três nomes acessíveis
+próximos quando o snapshot os encontrar. CSS/XPath são permitidos somente como
+localizadores explícitos de último recurso e geram aviso. O plano não aceita
+JavaScript enviado pelo harness nem coordenadas.
 
 Os aliases `value` → `text` em `type`/`wait_for_text` e `value` → `expected` em
 asserções são aceitos. `comment` também é aceito em planos e passos, mas é
@@ -381,9 +409,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`; o padrão é `computer`:
+`browser.mode` aceita `harness` ou `computer`; o padrão é `computer`:
 
-- `harness` usa Chrome headless e contexto 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
@@ -392,23 +420,23 @@ 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. `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
-`Content-Length`. Corpos acima do limite, com formato inválido ou que não
-podem ser lidos com segurança são omitidos e explicados em `warnings`.
+`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`.
+
+Com `capture_network_error_bodies: true`, respostas JSON de erro da mesma
+origem são capturadas mesmo quando usam transferência chunked e não enviam
+`Content-Length`. Corpos acima do limite, com formato inválido ou que não
+podem ser lidos com segurança são omitidos e explicados em `warnings`.
 
 `jev_browser_mcp.browser.max_action_timeout_seconds` limita esperas por ações,
 seletores e condições. `JEV_BROWSER_UPLOAD_ROOT` libera uploads somente dentro
@@ -424,54 +452,76 @@ 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`,
-`capture_network_error_bodies`, `ready_timeout_seconds`, `ready_network_idle`,
-`ready_stable_ms`, `ready_text`, `reuse_page`, `screenshot_on_failure`,
-`trace_on_failure`, `snapshot_include_hidden`, `stop_on_expected`, `dry_run` 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. `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
-layout ou o comportamento do site, então a opção é desligada por padrão.
+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
+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.
+`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.
-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
+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
 substituí-lo por uma pasta absoluta fora do pacote. Screenshots e traces podem
 conter dados visíveis da aplicação: mantenha o diretório local protegido e
-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.
-
-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.
-Resultados MCP incluem `server_version`; erros também começam com a versão do
-servidor para facilitar a comparação entre instalações.
+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.
+
+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.
+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
+que encerrou desde a chamada anterior. Passe `{"restart":true}` para fechar e
+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}`;