@diegosouzacdv/jev-browser-mcp 0.1.2 → 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

@@ -6,7 +6,8 @@ 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.
+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:
@@ -16,7 +17,7 @@ versão em produção, use o número explícito no argumento do pacote:
   "mcpServers": {
     "jev-browser": {
       "command": "npx",
-      "args": ["--yes", "@diegosouzacdv/jev-browser-mcp@0.1.1"],
+      "args": ["--yes", "@diegosouzacdv/jev-browser-mcp@0.2.0"],
       "env": {
         "OPENROUTER_API_KEY": "${OPENROUTER_API_KEY}",
         "JEV_BROWSER_MODE": "harness"
@@ -58,12 +59,14 @@ somente quando precisar experimentar uma revisão ainda não publicada.
 
 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 e limitado a clique por papel/nome
-acessível, preenchimento de texto, espera por texto, teclas de rolagem e
-reações idempotentes a um comentário único. Não aceita JavaScript, 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.
+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
@@ -77,16 +80,59 @@ 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`, `wait_for_text`, teclas aprovadas de
-navegação/rolagem (`PageDown`, `PageUp`, `Home`, `End`, `ArrowDown`, `ArrowUp`)
-e as ações `like_comment` e `unlike_comment`. Cliques e entrada de texto usam
-papel e nome acessível exatos; as ações de reação localizam uma única linha pelo
-autor e texto, inspecionam os controles dentro dela e não clicam novamente
-quando já estão no estado pedido. O rótulo é comparado como palavra inteira
-para que `Curtir` não seja confundido com `Descurtir`. Não há JavaScript
-arbitrário, coordenadas ou seletores livres. Se um alvo estiver
-ausente ou ambíguo, o MCP interrompe o plano e devolve a última evidência para o
-harness decidir como continuar.
+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:
 
@@ -95,13 +141,20 @@ Exemplo de chamada:
   "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": "click", "role": "link", "name": "View cart"},
+        {"action": "assert_text", "role": "heading", "name": "Order summary", "expected": "Coffee"}
       ]
     }
   }
@@ -123,9 +176,11 @@ descritos antes da execução.
 
 ## Configuração
 
-Edite `config/ui-testing.json`. O próprio arquivo declara URL e modelo do
-provedor, nome da variável de credencial e limites de entrada e resposta;
-preserve a estrutura completa exigida pelo validador.
+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`:
 
@@ -139,8 +194,42 @@ preserve a estrutura completa exigida pelo validador.
 `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. `incomplete` significa que o fluxo não foi
-comprovado; confiança do Jev não substitui essa verificação.
+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}`;
@@ -162,16 +251,20 @@ Quando a versão configurada mudar, aqueça o novo pacote uma vez.
 
 ## Desempenho e evidência
 
-O servidor Python `mcp_servers/jev_browser_server.py` usa uma decisão remota do
-Jev por fluxo. Inclua o fluxo
-completo em um plano candidato para evitar chamadas separadas ao harness; a
-seleção do plano, a navegação e a reação ao comentário ficam em uma chamada MCP.
-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.
+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
@@ -181,11 +274,17 @@ 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. Os passos e valores de texto dos planos
-não são enviados. Não inclua segredos em `flow`, `expected_outcome` ou nas
-descrições. A resposta retorna o plano escolhido, custo/confiança do provedor
-quando disponíveis e o snapshot final sanitizado. O fluxo só passa quando o
-texto esperado aparece nesse snapshot.
+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)

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),
     }),
   });
 }