# Guia de Referência: Web APIs para IA — Referência MDN Catálogo orientado a decisão das APIs disponibilizadas pelo ambiente Web. O objetivo é evitar que a IA confunda uma API do navegador com a linguagem JavaScript ou use uma capacidade sensível sem avaliar permissões e suporte. --- ## 1. Contrato de execução para a IA - Trate este arquivo como **referência de decisão e implementação**, não como licença para aplicar toda tecnologia disponível. - Antes de codificar, declare o **ambiente** (browser, Node.js, worker, servidor, PWA etc.), os requisitos e as restrições de compatibilidade. - Prefira a solução nativa e simples quando ela atende aos requisitos com boa acessibilidade, segurança e manutenção. - Consulte compatibilidade antes de usar APIs experimentais ou de disponibilidade limitada. - Não misture responsabilidades: estrutura/semântica em HTML, apresentação em CSS, comportamento em JavaScript e capacidades do navegador em Web APIs. - Considere segurança, privacidade, performance e acessibilidade desde o design, não como correções finais. --- ## 2. Documento e observação ### DOM - **Conceito:** Document, Element, Node e manipulação. - **Regra para IA:** Use semântica e APIs seguras; evite reconstruções integrais desnecessárias. ### EventTarget - **Conceito:** Eventos e listeners. - **Regra para IA:** Remova listeners quando o ciclo de vida exigir e use AbortSignal quando conveniente. ### Observers - **Conceito:** MutationObserver, ResizeObserver, IntersectionObserver. - **Regra para IA:** Prefira observer apropriado a polling/layout reads constantes. --- ## 3. Rede ### Fetch API - **Conceito:** Requisições HTTP modernas. - **Regra para IA:** Trate status, abort, CORS e streams corretamente. ### WebSocket - **Conceito:** Canal bidirecional persistente. - **Regra para IA:** Implemente reconexão/backoff e protocolo de mensagens explícito. ### Server-Sent Events - **Conceito:** Eventos unidirecionais do servidor. - **Regra para IA:** Prefira para stream textual simples servidor→cliente quando bidirecionalidade não é necessária. ### Streams - **Conceito:** Readable/Writable/Transform streams. - **Regra para IA:** Use para grandes dados e backpressure em vez de carregar tudo em memória. ### URL/URLSearchParams - **Conceito:** Parsing e construção de URLs. - **Regra para IA:** Use APIs estruturadas, não concatenação frágil de query strings. --- ## 4. Storage e offline ### Web Storage - **Conceito:** KV síncrono simples. - **Regra para IA:** Mantenha pequeno e não sensível. ### IndexedDB - **Conceito:** Storage estruturado assíncrono. - **Regra para IA:** Use para offline e volume maior, com migrações. ### Cache API - **Conceito:** Armazenamento Request/Response. - **Regra para IA:** Use com estratégia de cache clara, frequentemente com Service Worker. ### Service Worker - **Conceito:** Proxy programável em background para rede/cache. - **Regra para IA:** Implemente lifecycle/update/offline conscientemente; não cache respostas privadas indiscriminadamente. --- ## 5. Execução e comunicação ### Web Workers - **Conceito:** Threads de trabalho sem DOM. - **Regra para IA:** Mova CPU pesada quando mensuração indicar bloqueio da main thread. ### BroadcastChannel/MessageChannel - **Conceito:** Mensageria entre contextos. - **Regra para IA:** Defina mensagens versionadas e valide payloads. --- ## 6. Arquivos, mídia e gráficos ### File/Blob/FileReader - **Conceito:** Arquivos e dados binários. - **Regra para IA:** Valide tipo/tamanho no cliente por UX e novamente no servidor por segurança. ### MediaDevices - **Conceito:** Câmera/microfone. - **Regra para IA:** Peça permissão no contexto da ação do usuário e ofereça alternativa. ### Canvas/SVG/WebGL/WebGPU - **Conceito:** Renderização 2D/vetorial/GPU. - **Regra para IA:** Escolha menor tecnologia suficiente e forneça alternativa acessível para informação essencial. ### WebRTC - **Conceito:** Comunicação peer-to-peer de mídia/dados. - **Regra para IA:** Considere signaling, ICE/STUN/TURN, privacidade e estados de conexão. --- ## 7. Segurança e identidade ### Web Crypto - **Conceito:** Primitivas criptográficas. - **Regra para IA:** Não invente protocolos; use primitivas para tarefas apropriadas e trate todo sistema de segurança como conjunto. ### WebAuthn - **Conceito:** Autenticação forte/passkeys. - **Regra para IA:** Use fluxo de servidor correto; nunca tente substituir com criptografia caseira. ### Permissions - **Conceito:** Consulta/gestão de permissões suportadas. - **Regra para IA:** Peça somente no momento necessário e lide com denied/prompt/granted. --- ## 8. Experiência e dispositivo ### Clipboard/Share/Fullscreen - **Conceito:** Integração com ações do usuário. - **Regra para IA:** Acione em resposta a gesto quando exigido e ofereça fallback. ### Geolocation/Sensors - **Conceito:** Dados potencialmente sensíveis. - **Regra para IA:** Explique benefício, menor precisão necessária e fallback; trate privacidade. ### Notifications/Push - **Conceito:** Notificações e mensagens em background. - **Regra para IA:** Solicite permissão após demonstrar valor; evite spam e forneça opt-out. ### History - **Conceito:** Navegação e URL em SPAs. - **Regra para IA:** Mantenha back/forward, deep links e títulos coerentes. --- ## 9. Medição ### Performance APIs - **Conceito:** Marcas, measures, navigation/resource timing. - **Regra para IA:** Meça gargalos reais e associe métricas a UX. --- ## Checklist de aceite 1. [ ] A tecnologia escolhida resolve um requisito real e foi aplicada no ambiente correto. 2. [ ] Semântica, acessibilidade e estados de teclado/foco foram revisados. 3. [ ] Entradas externas são tratadas como não confiáveis e saídas são renderizadas com segurança. 4. [ ] Erros, estados vazios, carregamento, offline/rede e cancelamento foram considerados quando aplicável. 5. [ ] Compatibilidade e fallback foram avaliados para recursos não Baseline/amplamente suportados. 6. [ ] O código não duplica APIs nativas ou responsabilidades de outra camada. 7. [ ] Performance foi medida quando a decisão tem impacto relevante. --- ## Prompt-base para IA ```text Use o guia "Web APIs para IA — Referência MDN" anexado como contrato técnico. Analise meu requisito e escolha somente os conceitos necessários. Diga quais partes do guia serão aplicadas e por quê. Implemente com semântica, acessibilidade, segurança e compatibilidade. Não invente APIs. Ao final, revise a solução pelo checklist do guia. Contexto: [DESCREVA o sistema, stack/versões, ambiente e estado atual] Objetivo: [DESCREVA o resultado observável esperado] Restrições: [DESCREVA o que não pode mudar e os limites técnicos] ``` ### Como preencher os campos - **Contexto:** descreva sistema, stack/versões, arquitetura ou ambiente, estado atual e onde a mudança acontece. - **Objetivo:** descreva o resultado observável esperado — o que o usuário ou o sistema deve conseguir fazer ao final. - **Restrições:** descreva o que não pode mudar e os limites de compatibilidade, segurança, acessibilidade, performance, dependências e escopo. ### Exemplo preenchido ```text Contexto: Painel precisa refletir mudanças do servidor quase em tempo real e hoje faz polling agressivo a cada poucos segundos. Objetivo: Comparar polling, Server-Sent Events e WebSocket e implementar a alternativa mais simples adequada ao fluxo. Restrições: Tratar reconexão/cancelamento; medir consumo; verificar compatibilidade; não manter listeners após a tela ser destruída. ``` --- ## Fontes primárias - MDN Web APIs: https://developer.mozilla.org/pt-BR/docs/Web/API