Estados do assistente

O atributo state seleciona um dos cinco perfis de movimento. O estado comunica uma intenção visual; não liga microfone, chama modelo nem reproduz áudio.

Defina um estado

Use um atributo HTML:

<orb-z state="listening"></orb-z>

Ou atualize a propriedade correspondente:

import "@neongate-ai/orbz/browser";
import type { OrbzElement } from "@neongate-ai/orbz";
 
const orb = document.querySelector<OrbzElement>("orb-z");
 
if (orb) {
  orb.state = "thinking";
}

React e Next.js renderizam a mesma tag nativa após importar a entrada do navegador:

import "@neongate-ai/orbz/browser";
import type { OrbzState } from "@neongate-ai/orbz";
 
export function AssistantPresence({ state }: { state: OrbzState }) {
  return <orb-z state={state} />;
}

Alterar state substitui a animação pelo perfil do novo estado. Se paused estiver presente, Orbz renderiza o novo estado e mantém a animação pausada.

Mantenha estados do domínio fora do Orbz

Assistentes reais têm estados adicionais: pedir permissão, reconectar, aguardar ferramenta, recuperar erro ou receber interrupção. Mantenha-os na aplicação e mapeie para a intenção visual mais próxima.

type SessionPhase =
  | "booting"
  | "ready"
  | "capturing"
  | "transcribing"
  | "requesting"
  | "playing"
  | "offline"
  | "failed";
 
const visualState = {
  booting: "idle",
  ready: "idle",
  capturing: "listening",
  transcribing: "thinking",
  requesting: "thinking",
  playing: "speaking",
  offline: "asleep",
  failed: "idle",
} as const;

Detalhes de erros devem aparecer em texto ou controles reais. Mudar só a cor ou o movimento não explica uma falha.

Valores inválidos ou ausentes

O padrão é idle. Remover state ou atribuir um valor não suportado em código sem tipagem normaliza para idle. Use OrbzState ou ORBZ_STATES no TypeScript para evitar valores inválidos.

import { ORBZ_STATES, type OrbzState } from "@neongate-ai/orbz";
 
function setState(state: OrbzState) {
  // state is one of the five documented values
}
 
for (const state of ORBZ_STATES) {
  console.log(state);
}

O estado também precisa ser percebido

Movimento é apresentação, não anúncio. Combine o orb com texto de status visível e uma região viva quando as mudanças forem relevantes:

<div role="status" aria-live="polite">
  <orb-z state="thinking"></orb-z>
  <span>Assistant is thinking</span>
</div>

Esse padrão mantém o significado com animação reduzida, pausada, não suportada ou invisível. Continue em Movimento e acessibilidade.