@diegosouzacdv/jev-browser-mcp 0.2.0 → 0.3.1

package/docs/jev-browser-mcp.md

@@ -1,291 +1,354 @@
-# Automação de tela com Jev e Playwright
-
-## Instalar em outros harnesses com npm/npx
-
-O repositório também contém um pacote Node independente do harness. Ele fala
-MCP por `stdio`, executa o Playwright no mesmo processo e pode ser iniciado por
-qualquer harness que aceite `command` e `args` para um servidor MCP. O pacote
-usa o mesmo `config/ui-testing.json` deste repositório; não precisa instalar o
-Python do orquestrador. As opções específicas do pacote ficam isoladas no
-bloco `jev_browser_mcp` para preservar o contrato do servidor Python.
-
-Instale a versão publicada do npm diretamente no harness. Para fixar uma
-versão em produção, use o número explícito no argumento do pacote:
-
-```json
-{
-  "mcpServers": {
-    "jev-browser": {
-      "command": "npx",
-      "args": ["--yes", "@diegosouzacdv/jev-browser-mcp@0.2.0"],
-      "env": {
-        "OPENROUTER_API_KEY": "${OPENROUTER_API_KEY}",
-        "JEV_BROWSER_MODE": "harness"
-      }
-    }
-  }
-}
-```
-
-O formato de interpolação de variáveis varia por harness. Injete a chave por
-um secret manager ou pelo ambiente do processo; não grave a chave no arquivo
-de configuração. Para instalar no projeto Node do próprio harness:
-
-```sh
-npm install @diegosouzacdv/jev-browser-mcp
-npx --yes @diegosouzacdv/jev-browser-mcp --install-browser
-```
-
-No modo `harness`, a instalação baixa uma vez o Chrome/Edge que o Playwright
-controlará. No modo `computer`, o pacote abre o Chrome/Edge instalado e usa um
-perfil persistente exclusivo em `browser.computer_user_data_dir`; personalize
-as escolhas com `JEV_BROWSER_MODE`, `JEV_BROWSER_CHANNEL` e
-`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
-nome de variável declarado em `jev.credential_env`.
-
-Uma aplicação Node também pode importar `createJevBrowserServer` por
-`@diegosouzacdv/jev-browser-mcp/server` e conectar o servidor ao transporte MCP
-que ela já utiliza.
-
-O pacote é montado pela raiz do repositório, mas o campo `files` do `package.json`
-inclui somente o código Node, a configuração compartilhada e esta documentação
-(além do README que o npm inclui automaticamente). Ele não publica o restante
-do orquestrador. A instalação por npm é a recomendada; use a referência GitHub
-somente quando precisar experimentar uma revisão ainda não publicada.
-
-### Contrato do pacote
-
-O executável oferece `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, seletores livres nem coordenadas. 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.
-
-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
-candidatos declarativos. O MCP abre uma única sessão do Playwright, navega para
-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` e `select_option` com papel/nome acessível exatos;
-- `wait_for_text` e `wait_for_condition` (`network_idle`, limitado pelo timeout
-  de ação configurado);
-- `press_key` com `PageDown`, `PageUp`, `Home`, `End`, `ArrowDown`, `ArrowUp`,
-  `Enter`, `Escape` ou `Tab`;
-- `assert_text`, `assert_value`, `assert_visible` e `assert_hidden`;
-- `upload_file` para input rotulado, botão que abre o seletor de arquivo ou
-  dropzone;
-- `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`.
-
-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. O plano não aceita JavaScript enviado
-pelo harness, coordenadas ou seletores livres.
-
-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 é
-ignorado e não é enviado ao Jev. Campos fora do contrato continuam sendo
-recusados.
-
-### Upload de arquivos
-
-Defina `JEV_BROWSER_UPLOAD_ROOT` como uma pasta absoluta que contenha os arquivos
-de fixture. Cada caminho passado ao fluxo também precisa ser absoluto; o MCP
-resolve links simbólicos e recusa qualquer arquivo fora dessa raiz. Só aceita
-arquivos regulares, até 5 arquivos por passo, 10 MiB por arquivo e 25 MiB no
-total do passo, conforme `jev_browser_mcp.browser` em `config/ui-testing.json`.
-Os bytes são lidos e validados no processo local antes de serem entregues ao
-Playwright. O MCP não envia esses bytes ao Jev nem os inclui diretamente na
-resposta; texto que o próprio site exibir na interface ainda pode aparecer no
-snapshot devolvido ao harness.
-
-```json
-{"action":"upload_file","target":"input","label":"Nota fiscal","file_path":"/fixtures/nota.pdf"}
-```
-
-Para uma área de arrastar, use o papel e o nome acessível da dropzone. Para um
-botão que abre a janela nativa, use `target: "button"`; sem `target`, a presença
-de `label` seleciona o input e `role`/`name` seleciona esse botão.
-
-```json
-{"action":"upload_file","target":"dropzone","role":"region","name":"Anexos","file_paths":["/fixtures/a.pdf","/fixtures/b.png"]}
-```
-
-Se `JEV_BROWSER_UPLOAD_ROOT` não estiver definido, a ação recusa a execução. O
-limite evita que um plano transforme o MCP em leitor arbitrário de arquivos do
-computador.
-
-Exemplo de chamada:
-
-```json
-{
-  "flow": "Adicionar o produto ao carrinho e confirmar o resumo",
-  "initial_url": "http://127.0.0.1:4173/products/coffee",
-  "expected_outcome": "Coffee added to cart",
-  "options": {
-    "fast_path": true,
-    "snapshot_scope": "main",
-    "capture_network_errors": true,
-    "screenshot_on_failure": true
-  },
-  "candidate_plans": {
-    "add_and_confirm": {
-      "description": "Adicionar o produto visível ao carrinho e abrir o resumo",
-      "steps": [
-        {"action": "click", "role": "button", "name": "Add to cart"},
-        {"action": "wait_for_text", "text": "Coffee added to cart"},
-        {"action": "click", "role": "link", "name": "View cart"},
-        {"action": "assert_text", "role": "heading", "name": "Order summary", "expected": "Coffee"}
-      ]
-    }
-  }
-}
-```
-
-O plano é montado pelo LLM do harness, mas o Jev escolhe qual plano fornecido
-deve executar usando o fluxo e o snapshot inicial. O Jev não cria ações, nomes
-de controles ou valores de formulário. Valores de `type` são usados localmente
-pelo Playwright e são removidos do texto enviado ao provedor e da evidência de
-retorno. Use valores de teste; autenticação deve ficar no perfil de navegador
-configurado.
-
-O MCP também mantém `choose_next_action` para fluxos exploratórios em que o
-harness precisa inspecionar e decidir entre ações uma por vez. Esse caminho é
-mais lento porque exige uma nova decisão e uma nova chamada de ferramenta por
-ação; prefira `run_browser_flow` quando os passos esperados puderem ser
-descritos antes da execução.
-
-## Configuração
-
-Edite `config/ui-testing.json`. URL, modelo do provedor, variável de credencial
-e limites compartilhados ficam nos blocos `browser` e `jev`. As opções próprias
-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`:
-
-- `harness` usa Chrome headless e perfil 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.
-
-`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
-de uma pasta absoluta escolhida pelo operador.
-`jev_browser_mcp.browser.max_upload_files`, `max_upload_path_chars`,
-`max_upload_file_bytes` e `max_upload_total_bytes` limitam quantidade e tamanho.
-Não configure a raiz como o disco inteiro ou a pasta home: use uma pasta de
-fixtures dedicada.
-
-O `run_browser_flow` aceita `options` com `fast_path`, `snapshot_scope`,
-`block_trackers`, `capture_console_errors`, `capture_network_errors`,
-`screenshot_on_failure` e `trace_on_failure`. Sem override, os padrões são lidos
-de `jev_browser_mcp` em `config/ui-testing.json`: um plano candidato pula a chamada Decisions;
-captura de console e screenshot de falha ficam ligadas; trace, rede e bloqueio
-de recursos ficam desligados. `snapshot_scope` aceita `body`, `main` ou `dialog`.
-
-`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.
-
-Com `capture_console_errors` e `capture_network_errors`, o retorno traz
-`console_errors` e `network_failures`, limitados em quantidade e tamanho.
-Respostas HTTP 4xx/5xx e requisições que falham são listadas; query strings,
-fragmentos, valores de formulário e nomes de arquivo são removidos ou
-sanitizados. Em falhas, `screenshot_on_failure` salva screenshot local e retorna
-`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.
-
-`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.
-
-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
-em `config/ui-testing.json`. `provider_url` é o endpoint HTTPS completo da API
-Decisions. O cliente não
-segue redirects e recusa URL com credencial, query string ou fragmento. O Jev
-fica indisponível quando a política de MCP está em modo offline.
-
-Na primeira execução, aqueça uma vez o cache local do pacote declarado em
-`browser.playwright_mcp_package` com `npx --yes <pacote> --help`. O MCP inicia
-depois com `--offline`, evitando uma consulta ao registry npm em cada fluxo.
-Quando a versão configurada mudar, aqueça o novo pacote uma vez.
-
-## Desempenho e evidência
-
-O pacote Node usa a decisão remota do Jev para escolher entre múltiplos planos.
-Com exatamente um plano e `fast_path` ligado (padrão), executa esse plano sem
-chamar a API Decisions; `jev_decisions` fica em zero. Inclua o fluxo completo em
-um plano candidato para evitar chamadas separadas ao harness; seleção,
-navegação, ações e asserções ficam em uma chamada MCP. O servidor Python
-`mcp_servers/jev_browser_server.py` mantém seu fluxo próprio e usa uma decisão
-remota do Jev por chamada. A sessão Playwright fecha antes de o MCP Python
-retornar. O perfil do modo `computer` preserva o login para chamadas seguintes;
-nesse servidor o processo e a janela não são reutilizados. O pacote Node mantém
-o browser aquecido até o harness encerrar o processo. O snapshot enviado ao Jev
-e devolvido ao harness remove o rodapé e, se ainda exceder o limite, mantém o
-início e o fim da captura com um marcador de truncamento. `snapshot_scope` pode
-limitar a captura a `main` ou `dialog`; iframes nomeados contidos nesse escopo
-também podem ser incluídos.
-
-A chamada composta aquecida deve ficar dentro da meta de 20 segundos em páginas
-que respondem normalmente; a inicialização fria, páginas lentas, MFA e conteúdo
-sob demanda podem excedê-la. O MCP devolve `total_ms`, `browser_session_ms`,
-`navigation_ms`, `initial_snapshot_ms`, `jev_decision_ms` e `browser_plan_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.
-
-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)
-para os tipos de resposta e autenticação.
+# Automação de tela com Jev e Playwright
+
+## Instalar em outros harnesses com npm/npx
+
+O repositório também contém um pacote Node independente do harness. Ele fala
+MCP por `stdio`, executa o Playwright no mesmo processo e pode ser iniciado por
+qualquer harness que aceite `command` e `args` para um servidor MCP. O pacote
+usa o mesmo `config/ui-testing.json` deste repositório; não precisa instalar o
+Python do orquestrador. As opções específicas do pacote ficam isoladas no
+bloco `jev_browser_mcp` para preservar o contrato do servidor Python.
+
+Instale a versão publicada do npm diretamente no harness. Para fixar uma
+versão em produção, use o número explícito no argumento do pacote:
+
+```json
+{
+  "mcpServers": {
+    "jev-browser": {
+      "command": "npx",
+      "args": ["--yes", "@diegosouzacdv/jev-browser-mcp@0.3.1"],
+      "env": {
+        "OPENROUTER_API_KEY": "${OPENROUTER_API_KEY}",
+        "JEV_BROWSER_MODE": "harness"
+      }
+    }
+  }
+}
+```
+
+O formato de interpolação de variáveis varia por harness. Injete a chave por
+um secret manager ou pelo ambiente do processo; não grave a chave no arquivo
+de configuração. Para instalar no projeto Node do próprio harness:
+
+```sh
+npm install @diegosouzacdv/jev-browser-mcp
+npx --yes @diegosouzacdv/jev-browser-mcp --install-browser
+```
+
+No modo `harness`, a instalação baixa uma vez o Chrome/Edge que o Playwright
+controlará. No modo `computer`, o pacote abre o Chrome/Edge instalado e usa um
+perfil persistente exclusivo em `browser.computer_user_data_dir`; personalize
+as escolhas com `JEV_BROWSER_MODE`, `JEV_BROWSER_CHANNEL` e
+`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
+nome de variável declarado em `jev.credential_env`.
+
+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.
+
+### Contrato do pacote
+
+O executável oferece `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, seletores livres nem coordenadas. 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.
+
+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
+candidatos declarativos. O MCP abre uma única sessão do Playwright, navega para
+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` e `select_option` com papel/nome acessível exatos;
+- `wait_for_text` e `wait_for_condition` (`network_idle`, limitado pelo timeout
+  de ação configurado);
+- `press_key` com `PageDown`, `PageUp`, `Home`, `End`, `ArrowDown`, `ArrowUp`,
+  `Enter`, `Escape` ou `Tab`;
+- `assert_text`, `assert_value`, `assert_visible` e `assert_hidden`;
+- `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`.
+
+Quando vários controles têm o mesmo papel e nome, `within` limita a busca a um
+container acessível único, como uma linha ou card. `index` escolhe uma ocorrência
+zero-based dentro desse escopo; sem `index`, o MCP exige exatamente um alvo.
+
+```json
+{
+  "action": "click",
+  "role": "button",
+  "name": "Add to cart",
+  "within": {"role": "group", "name": "Sauce Labs Backpack"}
+}
+```
+
+```json
+{"action":"click","role":"button","name":"Add to cart","index":0}
+```
+
+### 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
+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
+por fluxo. A checagem de tamanho acontece depois da transferência do navegador,
+antes de copiar para a pasta de artefatos.
+
+```json
+{"action":"click","role":"button","name":"Export report","expect_download":true}
+```
+
+`jev_browser_mcp.browser.max_download_files`, `max_download_file_bytes`,
+`max_download_total_bytes` e `max_download_timeout_seconds` definem os limites.
+O diretório de artefatos deve ser local e protegido: arquivos baixados podem
+conter dados da aplicação.
+
+### Auditoria automatizada de acessibilidade
+
+Use `audit_accessibility` depois de colocar a página no estado que deseja
+verificar:
+
+```json
+{"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.
+
+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. O plano não aceita JavaScript enviado
+pelo harness, coordenadas ou seletores livres.
+
+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 é
+ignorado e não é enviado ao Jev. Campos fora do contrato continuam sendo
+recusados.
+
+### Upload de arquivos
+
+Defina `JEV_BROWSER_UPLOAD_ROOT` como uma pasta absoluta que contenha os arquivos
+de fixture. Cada caminho passado ao fluxo também precisa ser absoluto; o MCP
+resolve links simbólicos e recusa qualquer arquivo fora dessa raiz. Só aceita
+arquivos regulares, até 5 arquivos por passo, 10 MiB por arquivo e 25 MiB no
+total do passo, conforme `jev_browser_mcp.browser` em `config/ui-testing.json`.
+Os bytes são lidos e validados no processo local antes de serem entregues ao
+Playwright. O MCP não envia esses bytes ao Jev nem os inclui diretamente na
+resposta; texto que o próprio site exibir na interface ainda pode aparecer no
+snapshot devolvido ao harness.
+
+```json
+{"action":"upload_file","target":"input","label":"Nota fiscal","file_path":"/fixtures/nota.pdf"}
+```
+
+Para uma área de arrastar, use o papel e o nome acessível da dropzone. Para um
+botão que abre a janela nativa, use `target: "button"`; sem `target`, a presença
+de `label` seleciona o input e `role`/`name` seleciona esse botão.
+
+```json
+{"action":"upload_file","target":"dropzone","role":"region","name":"Anexos","file_paths":["/fixtures/a.pdf","/fixtures/b.png"]}
+```
+
+Se `JEV_BROWSER_UPLOAD_ROOT` não estiver definido, a ação recusa a execução. O
+limite evita que um plano transforme o MCP em leitor arbitrário de arquivos do
+computador.
+
+Exemplo de chamada:
+
+```json
+{
+  "flow": "Adicionar o produto ao carrinho e confirmar o resumo",
+  "initial_url": "http://127.0.0.1:4173/products/coffee",
+  "expected_outcome": "Coffee added to cart",
+  "options": {
+    "fast_path": true,
+    "snapshot_scope": "main",
+    "capture_network_errors": true,
+    "screenshot_on_failure": true
+  },
+  "candidate_plans": {
+    "add_and_confirm": {
+      "description": "Adicionar o produto visível ao carrinho e abrir o resumo",
+      "steps": [
+        {"action": "click", "role": "button", "name": "Add to cart"},
+        {"action": "wait_for_text", "text": "Coffee added to cart"},
+        {"action": "click", "role": "link", "name": "View cart"},
+        {"action": "assert_text", "role": "heading", "name": "Order summary", "expected": "Coffee"}
+      ]
+    }
+  }
+}
+```
+
+O plano é montado pelo LLM do harness, mas o Jev escolhe qual plano fornecido
+deve executar usando o fluxo e o snapshot inicial. O Jev não cria ações, nomes
+de controles ou valores de formulário. Valores de `type` são usados localmente
+pelo Playwright e são removidos do texto enviado ao provedor e da evidência de
+retorno. Use valores de teste; autenticação deve ficar no perfil de navegador
+configurado.
+
+O MCP também mantém `choose_next_action` para fluxos exploratórios em que o
+harness precisa inspecionar e decidir entre ações uma por vez. Esse caminho é
+mais lento porque exige uma nova decisão e uma nova chamada de ferramenta por
+ação; prefira `run_browser_flow` quando os passos esperados puderem ser
+descritos antes da execução.
+
+## Configuração
+
+Edite `config/ui-testing.json`. URL, modelo do provedor, variável de credencial
+e limites compartilhados ficam nos blocos `browser` e `jev`. As opções próprias
+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`:
+
+- `harness` usa Chrome headless e perfil 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.
+
+`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
+de uma pasta absoluta escolhida pelo operador.
+`jev_browser_mcp.browser.max_upload_files`, `max_upload_path_chars`,
+`max_upload_file_bytes` e `max_upload_total_bytes` limitam quantidade e tamanho.
+Não configure a raiz como o disco inteiro ou a pasta home: use uma pasta de
+fixtures dedicada.
+
+Os limites de download ficam no mesmo bloco: `max_download_files`,
+`max_download_file_bytes`, `max_download_total_bytes` e
+`max_download_timeout_seconds`. `jev_browser_mcp.jev.max_accessibility_violations`
+limita quantas descrições de violações axe entram no resultado; a contagem total
+continua informada mesmo quando a lista é truncada.
+
+O `run_browser_flow` aceita `options` com `fast_path`, `snapshot_scope`,
+`block_trackers`, `capture_console_errors`, `capture_network_errors`,
+`screenshot_on_failure` e `trace_on_failure`. Sem override, os padrões são lidos
+de `jev_browser_mcp` em `config/ui-testing.json`: um plano candidato pula a chamada Decisions;
+captura de console e screenshot de falha ficam ligadas; trace, rede e bloqueio
+de recursos ficam desligados. `snapshot_scope` aceita `body`, `main` ou `dialog`.
+
+`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.
+
+Com `capture_console_errors` e `capture_network_errors`, o retorno traz
+`console_errors` e `network_failures`, limitados em quantidade e tamanho.
+Respostas HTTP 4xx/5xx e requisições que falham são listadas; query strings,
+fragmentos, valores de formulário e nomes de arquivo são removidos ou
+sanitizados. Em falhas, `screenshot_on_failure` salva screenshot local e retorna
+`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.
+
+`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.
+
+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
+em `config/ui-testing.json`. `provider_url` é o endpoint HTTPS completo da API
+Decisions. O cliente não
+segue redirects e recusa URL com credencial, query string ou fragmento. O Jev
+fica indisponível quando a política de MCP está em modo offline.
+
+Na primeira execução, aqueça uma vez o cache local do pacote declarado em
+`browser.playwright_mcp_package` com `npx --yes <pacote> --help`. O MCP inicia
+depois com `--offline`, evitando uma consulta ao registry npm em cada fluxo.
+Quando a versão configurada mudar, aqueça o novo pacote uma vez.
+
+## Desempenho e evidência
+
+O pacote Node usa a decisão remota do Jev para escolher entre múltiplos planos.
+Com exatamente um plano e `fast_path` ligado (padrão), executa esse plano sem
+chamar a API Decisions; `jev_decisions` fica em zero. Inclua o fluxo completo em
+um plano candidato para evitar chamadas separadas ao harness; seleção,
+navegação, ações e asserções ficam em uma chamada MCP. O servidor Python
+`mcp_servers/jev_browser_server.py` mantém seu fluxo próprio e usa uma decisão
+remota do Jev por chamada. A sessão Playwright fecha antes de o MCP Python
+retornar. O perfil do modo `computer` preserva o login para chamadas seguintes;
+nesse servidor o processo e a janela não são reutilizados. O pacote Node mantém
+o browser aquecido até o harness encerrar o processo. O snapshot enviado ao Jev
+e devolvido ao harness remove o rodapé e, se ainda exceder o limite, mantém o
+início e o fim da captura com um marcador de truncamento. `snapshot_scope` pode
+limitar a captura a `main` ou `dialog`; iframes nomeados contidos nesse escopo
+também podem ser incluídos.
+
+A chamada composta aquecida deve ficar dentro da meta de 20 segundos em páginas
+que respondem normalmente; a inicialização fria, páginas lentas, MFA e conteúdo
+sob demanda podem excedê-la. O MCP devolve `total_ms`, `browser_session_ms`,
+`navigation_ms`, `initial_snapshot_ms`, `jev_decision_ms` e `browser_plan_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.
+
+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)
+para os tipos de resposta e autenticação.