Habilidade do Navegador Dev

Automação de navegador que mantém o estado da página entre as execuções de scripts. Escreva scripts pequenos e focados para realizar tarefas incrementalmente. Assim que você tiver validado parte de um fluxo de trabalho e houver trabalho repetido a ser feito, você pode escrever um script para realizar o trabalho repetido em uma única execução.

Escolhendo sua Abordagem

• Sites locais/com código-fonte disponível: Leia o código-fonte primeiro para escrever seletores diretamente
• Layouts de página desconhecidos: Use getAISnapshot() para descobrir elementos e selectSnapshotRef() para interagir com eles
• Feedback visual: Tire capturas de tela para ver o que o usuário vê

Configuração

Instalação: Veja references/installation.md para instruções detalhadas de configuração, incluindo suporte ao Windows.

Dois modos disponíveis. Pergunte ao usuário se não estiver claro qual usar.

Modo Standalone (Padrão)

Inicia um novo navegador Chromium para sessões de automação novas.

./skills/dev-browser/server.sh &

Adicione o flag --headless se o usuário solicitar. Espere pela mensagem Ready antes de executar scripts.

Modo Extensão

Conecta-se ao navegador Chrome existente do usuário. Use este modo quando:

• O usuário já estiver logado em sites e quiser que você faça coisas em uma experiência autenticada que não seja de desenvolvimento local.
• O usuário pedir para você usar a extensão

Importante: O fluxo principal ainda é o mesmo. Você cria páginas nomeadas dentro do navegador dele.

Inicie o servidor de retransmissão:

cd skills/dev-browser && npm i && npm run start-extension &

Espere por Waiting for extension to connect... seguido por Extension connected no console. Para saber que um cliente se conectou e o navegador está pronto para ser controlado. Fluxo de Trabalho:

1. Scripts chamam client.page("name") assim como no modo normal para criar novas páginas / conectar-se às existentes.
2. A automação é executada na sessão real do navegador do usuário.

Se a extensão ainda não se conectou, diga ao usuário para iniciá-la e ativá-la. Link para download: https://github.com/SawyerHood/dev-browser/releases

Escrevendo Scripts

Execute todos os scripts do diretório skills/dev-browser/. O alias de importação @/ requer a configuração deste diretório.

Execute scripts inline usando heredocs:

cd skills/dev-browser && npx tsx <<'EOF'
import { connect, waitForPageLoad } from "@/client.js";

const client = await connect();
// Create page with custom viewport size (optional)
const page = await client.page("example", { viewport: { width: 1920, height: 1080 } });

await page.goto("https://example.com");
await waitForPageLoad(page);

console.log({ title: await page.title(), url: page.url() });
await client.disconnect();
EOF

Escreva em arquivos tmp/ apenas quando o script precisar de reutilização, for complexo ou o usuário solicitar explicitamente.

Princípios Chave

1. Scripts pequenos: Cada script faz UMA coisa (navegar, clicar, preencher, verificar)
2. Avaliar estado: Registrar/retornar o estado no final para decidir os próximos passos
3. Nomes de página descritivos: Use "checkout", "login", não "main"
4. Desconectar para sair: await client.disconnect() - as páginas persistem no servidor
5. JavaScript puro em evaluate: page.evaluate() é executado no navegador - sem sintaxe TypeScript

Loop de Fluxo de Trabalho

Siga este padrão para tarefas complexas:

1. Escreva um script para realizar uma ação
2. Execute-o e observe a saída
3. Avalie - funcionou? Qual é o estado atual?
4. Decida - a tarefa está completa ou precisamos de outro script?
5. Repita até que a tarefa seja concluída

Sem TypeScript no Contexto do Navegador

O código passado para page.evaluate() é executado no navegador, que não entende TypeScript:

// ✅ Correct: plain JavaScript
const text = await page.evaluate(() => {
  return document.body.innerText;
});

// ❌ Wrong: TypeScript syntax will fail at runtime
const text = await page.evaluate(() => {
  const el: HTMLElement = document.body; // Type annotation breaks in browser!
  return el.innerText;
});

Coleta de Dados

Para coletar grandes conjuntos de dados, intercepte e reproduza requisições de rede em vez de rolar o DOM. Veja references/scraping.md para o guia completo cobrindo captura de requisições, descoberta de esquema e reprodução de API paginada.

API do Cliente

const client = await connect();

// Obter ou criar página nomeada (viewport se aplica apenas a novas páginas)
const page = await client.page("nome");
const pageWithSize = await client.page("nome", { viewport: { width: 1920, height: 1080 } });

const pages = await client.list(); // Listar todos os nomes de página

…