Módulo 2.1 — Dirigir o app com agent-browser | Vídeo Demonstrativo

1

🤖 O que é o agent-browser

Uma skill de navegação que controla um navegador real (Playwright por baixo) por comandos de linha — é o que abre o app de verdade e captura as telas que viram o vídeo.

Conceito Principal

O agent-browser não simula a tela — ele usa o app. Cada screenshot é uma captura real do DOM no estado daquele passo, no viewport que você fixou.

É por isso que esta skill mostra um app real, em vez de explicar um conceito com motion graphics.

✓ O que o agent-browser faz

✓ Abre uma URL real num navegador controlado
✓ Lista elementos interativos com snapshot -i
✓ Preenche, clica e tira screenshots de cada estado
✓ Roda JS via eval (ex.: ler a bbox)

✗ O que ele NÃO é

✗ Não renderiza o vídeo (isso é o HyperFrames, na T3)
✗ Não grava vídeo da tela (isso seria o modo v3, roadmap)
✗ Não precisa de chave de API nem de nuvem
✗ Não anima nada — só captura o estado real

📦 Pré-requisitos da captura

agent-browser no PATH

A skill de navegação precisa estar disponível na linha de comando.

App no ar

O app-alvo precisa estar rodando, ex.: localhost:8000.

Node 22+

O capture.mjs roda em Node e chama o agent-browser.

2

🔗 Abrir sessão e navegar a URL

Fixe o viewport, abra a URL e estabeleça o estado. A ordem importa: viewport antes de abrir.

Abrir o app (forma manual)

# viewport ANTES de abrir — vira o espaço das coordenadas

agent-browser set viewport 1280 800

agent-browser open http://localhost:8000/

agent-browser snapshot -i # descobre refs @e1, @e2...

💡

A sessão fica viva entre comandos

Cada comando atua na mesma aba aberta. Você navega, age, captura e mede — passo a passo — sem reabrir o app a cada chamada.

Equivalente no actions.json (forma automatizada)

{

"url": "http://localhost:8000/",

"viewport": [1280, 800]

}

# o capture.mjs faz set viewport + open com esses valores

3

📑 Referências @ref e snapshot

O snapshot -i mapeia os elementos e dá refs (@e1, @e2…) — mas eles deslocam quando o DOM muda.

Fluxo de descoberta de elementos

1

snapshot -i lista os interativos

Cada botão, campo e link ganha um ref (@e6 = textarea, por exemplo).

2

Você age pelo ref

agent-browser fill @e6 "texto" preenche aquele elemento específico.

3

DOM mudou? Re-snapshot

Depois de "Gerar", surge um link de download e os refs deslocam. Re-snapshot ou troque por seletor estável.

⚠️

Refs são voláteis

Não confie em @eN quando o estado muda entre passos. Em telas que mudam muito, prefira CSS selectors ou {tag,text} — assunto do módulo 2.3.

4

🖱️ Ações: click, fill, scroll, screenshot

O vocabulário básico de cada passo. Cada ação muda o estado da tela — e cada estado vira um screenshot.

Ação	O que faz	Status
fill	Preenche input/textarea (CSS selector)	funciona
click	Clica um elemento (CSS selector)	funciona
screenshot	Salva a tela do estado atual em PNG	funciona
eval	Roda JS no browser (ex.: ler a bbox)	funciona
scroll	Rolar até o alvo antes do screenshot	manual / roadmap

💡

Scroll ainda é manual

O capture.mjs não rola a página por conta própria. Em páginas longas, hoje você dirige o agent-browser na mão (scrollIntoView). É o item nº 1 do backlog — detalhado no módulo 2.4.

5

📸 Capturar o screenshot da tela

Um screenshot por estado, gravado em assets/shots/NN-id.png. É a base da regra de ouro: capturar antes, animar depois.

Capturar antes, animar depois

O render do HyperFrames é determinístico (sem rede na renderização). Por isso nunca se carrega o site ao vivo no vídeo: a gente captura prints reais antes e anima por cima.

Capturar um estado

agent-browser fill @e6 "um cavalo galopando na praia"

agent-browser screenshot assets/shots/01-prompt.png

# 1 shot por estado → 02-size.png, 03-height.png, 04-resultado.png ...

🖼️

1 por estado

um shot/passo

📁

assets/shots/

NN-id.png

🎯

Determinístico

sem site ao vivo

🪟

Na moldura

look de navegador

6

📐 Medir a bounding box de um elemento

Via eval, ler o getBoundingClientRect() do alvo. É a caixa exata que o cursor mira no vídeo.

Ler a bbox do alvo

# bbox no espaço do screenshot (viewport-relative)

agent-browser eval "(()=>{const r=

document.querySelector('textarea').getBoundingClientRect();

return{x:Math.round(r.x),y:Math.round(r.y),

w:Math.round(r.width),h:Math.round(r.height)}})()" --json

# resultado: {"x":129,"y":252,"w":482,"h":96}

⚠️

eval --json vem aninhado

O resultado fica em data.result (não em result). O capture.mjs já trata isso — mas vale saber se dirigir na mão.

💡

É isso que faz parecer profissional

A bbox real (não "no olho") é o que faz o cursor cair exato no botão/campo. O mapeamento da bbox para o canvas do vídeo é o tema do módulo 2.3.

7

🖼️ O viewport fixo e por que ele importa

O viewport da captura é o espaço de coordenadas de tudo. Mantenha-o igual para bboxes e screenshots — senão o cursor erra o alvo.

✓ Viewport bem feito

✓ O mesmo viewport para bbox e screenshot
✓ Largura ≤ ~1280 para caber no canvas 16:9
✓ Se recapturar, recapturar tudo no mesmo viewport
✓ set viewport antes de open

✗ Viewport quebrado

✗ Capturar bbox e shot em viewports diferentes
✗ Telas muito largas saem espremidas ou estouram
✗ Recapturar só uma tela e misturar com as antigas
✗ Abrir o app e só depois fixar o viewport

📊 Limites do screenshot no canvas

Com viewport 1280×800 e a janela centralizada, o print vai de x320..1600 e y148..948 — dentro do canvas 1920×1080. Mude o viewport e confira que não passa das bordas.

🎯 Resumo do módulo

✓ agent-browser = Playwright na linha de comando; usa o app de verdade
✓ viewport ANTES de open; snapshot -i dá refs @eN voláteis
✓ ações: fill, click, screenshot, eval (scroll ainda é manual/roadmap)
✓ 1 shot por estado em assets/shots/NN-id.png
✓ bbox via getBoundingClientRect; viewport fixo = espaço de coordenadas

Próximo módulo

2.2

🗺️ O actions.json

Descreva URL, viewport e os passos num único arquivo e deixe o capture.mjs gerar os shots e o steps.json.

Ir para o módulo 2.2 →

← Voltar para Trilha 2 Próximo Módulo: 2.2 actions.json →