Plugin API

O host publica pontos nomeados em momentos específicos. Plugins registram callbacks. WordPress diferencia actions, que executam efeitos, e filters, que recebem e retornam valores. Uma plataforma de automação pode emitir `device_added`, `state_changed` ou `automation_executed`. O contrato precisa definir ordem, argumentos, retorno e tratamento de exceção. Prioridades podem alterar resultado. Dois plugins podem modificar o mesmo valor. Reentrância e loops são riscos. Um callback lento bloqueia o host se a API for síncrona. APIs modernas oferecem eventos assíncronos ou filas. O plugin deve remover listeners no unload para evitar vazamento. Hooks não são um barramento sem governança; nomes e payloads precisam de versão.

A Plugin API pode exigir que a extensão implemente uma interface, como `Plugin<T>.apply(target)` no Gradle, ou registre serviços. O host chama métodos padronizados: inicializar, iniciar, parar, configurar e diagnosticar. O plugin pode fornecer novos tipos de dispositivo, ações, painéis ou conectores. Interfaces tipadas detectam erros em compilação. APIs dinâmicas dependem de testes. O contrato deve dizer quais métodos podem ser chamados em paralelo e quais objetos permanecem válidos. O plugin não deve guardar referências internas além do ciclo de vida. Compatibilidade semântica importa: manter a mesma assinatura enquanto muda o efeito também quebra.

Plugins são identificados por ID, versão, dependências, permissões e versão mínima do host. Home Assistant usa `manifest.json` para domínio, documentação, requisitos, dependências, discovery e qualidade. Navegadores usam manifestos de extensões. O host lê antes de carregar. Isso permite rejeitar incompatibilidade e resolver dependências. O manifesto precisa ser validado. IDs são estáveis. Versões seguem convenção como SemVer quando adotada. Dependências transitivas aumentam risco. O carregamento não deve executar código antes de verificar assinatura e política quando a plataforma oferece. Um arquivo de metadados não é sandbox; permissões precisam ser aplicadas pelo runtime.

Plugins podem registrar páginas, cartões, widgets ou painéis. Home Assistant permite custom panels com acesso em tempo real ao objeto da aplicação. WordPress oferece APIs administrativas e de blocos. O host precisa fornecer componentes, temas, tradução e roteamento. A extensão não deve manipular DOM interno não documentado, porque atualizações quebram. Content Security Policy, isolamento, sanitização e permissões são necessários. Um painel pode expor câmeras, presença e fechaduras; o backend deve autorizar cada dado, não confiar na visibilidade do menu. A API de UI precisa ter versionamento e fallback. Recursos visuais não devem bloquear o núcleo se falharem.