@diegosouzacdv/jev-browser-mcp 0.1.1 → 0.2.0

package/README.md

@@ -1712,6 +1712,16 @@ Valores digitados ficam no Playwright e são removidos do conteúdo enviado ao
 Jev. Não coloque senhas, tokens ou outros segredos na descrição do fluxo ou
 nos critérios.
 
+O contrato também oferece `select_option`, `hover`, teclas `Enter`/`Escape`/`Tab`,
+asserções por elemento (`assert_text`, `assert_value`, `assert_visible`,
+`assert_hidden`) e alvos nomeados em iframes. `upload_file` aceita inputs,
+botões que abrem o seletor nativo e dropzones; configure `JEV_BROWSER_UPLOAD_ROOT`
+para limitar os arquivos locais que o MCP pode ler. Um único plano usa o
+fast-path por padrão e não chama a API Decisions. `options` pode limitar o
+snapshot a `main` ou `dialog`, bloquear rastreadores, capturar erros de console
+e rede e salvar screenshot/trace local em falhas. Os caminhos e limites estão
+descritos no [guia completo](docs/jev-browser-mcp.md).
+
 A resposta informa o status, o plano escolhido, as ações executadas, a captura
 final e se o resultado esperado foi confirmado. Consulte o [guia completo do
 MCP Jev Browser](docs/jev-browser-mcp.md) para schemas, limites, tempos e

package/config/ui-testing.json

@@ -5,9 +5,9 @@
     "harness_browser": "chrome",
     "playwright_mcp_package": "@playwright/mcp@0.0.79",
     "computer_browser": "chrome",
-    "computer_user_data_dir": "~/.cache/orquestrador/jev-browser-{browser}",
-    "max_flow_steps": 24,
-    "max_text_entry_chars": 2000
+    "computer_user_data_dir": "~/.cache/orquestrador/jev-browser-{browser}",
+    "max_flow_steps": 24,
+    "max_text_entry_chars": 2000
   },
   "jev": {
     "provider_url": "https://openrouter.ai/api/alpha/decisions",
@@ -16,8 +16,40 @@
     "request_timeout_seconds": 30,
     "max_flow_chars": 12000,
     "max_snapshot_chars": 12000,
-    "max_action_count": 32,
-    "max_action_description_chars": 300,
-    "max_response_bytes": 65536
-  }
-}
+    "max_action_count": 32,
+    "max_action_description_chars": 300,
+    "max_response_bytes": 65536
+  },
+  "jev_browser_mcp": {
+    "browser": {
+      "max_action_timeout_seconds": 8,
+      "max_upload_files": 5,
+      "max_upload_path_chars": 4096,
+      "max_upload_file_bytes": 10485760,
+      "max_upload_total_bytes": 26214400,
+      "upload_root_env": "JEV_BROWSER_UPLOAD_ROOT",
+      "artifact_directory": "~/.cache/orquestrador/jev-browser-artifacts",
+      "artifact_directory_env": "JEV_BROWSER_ARTIFACT_DIR",
+      "max_frame_snapshots": 5,
+      "fast_path_single_plan_default": true,
+      "screenshot_on_failure_default": true,
+      "trace_on_failure_default": false,
+      "capture_console_errors_default": true,
+      "capture_network_errors_default": false,
+      "block_trackers_default": false,
+      "snapshot_scope_default": "body",
+      "tracker_host_suffixes": [
+        "google-analytics.com",
+        "googletagmanager.com",
+        "hotjar.com",
+        "fonts.googleapis.com",
+        "fonts.gstatic.com"
+      ],
+      "blocked_resource_types": ["font", "media"]
+    },
+    "jev": {
+      "max_diagnostic_items": 50,
+      "max_diagnostic_chars": 500
+    }
+  }
+}

package/docs/jev-browser-mcp.md

@@ -0,0 +1,291 @@
+# 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.

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

@@ -9,9 +9,10 @@ Usage:
                                   Install the configured browser for harness mode
   jev-browser-mcp --help           Show this help
 
-Configuration is read from config/ui-testing.json. Set OPENROUTER_API_KEY in
-the environment and use JEV_BROWSER_MODE=harness or computer to choose a browser.
-`;
+Configuration is read from config/ui-testing.json. Set OPENROUTER_API_KEY in
+the environment and use JEV_BROWSER_MODE=harness or computer to choose a browser.
+For upload_file, set JEV_BROWSER_UPLOAD_ROOT to a dedicated fixture directory.
+`;
 
 async function main() {
   const args = process.argv.slice(2);

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

@@ -4,19 +4,39 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 
 const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../..");
-const CONFIG_PATH = path.join(PACKAGE_ROOT, "config", "ui-testing.json");
-const CONFIG_KEYS = {
-  root: ["version", "browser", "jev"],
-  browser: [
+const CONFIG_PATH = path.join(PACKAGE_ROOT, "config", "ui-testing.json");
+const CONFIG_KEYS = {
+  root: ["version", "browser", "jev", "jev_browser_mcp"],
+  browser: [
     "mode",
     "harness_browser",
     "computer_browser",
     "playwright_mcp_package",
-    "computer_user_data_dir",
-    "max_flow_steps",
-    "max_text_entry_chars",
+    "computer_user_data_dir",
+    "max_flow_steps",
+    "max_text_entry_chars",
+  ],
+  nodeBrowser: [
+    "max_action_timeout_seconds",
+    "max_upload_files",
+    "max_upload_path_chars",
+    "max_upload_file_bytes",
+    "max_upload_total_bytes",
+    "upload_root_env",
+    "artifact_directory",
+    "artifact_directory_env",
+    "max_frame_snapshots",
+    "fast_path_single_plan_default",
+    "screenshot_on_failure_default",
+    "trace_on_failure_default",
+    "capture_console_errors_default",
+    "capture_network_errors_default",
+    "block_trackers_default",
+    "snapshot_scope_default",
+    "tracker_host_suffixes",
+    "blocked_resource_types",
   ],
-  jev: [
+  jev: [
     "provider_url",
     "credential_env",
     "model",
@@ -24,8 +44,12 @@ const CONFIG_KEYS = {
     "max_flow_chars",
     "max_snapshot_chars",
     "max_action_count",
-    "max_action_description_chars",
-    "max_response_bytes",
+    "max_action_description_chars",
+    "max_response_bytes",
+  ],
+  nodeJev: [
+    "max_diagnostic_items",
+    "max_diagnostic_chars",
   ],
 };
 
@@ -49,13 +73,52 @@ function requireKeys(value, keys, scope) {
   }
 }
 
-function positiveNumber(value, name, integer = false) {
+function positiveNumber(value, name, integer = false) {
   const parsed = Number(value);
   if (!Number.isFinite(parsed) || parsed <= 0 || (integer && !Number.isInteger(parsed))) {
     throw new JevBrowserError(`config/ui-testing.json ${name} must be a positive ${integer ? "integer" : "number"}`);
   }
   return parsed;
-}
+}
+
+function expandHomeDirectory(value) {
+  if (value.startsWith("~/") || value.startsWith("~\\")) return path.join(homedir(), value.slice(2));
+  return value;
+}
+
+function requireOutsidePackage(resolved, name) {
+  const insidePackage = path.relative(PACKAGE_ROOT, resolved);
+  if (insidePackage === "" || (!insidePackage.startsWith(`..${path.sep}`) && insidePackage !== ".." && !path.isAbsolute(insidePackage))) {
+    throw new JevBrowserError(`${name} must be outside the installed package directory`);
+  }
+  return resolved;
+}
+
+function configuredDirectory(value, name) {
+  if (typeof value !== "string" || !value.trim()) throw new JevBrowserError(`config/ui-testing.json ${name} must be a directory path`);
+  const expanded = expandHomeDirectory(value.trim());
+  if (!path.isAbsolute(expanded)) throw new JevBrowserError(`config/ui-testing.json ${name} must be absolute or start with ~`);
+  return path.resolve(expanded);
+}
+
+function environmentName(value, name) {
+  if (typeof value !== "string" || !/^[A-Z][A-Z0-9_]*$/.test(value)) {
+    throw new JevBrowserError(`config/ui-testing.json ${name} must be an environment variable name`);
+  }
+  return value;
+}
+
+function booleanValue(value, name) {
+  if (typeof value !== "boolean") throw new JevBrowserError(`config/ui-testing.json ${name} must be a boolean`);
+  return value;
+}
+
+function stringList(value, name, validator = () => true) {
+  if (!Array.isArray(value) || value.some((item) => typeof item !== "string" || !item.trim() || !validator(item))) {
+    throw new JevBrowserError(`config/ui-testing.json ${name} must be an array of valid strings`);
+  }
+  return value.map((item) => item.trim());
+}
 
 function validProviderUrl(value) {
   let parsed;
@@ -70,18 +133,10 @@ function validProviderUrl(value) {
   return parsed.toString();
 }
 
-function profileDirectory(template, channel, override) {
-  let value = override?.trim() || template.replace("{browser}", channel);
-  if (value.startsWith("~/") || value.startsWith("~\\")) {
-    value = path.join(homedir(), value.slice(2));
-  }
-  if (!path.isAbsolute(value)) throw new JevBrowserError("JEV_BROWSER_PROFILE must be an absolute path");
-  const resolved = path.resolve(value);
-  const insidePackage = path.relative(PACKAGE_ROOT, resolved);
-  if (insidePackage === "" || (!insidePackage.startsWith(`..${path.sep}`) && insidePackage !== ".." && !path.isAbsolute(insidePackage))) {
-    throw new JevBrowserError("browser profile must be outside the installed package directory");
-  }
-  return resolved;
+function profileDirectory(template, channel, override) {
+  const value = expandHomeDirectory(override?.trim() || template.replace("{browser}", channel));
+  if (!path.isAbsolute(value)) throw new JevBrowserError("JEV_BROWSER_PROFILE must be an absolute path");
+  return requireOutsidePackage(path.resolve(value), "browser profile");
 }
 
 export function loadSettings({ env = process.env, configPath = CONFIG_PATH } = {}) {
@@ -91,9 +146,14 @@ export function loadSettings({ env = process.env, configPath = CONFIG_PATH } = {
   } catch {
     throw new JevBrowserError("config/ui-testing.json is unreadable or invalid JSON");
   }
-  requireKeys(document, CONFIG_KEYS.root, "root");
-  requireKeys(document.browser, CONFIG_KEYS.browser, "browser");
-  requireKeys(document.jev, CONFIG_KEYS.jev, "jev");
+  requireKeys(document, CONFIG_KEYS.root, "root");
+  requireKeys(document.browser, CONFIG_KEYS.browser, "browser");
+  requireKeys(document.jev, CONFIG_KEYS.jev, "jev");
+  requireKeys(document.jev_browser_mcp, ["browser", "jev"], "jev_browser_mcp");
+  requireKeys(document.jev_browser_mcp.browser, CONFIG_KEYS.nodeBrowser, "jev_browser_mcp.browser");
+  requireKeys(document.jev_browser_mcp.jev, CONFIG_KEYS.nodeJev, "jev_browser_mcp.jev");
+  const browserOptions = document.jev_browser_mcp.browser;
+  const jevOptions = document.jev_browser_mcp.jev;
   if (document.version !== 1) throw new JevBrowserError("config/ui-testing.json has an unsupported version");
 
   if (!new Set(["harness", "computer"]).has(document.browser.mode)) {
@@ -116,23 +176,45 @@ export function loadSettings({ env = process.env, configPath = CONFIG_PATH } = {
   if (!new Set(["chrome", "msedge"]).has(channel)) {
     throw new JevBrowserError("JEV_BROWSER_CHANNEL must be chrome or msedge");
   }
-  const profileTemplate = document.browser.computer_user_data_dir;
+  const profileTemplate = document.browser.computer_user_data_dir;
   const profileRemainder = typeof profileTemplate === "string" ? profileTemplate.replace("{browser}", "") : "";
   if (typeof profileTemplate !== "string" || profileTemplate.split("{browser}").length !== 2
     || profileRemainder.includes("{") || profileRemainder.includes("}")) {
     throw new JevBrowserError("config/ui-testing.json browser.computer_user_data_dir must contain {browser}");
   }
 
-  const configuredProviderUrl = validProviderUrl(document.jev.provider_url);
+  const configuredProviderUrl = validProviderUrl(document.jev.provider_url);
   const providerUrl = validProviderUrl(env.JEV_PROVIDER_URL?.trim() || configuredProviderUrl);
-  const credentialEnv = String(document.jev.credential_env || "").trim();
-  if (!/^[A-Z][A-Z0-9_]*$/.test(credentialEnv)) {
-    throw new JevBrowserError("config/ui-testing.json jev.credential_env must be an environment variable name");
-  }
+  const credentialEnv = environmentName(document.jev.credential_env, "jev.credential_env");
   const configuredModel = String(document.jev.model || "").trim();
   if (!configuredModel) throw new JevBrowserError("config/ui-testing.json jev.model is required");
-  const model = (env.JEV_MODEL?.trim() || configuredModel).trim();
-  if (!model) throw new JevBrowserError("Jev model must not be empty");
+  const model = (env.JEV_MODEL?.trim() || configuredModel).trim();
+  if (!model) throw new JevBrowserError("Jev model must not be empty");
+
+  const artifactEnv = environmentName(browserOptions.artifact_directory_env, "jev_browser_mcp.browser.artifact_directory_env");
+  const artifactDirectory = requireOutsidePackage(configuredDirectory(
+    env[artifactEnv]?.trim() || browserOptions.artifact_directory,
+    "jev_browser_mcp.browser.artifact_directory",
+  ), "browser artifact directory");
+  const uploadRootEnv = environmentName(browserOptions.upload_root_env, "jev_browser_mcp.browser.upload_root_env");
+  const configuredUploadRoot = env[uploadRootEnv]?.trim();
+  const uploadRoot = configuredUploadRoot
+    ? configuredDirectory(configuredUploadRoot, `environment ${uploadRootEnv}`)
+    : null;
+  const snapshotScope = browserOptions.snapshot_scope_default;
+  if (!new Set(["body", "main", "dialog"]).has(snapshotScope)) {
+    throw new JevBrowserError("config/ui-testing.json jev_browser_mcp.browser.snapshot_scope_default must be body, main, or dialog");
+  }
+  const trackerHostSuffixes = stringList(
+    browserOptions.tracker_host_suffixes,
+    "jev_browser_mcp.browser.tracker_host_suffixes",
+    (host) => /^[a-z0-9.-]+$/i.test(host) && !host.startsWith(".") && !host.endsWith("."),
+  );
+  const blockedResourceTypes = stringList(
+    browserOptions.blocked_resource_types,
+    "jev_browser_mcp.browser.blocked_resource_types",
+    (type) => new Set(["font", "media", "image"]).has(type),
+  );
 
   return Object.freeze({
     env,
@@ -140,8 +222,27 @@ export function loadSettings({ env = process.env, configPath = CONFIG_PATH } = {
       mode,
       channel,
       profileDir: profileDirectory(profileTemplate, channel, env.JEV_BROWSER_PROFILE),
-      maxFlowSteps: positiveNumber(document.browser.max_flow_steps, "browser.max_flow_steps", true),
-      maxTextEntryChars: positiveNumber(document.browser.max_text_entry_chars, "browser.max_text_entry_chars", true),
+      maxFlowSteps: positiveNumber(document.browser.max_flow_steps, "browser.max_flow_steps", true),
+      maxTextEntryChars: positiveNumber(document.browser.max_text_entry_chars, "browser.max_text_entry_chars", true),
+      actionTimeoutMs: positiveNumber(browserOptions.max_action_timeout_seconds, "jev_browser_mcp.browser.max_action_timeout_seconds") * 1000,
+      maxUploadFiles: positiveNumber(browserOptions.max_upload_files, "jev_browser_mcp.browser.max_upload_files", true),
+      maxUploadPathChars: positiveNumber(browserOptions.max_upload_path_chars, "jev_browser_mcp.browser.max_upload_path_chars", true),
+      maxUploadFileBytes: positiveNumber(browserOptions.max_upload_file_bytes, "jev_browser_mcp.browser.max_upload_file_bytes", true),
+      maxUploadTotalBytes: positiveNumber(browserOptions.max_upload_total_bytes, "jev_browser_mcp.browser.max_upload_total_bytes", true),
+      uploadRoot,
+      artifactDirectory,
+      maxFrameSnapshots: positiveNumber(browserOptions.max_frame_snapshots, "jev_browser_mcp.browser.max_frame_snapshots", true),
+      defaults: Object.freeze({
+        fastPath: booleanValue(browserOptions.fast_path_single_plan_default, "jev_browser_mcp.browser.fast_path_single_plan_default"),
+        screenshotOnFailure: booleanValue(browserOptions.screenshot_on_failure_default, "jev_browser_mcp.browser.screenshot_on_failure_default"),
+        traceOnFailure: booleanValue(browserOptions.trace_on_failure_default, "jev_browser_mcp.browser.trace_on_failure_default"),
+        captureConsoleErrors: booleanValue(browserOptions.capture_console_errors_default, "jev_browser_mcp.browser.capture_console_errors_default"),
+        captureNetworkErrors: booleanValue(browserOptions.capture_network_errors_default, "jev_browser_mcp.browser.capture_network_errors_default"),
+        blockTrackers: booleanValue(browserOptions.block_trackers_default, "jev_browser_mcp.browser.block_trackers_default"),
+        snapshotScope,
+      }),
+      trackerHostSuffixes: Object.freeze(trackerHostSuffixes),
+      blockedResourceTypes: Object.freeze(blockedResourceTypes),
     }),
     jev: Object.freeze({
       providerUrl,
@@ -152,7 +253,9 @@ export function loadSettings({ env = process.env, configPath = CONFIG_PATH } = {
       maxSnapshotChars: positiveNumber(document.jev.max_snapshot_chars, "jev.max_snapshot_chars", true),
       maxActionCount: positiveNumber(document.jev.max_action_count, "jev.max_action_count", true),
       maxActionDescriptionChars: positiveNumber(document.jev.max_action_description_chars, "jev.max_action_description_chars", true),
-      maxResponseBytes: positiveNumber(document.jev.max_response_bytes, "jev.max_response_bytes", true),
+      maxResponseBytes: positiveNumber(document.jev.max_response_bytes, "jev.max_response_bytes", true),
+      maxDiagnosticItems: positiveNumber(jevOptions.max_diagnostic_items, "jev_browser_mcp.jev.max_diagnostic_items", true),
+      maxDiagnosticChars: positiveNumber(jevOptions.max_diagnostic_chars, "jev_browser_mcp.jev.max_diagnostic_chars", true),
     }),
   });
 }