A filosofia do Orbz

Orbz parte de uma ideia pequena: a presença visual de um assistente não deve ser reconstruída toda vez que a aplicação troca de framework.

O navegador já oferece um modelo compartilhado de componentes. Orbz o utiliza: <orb-z> expõe os mesmos estados e controles de aparência e movimento em HTML puro, Vue, Svelte, Angular, React, Next.js ou páginas com microfrontends mistos.

Um contrato, vários hosts

Integrações tendem a divergir: o wrapper React ganha um recurso ausente no Vue, Angular escolhe outros padrões, JavaScript puro é esquecido. Orbz mantém uma implementação nativa, e os frameworks vinculam seus atributos e propriedades públicos.

Assim, todos os hosts têm o mesmo vocabulário:

• cinco estados: idle, listening, thinking, speaking, asleep
• um atributo preset ou cinco atributos de cor personalizados
• size, speed, paused, elevated e reduced-motion
• métodos play(), pause() e restart()

Os seis ambientes de exemplo apresentam a mesma interface de propósito. O código do framework muda; o contrato e a experiência permanecem.

Primitiva visual com interfaces opcionais de fala

Orbz controla a expressão visual e oferece fluxo de conversa opcional com adaptadores para navegador e OpenAI. A aplicação controla as decisões e fronteiras de segurança que dão significado à expressão:

• início e fim da voz, e consentimento do visitante
• permissão do microfone, captura de áudio e reconhecimento de fala
• escolha do mecanismo, endpoints protegidos e credenciais
• pedidos ao modelo, chamadas de ferramentas e streaming
• alternância de turnos, cancelamento, erros e tentativas
• transcrições, botões, rótulos e demais interfaces semânticas

Essa fronteira permite usar qualquer fornecedor de voz, SDK de IA, gerenciador de estado ou backend. A aplicação mapeia eventos do domínio para um dos cinco estados e inicia explicitamente o runtime de conversa quando necessário; Orbz renderiza a presença correspondente.

Veja um mapeamento prático em Como criar um assistente de voz.

Estrito por decisão de projeto

A interface suportada é baseada em atributos. Orbz não expõe partes do Shadow DOM, variáveis CSS públicas nem adaptadores específicos por framework.

Essa rigidez tem três objetivos:

1. Portabilidade. A mesma configuração tem o mesmo significado em todos os hosts.
2. Estabilidade. Camadas e animações internas evoluem sem virar APIs públicas acidentais.
3. Consistência. Equipes personalizam os tokens previstos, sem substituir o componente seletor por seletor.

Para uma identidade visual própria, escolha um preset ou forneça as cinco cores documentadas. Semântica ou interação diferentes pertencem à aplicação ao redor do orb.

Isolamento é uma garantia da implementação

Cada instância cria um Shadow DOM fechado. HTML, estilos e camadas de animação internos são privados. O CSS da página não os reescreve e Orbz não vaza seletores internos.

Fechado não significa inacessível. Orbz é decorativo, então a imagem interna fica oculta das tecnologias assistivas. O host fornece um nome acessível ou, de preferência, texto de status próximo e atualizado que descreve o estado do assistente.

Seguro no servidor, nativo no navegador

O pacote pode ser importado durante SSR sem avaliar uma subclasse de HTMLElement no escopo do módulo. O registro é protegido e idempotente: não faz nada no servidor e só define orb-z se a tag ainda não existir no navegador.

Isso mantém compatibilidade com shells renderizados no servidor e execução nativa no navegador. O servidor emite o elemento e o cliente o atualiza após registrar. A entrada opcional react-types adiciona tipos JSX sem wrapper React ou adaptador de runtime.

Veja os padrões recomendados em SSR e hidratação.

Repositórios seguem as fronteiras públicas

O pacote Orbz, este site e o Orbz Sandbox são projetos independentes. Os exemplos consomem @neongate-ai/orbz@0.3.1 do npm; nem a documentação nem os exemplos importam workspaces de pacotes vizinhos ou caminhos privados de código.

Cada exemplo pode ser implantado como projeto Vercel independente. Um shell de microfrontend usa o mesmo pacote. A fronteira durável é o pacote publicado e o contrato <orb-z>, não a estrutura compartilhada de repositórios.

Como avaliar um novo recurso

Antes de ampliar a interface pública, pergunte:

• É uma necessidade visual comum a todos os frameworks?
• Cabe em um atributo pequeno e serializável ou uma propriedade tipada?
• O comportamento pode ser determinístico em HTML nativo e adaptadores?
• Preserva a fronteira fechada e estrita do componente?
• A aplicação ainda consegue oferecer significado acessível fora do orb?

Se não, o recurso provavelmente pertence ao host. Um contrato pequeno permite que um único componente continue sendo o mesmo em qualquer lugar.