Componente web nativo

O elemento nativo <orb-z> é a base do Orbz. Funciona onde houver suporte a elementos personalizados, com JavaScript puro ou frameworks.

Registro automático

Importe a entrada do navegador uma vez no código da aplicação:

import "@neongate-ai/orbz/browser";

O módulo chama defineOrbz() por você. O registro é protegido: não faz nada no servidor e retorna o construtor existente se outra parte da página já registrou orb-z.

A tag pode ser renderizada antes ou depois do módulo. O navegador atualiza as tags existentes quando o elemento personalizado é definido.

<orb-z state="idle" size="18rem"></orb-z>

Conectar ou atualizar o elemento nunca inicia a fala. O host deve configurar um mecanismo de voz e chamar startTalking() quando o visitante optar por ouvir.

Registro explícito

Use a entrada raiz para escolher exatamente quando registrar:

import { defineOrbz } from "@neongate-ai/orbz";
 
const OrbzElementClass = defineOrbz();

defineOrbz() retorna o construtor no navegador e undefined quando customElements ou HTMLElement não estão disponíveis. Chamadas repetidas são seguras.

Controle por atributos

<orb-z
  state="thinking"
  size="320px"
  speed="1.15"
  preset="periwinkle"
  reduced-motion="system"
  elevated
></orb-z>

O elemento observa alterações, portanto atualizar um atributo sincroniza a apresentação imediatamente:

const orb = document.querySelector("orb-z");
 
orb?.setAttribute("state", "speaking");
orb?.setAttribute("speed", "1.25");
orb?.toggleAttribute("elevated", true);

Controle por propriedades

Propriedades costumam ser mais claras ao alterar estados em JavaScript:

import type { OrbzElement } from "@neongate-ai/orbz";
 
const orb = document.querySelector<OrbzElement>("orb-z");
 
if (orb) {
  orb.state = "listening";
  orb.size = 300; // normalized to "300px"
  orb.speed = 1.2;
  orb.reducedMotion = "system";
  orb.elevated = true;
}

Cada propriedade pública reflete no atributo correspondente. size aceita um número, convertido em pixels, ou uma string de comprimento CSS como "20rem".

Mecanismos de voz e fluxos de conversa são propriedades exclusivas de JavaScript. Prepare o fluxo, insira o elemento e só configure o mecanismo e inicie a fala após uma ação explícita:

import "@neongate-ai/orbz/browser";
import { WebSpeechAdapter, type OrbzElement, type OrbzTalkStep } from "@neongate-ai/orbz";
 
const flow = [
  { id: "welcome", kind: "say", needsAuth: false, text: "Hello." },
  { id: "name", kind: "ask", needsAuth: false, text: "What is your name?", capture: "fullName" },
  { id: "help", kind: "say", needsAuth: false, text: "How can I help, {{fullName}}?" },
  { id: "answer", kind: "respond", needsAuth: false, strategy: "openai", fallback: "I cannot answer that right now." }
] as const satisfies readonly OrbzTalkStep[];
 
const orb = document.createElement("orb-z") as OrbzElement;
orb.talkFlow = flow;
orb.voiceEngine = new WebSpeechAdapter({ language: "en-US" });
document.body.append(orb);
 
const startVoiceButton = document.querySelector<HTMLButtonElement>("[data-start-voice]");
startVoiceButton?.addEventListener("click", async () => {
  await orb.startTalking();
});

Atributos booleanos

paused e elevated seguem a semântica booleana nativa do HTML: a presença do atributo significa verdadeiro, independentemente da string atribuída.

<!-- Elevated -->
<orb-z elevated></orb-z>
 
<!-- Also elevated: "false" is still a present attribute -->
<orb-z elevated="false"></orb-z>

Remova o atributo ou atribua false à propriedade:

orb?.removeAttribute("elevated");
 
if (orb) {
  orb.paused = false;
  orb.elevated = false;
}

Preset integrado ou paleta personalizada

Escolha um preset de cores com o atributo preset:

<orb-z preset="magenta"></orb-z>

A aparência padrão é Neongate; omita preset para selecioná-la entre versões. Os demais presets são periwinkle, magenta, peach, mocha e ivory. Veja nomes e compatibilidade.

Para uma paleta personalizada, omita preset e defina qualquer um dos cinco atributos de cor:

<orb-z
  color-primary="#7C3AED"
  color-secondary="#22D3EE"
  color-accent="#F472B6"
  color-highlight="#FDE68A"
  color-background="#09090B"
></orb-z>

Cores ausentes usam os padrões Neongate. Não combine preset explícito com color-*. Se ambos estiverem presentes, o preset prevalece e Orbz relata o conflito no console.

Controle pela máquina de estados da aplicação

Mantenha a aplicação como fonte de verdade e faça Orbz refletir esse estado:

import type { OrbzElement, OrbzState } from "@neongate-ai/orbz";
 
const orb = document.querySelector<OrbzElement>("orb-z");
 
function presentAssistantState(state: OrbzState, message: string) {
  if (orb) orb.state = state;
 
  const status = document.querySelector<HTMLElement>("[data-assistant-status]");
  if (status) status.textContent = message;
}
 
presentAssistantState("thinking", "Assistant is preparing a response");

Os cinco estados suportados são idle, listening, thinking, speaking e asleep. Valores desconhecidos são normalizados para idle.

Métodos de reprodução

O elemento nativo expõe três métodos específicos de animação:

orb?.pause();   // freeze the current animation
orb?.play();    // resume it
orb?.restart(); // rebuild the current state's animation

A propriedade e o atributo paused continuam sendo a opção declarativa. Use métodos quando a integração imperativa com o navegador for mais conveniente.

Preferências de movimento

reduced-motion="system" segue prefers-reduced-motion e reage a mudanças. Use always para forçar a apresentação reduzida ou never para forçar o perfil completo.

<div role="status" aria-live="polite">
  <orb-z state="thinking" reduced-motion="system"></orb-z>
  <span data-assistant-status>Assistant is thinking</span>
</div>

Mantenha texto significativo fora do orb. O componente é um sinal visual e não deve ser a única forma de conhecer o estado do assistente.

Templates de frameworks

Vue, Svelte e Angular vinculam valores reativos diretamente à tag após importar /browser uma vez. Não há adaptador de framework nem runtime compartilhado com Orbz.

Veja aplicações completas no workspace de exemplos .