Histórico de versões

Esta página registra as mudanças visíveis para usuários do pacote público @neongate-ai/orbz, do contrato do elemento personalizado <orb-z> e das integrações suportadas.

O repositório no GitHub é a fonte de verdade da implementação. As versões publicadas estão no npm , e a documentação completa está em orbz.site .

1.0.2 — 2026-09-08

Correção do preset Neongate

Restaurado neongate como nome canônico do preset padrão, incluindo DEFAULT_ORBZ_PRESET, ORBZ_PRESET_NAMES e o getter normalizado do elemento. As cores Neongate não mudaram.
Mantido o nome acidental derivado da conta na versão 1.0.1 como alias de entrada obsoleto. Atributos, atribuições de propriedades, entradas tipadas e validadores existentes continuam aceitando-o; normalização e reflexão de atributos usam neongate.
Mantida uma chave de paleta obsoleta como alias imutável e não enumerável de ORBZ_PRESETS.neongate. A lista canônica continua com seis presets.
Normalizados os objetos legados de configuração compacta e completa sem alterar a entrada do chamador, preservando as cores fornecidas e a validação estrita.

Atualização da versão 1.0.1

Instale a correção publicada e atualize as URLs de CDN fixadas:


npm install @neongate-ai/orbz@1.0.2

Use neongate nos novos valores explícitos de preset. Entradas existentes com a antiga chave derivada da conta continuam compatíveis; migre quando for conveniente. Código que lê o nome normalizado deve esperar neongate. Veja Nome do preset Neongate para exemplos padrão e acesso à paleta.

Esta correção substitui a orientação de nomes da versão 1.0.1, mantida abaixo como histórico. O escopo npm continua @neongate-ai/orbz; o repositório mantido agora pertence a jonatassales.

Ver 1.0.2 no npm · Consultar o código da tag v1.0.2 · Comparar o código das tags

1.0.1 — 2026-09-08

Limpeza e configuração compacta

Corrigido orb cleanup (alias orb clean) no checkout do Orbz para remover por padrão node_modules não rastreados, na raiz e em subpastas, e saídas geradas. --dry-run mostra os alvos; --keep-dependencies preserva dependências. Conteúdo rastreado, código/recursos, metadados do harness e repositórios aninhados são preservados; a limpeza não segue links simbólicos de diretórios.
Simplificado o JSON de configuração autoral. O transformador preenche grupos internos omitidos de aparência, movimento e fala com padrões tipados, depois valida, clona e congela a configuração de execução. Substituições explícitas desses grupos continuam suportadas.
Atualizados os links de propriedade no GitHub para a conta pessoal vigente na época, além do README, guia da CLI e verificações de engenharia. O pacote npm continua @neongate-ai/orbz.

Atualização da versão 1.0.0

Instale a correção e atualize as URLs de CDN fixadas:


npm install @neongate-ai/orbz@1.0.1

Esta versão renomeou temporariamente o preset padrão para o identificador de uma conta pessoal, mantendo as cores de neongate. A versão 1.0.2 restaurou neongate como nome canônico; use <orb-z preset="neongate"></orb-z> em novas integrações. Se você mantém um checkout do Orbz, use orb cleanup --keep-dependencies para preservar node_modules; orb cleanup sozinho agora o remove. Esses detalhes de migração se aplicam mesmo sendo uma versão de correção.

Ver 1.0.1 no npm · Comparar o código das tags

1.0.0 — 2026-09-06

Modelos de voz e conversas Realtime

Adicionada a propriedade JavaScript tipada voiceModel para web-speech, openai-speech e openai-realtime. Selecionar um provedor permanece silencioso; a aplicação inicia explicitamente a fala ou conversa após ativação do usuário.
Adicionados OpenAIRealtimeAdapter e áudio WebRTC direto do navegador ao provedor. As aplicações autorizam a sessão por realtimeSession, com endpoint próprio ou callback assíncrono que retorna uma resposta SDP.
Adicionados startConversation(), stopConversation(), interruptConversation(), conversationState somente leitura e os eventos orbz-conversation-state-change e orbz-transcript para controles e transcrições da aplicação.
As chaves do provedor ficam no backend da aplicação. As configurações do modelo contêm apenas dados públicos; objetos de endpoint rejeitam campos desconhecidos como apiKey, token e headers. Segredos e tokens de sessão não pertencem a atributos HTML, propriedades do componente ou JSON de configuração.

Configuração canônica e CLI

Mantenedores de forks agora editam src/orbz.config.json para os padrões do componente, aparência, movimento, fala e Realtime, e recompilam o pacote. Pacotes instalados usam padrões incorporados, sem buscar configuração durante a execução.
Adicionados orbzConfiguration somente leitura e o utilitário puro transformOrbzConfiguration() para validar, clonar, transformar e congelar configurações completas sem modificar o singleton do pacote.
Consolidados o processamento de comandos e a ajuda da Orb CLI. Exportações públicas, atributos visuais, registro nativo e integrações explícitas com voiceEngine continuam disponíveis.

Atualização da versão 0.4.3

Instale a versão publicada e atualize as URLs de CDN fixadas:


npm install @neongate-ai/orbz@1.0.0

Os exemplos visuais existentes mantêm <orb-z> e a mesma entrada de navegador. As novas opções estruturadas usam propriedades JavaScript; não existe atributo HTML voice-model. Realtime exige autorização de sessão pela aplicação e ativação explícita; atualizar o pacote não inicia áudio nem solicita microfone. Um voiceEngine explicitamente atribuído tem precedência sobre voiceModel.

Ver 1.0.0 no npm

0.4.3 — 2026-09-04

Destaques desde a versão 0.3.1

Adicionada a CLI POSIX orb como binário do pacote publicado. Execute temporariamente com npx -y --package=@neongate-ai/orbz@latest orb.
A configuração de projetos Orb detecta npm, pnpm, Yarn ou Bun pelos metadados e lockfiles, instala a versão do Orbz em execução e não gera nem sobrescreve código da aplicação.
WebSpeechAdapter agora usa português brasileiro (pt-BR) por padrão. Aplicações podem substituir language, inclusive por en-US, quando necessário.
Orbz agora é distribuído sem saudação pronta, persona ou fluxo de conversa padrão. Consumidores fornecem speech ou talkFlow, configuram um voiceEngine e chamam startTalking() explicitamente.

Ver 0.4.3 no npm

0.3.1 — 2026-08-25

Ativação explícita da fala

Conectar ou atualizar <orb-z> não cria mais um mecanismo de voz padrão nem inicia um fluxo de conversa.
voiceEngine agora é undefined por padrão. Aplicações fornecem um mecanismo explicitamente e chamam startTalking() após a adesão do visitante.
Atribuir um mecanismo de voz permanece silencioso; stopTalking() interrompe um fluxo ativo, e atribuir undefined remove o mecanismo configurado.
Strings numéricas em HTML ou marcação renderizada no servidor agora são normalizadas para pixels de forma consistente com propriedades numéricas.

Ver 0.3.1 no npm

0.3.0 — 2026-08-23

Tipagem para React e Next.js

Adicionada a entrada opcional @neongate-ai/orbz/react-types para projetos TypeScript com React e Next.js.
A entrada amplia o JSX para tipar <orb-z> sem um componente adaptador de framework.
React continua ausente das dependências de execução do Orbz; seus tipos são usados apenas na compilação da entrada opcional de declarações.

0.2.0 — 2026-08-22

Orbz 0.2.0 amplia o componente visual original para um elemento personalizado com voz e independente de framework. Esta versão introduz um runtime de conversa, portas intercambiáveis de fala e inteligência, controles de aparência mais estritos, encapsulamento reforçado e um único modelo de integração nativa para todos os frameworks suportados.

Versão anterior à 1.0 com mudanças incompatíveis: aplicações que usam colors da versão 0.1.0, variáveis CSS públicas, Shadow Parts, Shadow DOM aberto ou @neongate-ai/orbz/react precisam migrar.

Runtime de voz e conversa

Adicionado um fluxo de conversa automático e determinístico após a primeira renderização conectada do elemento.
Adicionadas as etapas welcoming, askName, help e answer pelo objeto público talk e por DEFAULT_TALK_FLOW.
Adicionada memória de conversa apenas em execução. O fluxo padrão captura o nome do visitante e o disponibiliza em talkContext, sem escrever em cookies, armazenamento local, IndexedDB ou backend.
Adicionado startTalking() para redefinir o contexto atual e reiniciar o fluxo configurado.
Adicionado receive(input) para a aplicação continuar uma etapa ativa de pergunta ou resposta com texto da própria interface.
Adicionado stopTalking() para parar o fluxo e a saída de voz.
Adicionadas as propriedades configuráveis voiceEngine, talkFlow e intelligence.
Adicionados OrbzTalkStep, OrbzTalkContext e OrbzVoiceOptions como contratos públicos TypeScript.
Adicionado OrbzVoiceEnginePort para substituir a saída de fala sem mudar o componente.
Adicionado OrbzIntelligencePort para conectar um agente ou outro provedor de respostas, mantendo lógica de produto e credenciais fora do Orbz.
Adicionadas respostas locais alternativas quando não há provedor de inteligência ou quando ele falha.
Adicionado orbz-speaking-change com detalhes { speaking: boolean }.
Adicionado orbz-talk-error com o erro original em { error: unknown }.
Orbz passa temporariamente ao estado visual speaking durante o áudio e restaura o estado anterior ao terminar.
Captura de microfone, reconhecimento de fala, permissões, transcrições e entrada de texto continuam sob responsabilidade da aplicação. Orbz recebe apenas o texto passado por receive().

Fala do navegador

Adicionado WebSpeechAdapter como mecanismo padrão sem configuração.
Alterado o idioma padrão de fala para en-US.
A fala do navegador aguarda a lista de vozes carregada de forma assíncrona antes de escolher uma voz.
Adicionado filtro explícito para inglês em vez de aceitar uma voz padrão do sistema em outro idioma.
Adicionada seleção de vozes preferidas configuradas e de vozes Google, Microsoft, naturais, neurais, premium, aprimoradas ou online de maior qualidade, quando disponíveis no navegador.
Adicionadas configurações de idioma, vozes preferidas, velocidade, tom, volume e tempo limite de carregamento.
Adicionada detecção de falha ao iniciar a fala, evitando deixar o fluxo pendente indefinidamente.
Quando NotAllowedError bloqueia o áudio automático, a fala da primeira renderização tenta novamente após a primeira interação por ponteiro, teclado ou toque.
Removido o comportamento do exemplo que dependia de remontar o elemento por Redefinir tudo antes de iniciar a fala.
Esclarecido que as vozes continuam sendo fornecidas pelo navegador e sistema operacional do visitante. Melhorar a seleção não transforma uma voz do sistema em voz gerada pela OpenAI.

Fala da OpenAI

Adicionado OpenAISpeechAdapter para conversão de texto em fala da OpenAI via proxy da aplicação.
O adaptador usa por padrão gpt-4o-mini-tts, voz marin, saída MP3 e instruções de fala natural em inglês americano.
Adicionadas configurações de modelo, voz, formato de resposta, instruções, credenciais, cabeçalhos e implementação de fetch.
Adicionada compatibilidade com tts-1 e tts-1-hd, incluindo voz padrão compatível e omissão de instruções não suportadas.
A chave da OpenAI permanece fora do navegador e do pacote Orbz. O adaptador chama um endpoint do implementador que retorna o áudio gerado.
Adicionado cancelamento de solicitações pendentes quando a saída é interrompida ou substituída.
Adicionada limpeza das URLs de objetos de áudio após reprodução, cancelamento ou falha.
Adicionado tratamento de erros de ativação do navegador para o áudio gerado participar do mesmo ciclo de nova tentativa na primeira interação.

Aparência e API do componente

Substituída a propriedade aberta colors por dois modos estritos e mutuamente exclusivos:
- um atributo ou propriedade preset;
- os cinco atributos color-primary, color-secondary, color-accent, color-highlight e color-background.
Adicionados seis presets: neongate, periwinkle, magenta, peach, mocha e ivory.
Os modos de preset e cores personalizadas são exclusivos. Se ambos estiverem presentes, Orbz relata conflito, aplica o preset e ignora as cores até remover o atributo de preset.
Adicionados atributo e propriedade booleanos elevated para uma sombra centralizada opcional.
Mantidos os cinco estados públicos: idle, listening, thinking, speaking e asleep.
Mantidos multiplicadores positivos de velocidade, normalização de tamanho, pausa e reprodução, reinício da animação e políticas de movimento reduzido system, always e never.
Mantidos constantes, validadores e normalizadores públicos de estados, presets, movimento reduzido, tamanho, velocidade e cores.
Alterado Shadow DOM de aberto para fechado.
Removidos Shadow Parts públicos e estilização externa por ::part(...).
Removida personalização por variáveis CSS públicas --orbz-*. Seletores e variáveis internos agora são detalhes privados.
Movidos os estilos-fonte para src/element/index.css, mantidos na raiz de sombra fechada e emitidos também em dist/index.css.

Integração com frameworks e entradas do pacote

Removidos o componente React específico e a entrada @neongate-ai/orbz/react.
Removido React das peer dependencies e dependências de desenvolvimento do pacote de runtime.
Padronizadas as integrações no elemento literal <orb-z>.
Atualizadas as integrações React e Next.js para registrar a entrada de navegador e renderizar <orb-z> diretamente.
Adicionadas declarações locais de elementos intrínsecos JSX aos exemplos React e Next.js para tipagem, sem componente adaptador.
Mantido @neongate-ai/orbz como entrada sem efeitos colaterais para tipos, constantes, adaptadores, portas, fábricas e auxiliares de registro explícito.
Mantido @neongate-ai/orbz/browser como entrada que registra <orb-z>.
Mantido @neongate-ai/orbz/standalone como bundle autônomo que se registra para CDN e scripts diretos.
Mantidas as proteções de criação de classe e registro em ambientes renderizados no servidor.
Mantida a idempotência de defineOrbz() quando vários bundles ou microfrontends tentam registrar o elemento.
Renomeado o criador avançado de classes para orbzElementClassFactory().
Movidos os efeitos colaterais de registro para a entrada explícita de navegador, sem executá-los na raiz do pacote.

Compilação, empacotamento e organização interna

Adicionado prepack para validar TypeScript estritamente e recompilar antes de npm pack ou npm publish.
Limitado o pacote npm aos artefatos dist e arquivos incluídos automaticamente pelo npm, como package.json, README.md e LICENSE.
Mantidos documentação, exemplos, instruções internas de agentes, fontes e configuração de workspace fora do tarball npm.
Adicionadas extensões .ts explícitas nos imports de configuração compartilhada do tsdown para o carregamento TypeScript nativo do Node.
Reorganizados módulos internos em core, element, factories, ports, services e talk.
Renomeada a área-fonte voice para talk.
Consolidadas declarações relacionadas em módulos .types.ts.
Removidos prefixos orbz redundantes nos nomes de arquivos internos, mantendo os símbolos públicos Orbz*.
Achatados diretórios desnecessários de arquivo único.
Removida completamente a implementação de runtime React das fontes.

Exemplos e documentação

Adicionadas demonstrações sincronizadas de Vanilla, React, Vue, Svelte, Angular e Next.js com a mesma interface <orb-z>.
Atualizados os controles de redefinição para restaurar estado sem remontar o elemento.
Substituída a estrutura VitePress original por documentação Nextra.
Adicionadas instruções iniciais para integrações nativas, frameworks e CDN.
Adicionados conceitos de filosofia, estados, aparência, movimento e acessibilidade.
Adicionados guias de frameworks, microfrontends, SSR e assistentes de voz.
Adicionadas referências completas da API do elemento e das exportações.
Adicionados exemplos, solução de problemas e migração.
Estabelecido orbz.site como destino principal da documentação.
Estabelecidos subdomínios específicos de frameworks para publicação dos exemplos sincronizados.

Ver 0.2.0 no npm

Migração da versão 0.1.0

Substitua o adaptador React

Remova os imports da antiga entrada React:


import { Orbz } from "@neongate-ai/orbz/react";
 
export function Assistant() {
  return <Orbz state="idle" />;
}

Registre a entrada de navegador e renderize o elemento nativo:


import "@neongate-ai/orbz/browser";
 
export function Assistant() {
  return <orb-z state="idle"></orb-z>;
}

Adicione uma declaração local de elemento intrínseco JSX se TypeScript ainda não reconhecer orb-z. Essa declaração fornece apenas tipagem em compilação; não cria um componente React.

Substitua a API de cores

Remova o antigo objeto colors:


orb.colors = {
  primary: "#7C3AED",
  secondary: "#22D3EE"
};

Use um preset incorporado:


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

Ou use os cinco atributos de cores suportados sem preset:


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

Não combine preset explícito com cores personalizadas, a menos que sua precedência seja intencional.

Remova a personalização externa do Shadow DOM

Remova integrações que dependem de:

element.shadowRoot;
seletores internos;
::part(...);
variáveis CSS públicas --orbz-*;
suposições sobre a estrutura interna do DOM.

Use os atributos, propriedades, métodos, portas, adaptadores, eventos e exportações documentados.

Registre explicitamente o elemento personalizado

Use a entrada de navegador quando o módulo deve registrar <orb-z>:


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

Use a raiz do pacote para importar tipos ou utilitários sem efeitos colaterais no navegador:


import {
  defineOrbz,
  type OrbzElement
} from "@neongate-ai/orbz";

Chame defineOrbz() explicitamente quando o registro precisar ser controlado pela aplicação.

Ative a fala explicitamente

As versões 0.2.0 e 0.3.0 agendavam um fluxo após a primeira renderização conectada. A versão 0.3.1 removeu esse comportamento: aplicações atuais atribuem voiceEngine, talkFlow e intelligence, e chamam startTalking() explicitamente após a adesão do visitante.


import '@neongate-ai/orbz/browser'
import {
  OpenAISpeechAdapter,
  type OrbzElement
} from "@neongate-ai/orbz";
 
const orb = document.createElement("orb-z") as OrbzElement;
 
orb.voiceEngine = new OpenAISpeechAdapter({
  endpoint: "/api/orbz/speech"
});
 
document.body.append(orb);
 
const startVoiceButton = document.querySelector<HTMLButtonElement>("[data-start-voice]");
 
startVoiceButton?.addEventListener("click", async () => {
  await orb.startTalking();
});

Se o navegador rejeitar o áudio solicitado apesar do controle explícito, Orbz tenta o fluxo solicitado novamente na próxima interação.

0.1.0 — Primeira versão pública

Publicado o primeiro pacote @neongate-ai/orbz no npm.
Estabelecido Orbz como visual de voz IA independente de framework, feito com Web Components.
Incluídos cinco estados: idle, listening, thinking, speaking e asleep.
Incluídos tamanho, velocidade, pausa e reprodução configuráveis, reinício da animação e perfis de movimento reduzido.
Adicionados criação e registro seguros para SSR.
Adicionadas entrada de registro e bundle autônomo de navegador.
Adicionado o adaptador React inicial.
Expostas cores pela propriedade JavaScript colors.
Expostas variáveis CSS públicas --orbz-*.
Utilizados Shadow DOM aberto e Shadow Parts nomeados para personalização externa.

Ver 0.1.0 no npm

Política de versões

Os atributos, propriedades, métodos, eventos, portas, adaptadores, tipos, constantes e exportações documentados são API pública.

A partir do Orbz 1.0.0:

mudanças incompatíveis na API pública incrementam a versão principal;
capacidades compatíveis incrementam a versão secundária;
correções compatíveis incrementam a versão de patch.

Exemplos, documentação, configuração de publicação e organização interna podem evoluir sem criar contratos públicos adicionais de execução. Demonstram e explicam o pacote publicado, mas só integram a API npm se forem exportados explicitamente ou incluídos no contrato documentado do componente.