SSR e hidratação

Orbz separa as definições seguras para o servidor do registro protegido no navegador. Ele não avalia uma subclasse de HTMLElement no escopo do módulo.

Comportamento dos pontos de entrada

Marcação renderizada no servidor

Um servidor pode emitir a tag como HTML comum:

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

Importe o ponto de entrada do navegador em um módulo cliente estável. O elemento existente é atualizado no mesmo lugar quando o registro é executado.

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

Ou faça o registro explicitamente:

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

React e Next.js

Use uma fronteira cliente apenas para o registro e o estado interativo; depois, renderize a tag nativa diretamente:

"use client";
 
import "@neongate-ai/orbz/browser";
 
export function AssistantPresence() {
  return <orb-z state="idle" size="300px" />;
}

Mantenha determinísticos os atributos do servidor e da primeira renderização cliente. Leia estados exclusivos do navegador, como o status de conexão, após a hidratação.

Microfrontends

O registro de Custom Elements é global na página. Prevalece a primeira implementação que define orb-z, por isso aplicações que compartilham uma página precisam coordenar a versão de Orbz, mesmo com a proteção contra chamadas repetidas de defineOrbz().

Lista de verificação

• Renderize <orb-z> diretamente em todos os frameworks.
• Importe /browser uma vez no código cliente ou chame defineOrbz() explicitamente.
• Mantenha os atributos iniciais idênticos no servidor e no cliente.
• Mantenha o texto semântico de status fora do elemento visual.
• Não inspecione o Shadow DOM fechado.