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.

subdirectory_arrow_right1. 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.

subdirectory_arrow_right2. Documento e observação

subdirectory_arrow_rightDOM

• Conceito: Document, Element, Node e manipulação.
• Regra para IA: Use semântica e APIs seguras; evite reconstruções integrais desnecessárias.

subdirectory_arrow_rightEventTarget

• Conceito: Eventos e listeners.
• Regra para IA: Remova listeners quando o ciclo de vida exigir e use AbortSignal quando conveniente.

subdirectory_arrow_rightObservers

• Conceito: MutationObserver, ResizeObserver, IntersectionObserver.
• Regra para IA: Prefira observer apropriado a polling/layout reads constantes.

subdirectory_arrow_right3. Rede

subdirectory_arrow_rightFetch API

• Conceito: Requisições HTTP modernas.
• Regra para IA: Trate status, abort, CORS e streams corretamente.

subdirectory_arrow_rightWebSocket

• Conceito: Canal bidirecional persistente.
• Regra para IA: Implemente reconexão/backoff e protocolo de mensagens explícito.

subdirectory_arrow_rightServer-Sent Events

• Conceito: Eventos unidirecionais do servidor.
• Regra para IA: Prefira para stream textual simples servidor→cliente quando bidirecionalidade não é necessária.

subdirectory_arrow_rightStreams

• Conceito: Readable/Writable/Transform streams.
• Regra para IA: Use para grandes dados e backpressure em vez de carregar tudo em memória.

subdirectory_arrow_rightURL/URLSearchParams

• Conceito: Parsing e construção de URLs.
• Regra para IA: Use APIs estruturadas, não concatenação frágil de query strings.

subdirectory_arrow_right4. Storage e offline

subdirectory_arrow_rightWeb Storage

• Conceito: KV síncrono simples.
• Regra para IA: Mantenha pequeno e não sensível.

subdirectory_arrow_rightIndexedDB

• Conceito: Storage estruturado assíncrono.
• Regra para IA: Use para offline e volume maior, com migrações.

subdirectory_arrow_rightCache API

• Conceito: Armazenamento Request/Response.
• Regra para IA: Use com estratégia de cache clara, frequentemente com Service Worker.

subdirectory_arrow_rightService Worker

• Conceito: Proxy programável em background para rede/cache.
• Regra para IA: Implemente lifecycle/update/offline conscientemente; não cache respostas privadas indiscriminadamente.

subdirectory_arrow_right5. Execução e comunicação

subdirectory_arrow_rightWeb Workers

• Conceito: Threads de trabalho sem DOM.
• Regra para IA: Mova CPU pesada quando mensuração indicar bloqueio da main thread.

subdirectory_arrow_rightBroadcastChannel/MessageChannel

• Conceito: Mensageria entre contextos.
• Regra para IA: Defina mensagens versionadas e valide payloads.

subdirectory_arrow_right6. Arquivos, mídia e gráficos

subdirectory_arrow_rightFile/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.

subdirectory_arrow_rightMediaDevices

• Conceito: Câmera/microfone.
• Regra para IA: Peça permissão no contexto da ação do usuário e ofereça alternativa.

subdirectory_arrow_rightCanvas/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.

subdirectory_arrow_rightWebRTC

• Conceito: Comunicação peer-to-peer de mídia/dados.
• Regra para IA: Considere signaling, ICE/STUN/TURN, privacidade e estados de conexão.

shield7. Segurança e identidade

subdirectory_arrow_rightWeb 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.

subdirectory_arrow_rightWebAuthn

• Conceito: Autenticação forte/passkeys.
• Regra para IA: Use fluxo de servidor correto; nunca tente substituir com criptografia caseira.

subdirectory_arrow_rightPermissions

• Conceito: Consulta/gestão de permissões suportadas.
• Regra para IA: Peça somente no momento necessário e lide com denied/prompt/granted.

subdirectory_arrow_right8. Experiência e dispositivo

subdirectory_arrow_rightClipboard/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.

subdirectory_arrow_rightGeolocation/Sensors

• Conceito: Dados potencialmente sensíveis.
• Regra para IA: Explique benefício, menor precisão necessária e fallback; trate privacidade.

subdirectory_arrow_rightNotifications/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.

subdirectory_arrow_rightHistory

• Conceito: Navegação e URL em SPAs.
• Regra para IA: Mantenha back/forward, deep links e títulos coerentes.

subdirectory_arrow_right9. Medição

speedPerformance APIs

• Conceito: Marcas, measures, navigation/resource timing.
• Regra para IA: Meça gargalos reais e associe métricas a UX.

subdirectory_arrow_rightChecklist 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.

smart_toyPrompt-base para IA

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]

helpComo 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.

lightbulbExemplo preenchido

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.

library_booksFontes primárias

• MDN Web APIs: https://developer.mozilla.org/pt-BR/docs/Web/API