Use JavaScript puro como referência
O que é: Uma implementação sem framework explicita registro, dependências e cleanup.
Por que aprender: A referência reduz magia e ajuda a diagnosticar problemas escondidos por hooks ou injeção de dependência.
Antes de modelar
Escreva o pedido da pessoa, o estado atual e a evidência que provará conclusão.
Erro de partida
Começar pelo nome de uma função ou por um botão produz uma tool sem objetivo humano claro.
Preveja antes de abrir o código
Qual informação muda a decisão? Qual efeito precisa aparecer na interface? Responda antes de implementar.
const lifecycle = new AbortController();
registerTools(modelContext, services, lifecycle.signal);Indo mais fundo: evidência que vale guardar
Registre a entrada, o estado anterior, a decisão tomada, o resultado e a alteração visível da página.
Inclua também uma falha provocada e o comportamento observado sem suporte WebMCP.
Conceitos-chave
função pura
registro explícito
AbortController
baseline
Modele um hook React idempotente
O que é: O efeito registra tools para o estado atual e o cleanup aborta os registros anteriores.
Por que aprender: Strict Mode, rerenders e mudanças de dependência não podem duplicar nomes no catálogo.
| Pergunta | Contrato forte | Contrato fraco |
|---|---|---|
| Quando usar? | A descrição nomeia intenção e contexto. | “Faz coisas” ou “gerencia”. |
| O que recebe? | Somente dados necessários. | Objeto genérico e ilimitado. |
| O que devolve? | Estado e próxima ação verificáveis. | Texto sem protocolo. |
| Como falha? | Código, motivo e recuperação. | Exceção opaca. |
Faça
- ✓ Use verbos específicos.
- ✓ Delimite entradas.
- ✓ Declare a evidência.
Evite
- ✗ Misturar intenções.
- ✗ Aceitar qualquer objeto.
- ✗ Esconder efeitos.
useEffect(() => {
const controller = new AbortController();
registerTools({ courseId, signal: controller.signal });
return () => controller.abort();
}, [courseId]);Indo mais fundo: evidência que vale guardar
Registre a entrada, o estado anterior, a decisão tomada, o resultado e a alteração visível da página.
Inclua também uma falha provocada e o comportamento observado sem suporte WebMCP.
Conceitos-chave
useEffect
dependências
cleanup
Strict Mode
Encapsule em serviço Angular
O que é: Um serviço recebe dependências, registra as tools e expõe cleanup ao componente ou rota.
Por que aprender: A injeção de dependência mantém regras testáveis e separadas do ciclo visual.
Observe
Capture estado, entrada e contexto antes da ação.
Decida
Valide pré-condições e escolha a transição permitida.
Execute
Aplique a regra compartilhada e respeite cancelamento.
Prove
Atualize a interface e devolva resultado estruturado.
Ponto de controle
Se a etapa 2 reprovar, a tool não tenta “dar um jeito”: ela devolve uma recuperação explícita.
ngOnDestroy() {
this.webMcpRegistration.abort();
}Indo mais fundo: evidência que vale guardar
Registre a entrada, o estado anterior, a decisão tomada, o resultado e a alteração visível da página.
Inclua também uma falha provocada e o comportamento observado sem suporte WebMCP.
Conceitos-chave
service
DI
OnDestroy
testabilidade
Respeite cliente e servidor no Next.js
O que é: document.modelContext só existe no cliente e depois que o documento está ativo.
Por que aprender: Separar componente cliente, carregamento e API do servidor evita acesso ao Document durante SSR.
CÓDIGO DE REFERÊNCIA
"use client";
useEffect(() => registerPageTools(), []);É pequena, descrita e validável.
Reutiliza a regra real da aplicação.
Permite verificar efeito e continuar.
Leia o código como contrato
Sublinhe onde a entrada é validada, onde o efeito acontece, onde o cancelamento chega e onde a UI é atualizada.
Indo mais fundo: evidência que vale guardar
Registre a entrada, o estado anterior, a decisão tomada, o resultado e a alteração visível da página.
Inclua também uma falha provocada e o comportamento observado sem suporte WebMCP.
Conceitos-chave
use client
hydration
SSR
API route
Atualize tools ao trocar de rota
O que é: SPAs precisam retirar ferramentas da rota anterior e registrar apenas as capacidades da nova tela.
Por que aprender: Catálogo obsoleto é stale UI: o agente vê uma ação que a pessoa já não pode executar.
Falha provocada
Execute o cenário com estado ausente, entrada inválida ou capacidade indisponível.
Recuperação esperada
A resposta informa o que falhou, o que permanece seguro e qual ação pode continuar.
Matriz mínima de teste
✓ caminho feliz reproduzível
✓ entrada inválida acionável
✓ cancelamento encerra trabalho
✓ fallback preserva a jornada
✓ interface reflete o estado
✓ backend mantém autorização
routeController.abort("route changed");
routeController = new AbortController();Indo mais fundo: evidência que vale guardar
Registre a entrada, o estado anterior, a decisão tomada, o resultado e a alteração visível da página.
Inclua também uma falha provocada e o comportamento observado sem suporte WebMCP.
Conceitos-chave
router
unmount
catálogo atual
transição
Compare implementações com a mesma prova
O que é: Frameworks diferentes devem cumprir o mesmo contrato observável de registro, execução, UI e cleanup.
Por que aprender: Uma matriz comum separa diferenças de ergonomia de diferenças reais de comportamento.
Exercício de síntese
- 1. Explique o problema sem usar o nome da tecnologia.
- 2. Desenhe o estado anterior e posterior.
- 3. Implemente a menor prova funcional.
- 4. Provoque uma falha e registre a recuperação.
- 5. Entregue código, evidência e uma limitação conhecida.
Desafio do módulo
Implementar o mesmo catálogo em JavaScript puro e em um framework, demonstrando montagem, atualização e desmontagem.
Critério de Integrator responsável
A entrega precisa funcionar, explicar seus limites e preservar o caminho humano quando a capacidade experimental não existir.
| Implementação | registra 1x | atualiza UI | aborta | fallback |
| Vanilla | sim | sim | sim | sim |
| React | sim | sim | sim | sim |Indo mais fundo: evidência que vale guardar
Registre a entrada, o estado anterior, a decisão tomada, o resultado e a alteração visível da página.
Inclua também uma falha provocada e o comportamento observado sem suporte WebMCP.
Conceitos-chave
mesmo contrato
mesmos testes
cleanup provado
compatibilidade
📦 Entrega do módulo
Implementar o mesmo catálogo em JavaScript puro e em um framework, demonstrando montagem, atualização e desmontagem.
Critério de aceite
A entrega funciona com suporte WebMCP e mantém o caminho manual quando a API não existe.
Evidência
Inclua código, cenário testado, resultado observado e uma limitação conhecida.
Fontes técnicas
- Draft e repositório oficial WebMCP
- Especificação renderizada
- Snapshot oficial: 26/08/2026 · commit 41d12f0. A API declarativa permanece experimental; valide o draft antes de produção.