Orbz em microfrontends

Um web component é uma boa fronteira entre microfrontends porque seu contrato de execução pertence ao navegador, sem depender de um framework específico. Orbz pode ser renderizado por um módulo remoto Vue, atualizado por uma aplicação hospedeira Angular e substituído depois por uma interface React sem alterar a tag nem seus atributos.

Orbz é, por escolha, um componente visual folha, sem responsabilidade de roteamento ou de plataforma completa de microfrontends. Use sua estratégia de composição existente para navegação, dados, identidade e implantação. Use orb-z como a presença compartilhada do assistente na interface desses sistemas.

O contrato compartilhado

A integração mais duradoura usa marcação da própria plataforma web:

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

A aplicação hospedeira ou o módulo remoto atualiza propriedades públicas quando o estado do domínio muda:

import type { OrbzElement, OrbzState } from "@neongate-ai/orbz";
 
export function renderAssistantState(state: OrbzState) {
  const orb = document.querySelector<OrbzElement>("orb-z");
  if (orb) orb.state = state;
}

Nenhum objeto de framework atravessa essa fronteira. O contrato consiste em strings, números, atributos booleanos e três métodos.

Escolha quem registra o elemento

Há três modelos práticos.

1. A aplicação hospedeira registra Orbz

A aplicação hospedeira importa o ponto de entrada do navegador uma única vez:

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

Os módulos remotos apenas renderizam <orb-z>. Isso reduz a duplicação do código do pacote e atribui à aplicação hospedeira a responsabilidade explícita pela versão. É a opção padrão mais clara quando ela já cuida dos elementos básicos de design globais.

2. Cada módulo remoto importa a mesma versão fixada

Cada módulo remoto pode depender de Orbz e importá-lo de forma independente. O registro é idempotente: importações posteriores encontram a definição existente de orb-z em vez de defini-la novamente.

Coordene uma versão exata do pacote entre as implantações. O registro de Custom Elements não pode substituir uma tag já definida: prevalece a primeira versão registrada na página. Assim, divergências de versão podem fazer o comportamento depender da ordem de carregamento dos módulos remotos, mesmo sem ocorrer um erro durante o registro.

3. Compartilhe Orbz pelo empacotador ou por um import map

Module Federation, um import map ou outro mecanismo de compartilhamento em tempo de execução pode fornecer uma única instância do pacote. Isso pode reduzir bytes duplicados, mas é uma otimização, não um requisito de Orbz. Mantenha a regra de versão explícita mesmo quando a ferramenta marca o pacote como singleton.

Defina responsabilidades com clareza

Escolha um responsável para cada função:

Evite que vários módulos remotos escrevam no mesmo elemento. Um serviço compartilhado pode publicar o estado do domínio do assistente, mas apenas o módulo remoto que renderiza o orb deve mapear e aplicar esse estado.

Comunique o estado do domínio, não instruções de DOM

Um contrato frágil publica comandos como “deixe o orb roxo” ou “pause a terceira camada”. Isso leva detalhes de apresentação para o barramento da plataforma.

Um contrato mais sólido publica estados significativos da aplicação:

type AssistantStatus =
  | { phase: "ready" }
  | { phase: "capturing" }
  | { phase: "processing" }
  | { phase: "playing" }
  | { phase: "offline" }
  | { phase: "error"; message: string };

O módulo remoto que renderiza o componente mapeia capturing para listening, processing para thinking e assim por diante. Erros continuam sendo comunicados por texto e ações, em vez de se tornarem uma animação não documentada.

Implantações independentes

A estrutura do repositório e a estrutura de implantação são escolhas distintas. Um repositório compartilhado pode facilitar a orquestração local, enquanto cada exemplo ou microfrontend continua sendo um projeto Vercel independente. Da mesma forma, repositórios sem relação entre si podem consumir a mesma versão npm e renderizar um orb idêntico.

Para uma interface implantada de forma independente:

1. adicione @neongate-ai/orbz às dependências da própria aplicação;
2. fixe a versão permitida ou defina seu controle centralizado;
3. importe /browser no ponto de entrada cliente da aplicação;
4. exponha o estado do assistente pelo contrato de dados já existente na aplicação;
5. implante sem importar o código-fonte de Orbz nem outra aplicação de exemplo.

Os exemplos publicados de Vanilla , React , Vue , Svelte , Angular  e Next.js  demonstram seis aplicações hospedeiras independentes usando a mesma interface do componente.

Comportamento em falhas e alternativas

Antes do registro, um elemento personalizado desconhecido continua sendo HTML válido e inerte. Essa fronteira permite uma melhoria progressiva: os rótulos e controles ao redor podem ser renderizados enquanto o pacote do componente carrega.

Projete a aplicação hospedeira para que o assistente seja compreensível sem a animação:

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

Se um módulo remoto não carregar, o texto ainda comunica o estado. Se Orbz for registrado depois, o elemento é atualizado no mesmo lugar.

Lista de verificação de microfrontends

• Use o pacote npm como fronteira; não importe src/ de outra aplicação.
• Coordene uma versão exata de Orbz entre os módulos remotos carregados ao mesmo tempo.
• Sempre que possível, registre em um único local conhecido.
• Mantenha um único responsável por escrever em cada orb renderizado.
• Publique o estado do domínio no barramento da aplicação, sem detalhes visuais internos.
• Mantenha o texto de status e os controles fora do Shadow DOM fechado.
• Teste atualizações da aplicação hospedeira com movimento reduzido e carregamento de JavaScript atrasado.
• Trate o nome da tag e os atributos documentados como a API estável de integração.