SSR and hydration

Orbz separates server-safe definitions from guarded browser registration. It does not evaluate an HTMLElement subclass at module scope.

Entry-point behavior

Import	Purpose	Server behavior
`@neongate-ai/orbz`	Types, constants, adapters, helpers, explicit registration	No automatic registration
`@neongate-ai/orbz/browser`	Browser entry for every framework	No-op without a Custom Elements registry
`@neongate-ai/orbz/standalone`	Self-contained browser/CDN build	Uses the guarded browser registration path

Server-rendered markup

A server can emit the tag as ordinary HTML:


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

Import the browser entry from a stable client module. The existing element upgrades in place when registration runs.


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

Or register explicitly:


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

React and Next.js

Use a client boundary only for registration and interactive state, then render the native tag directly:


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

Keep server and first-client attributes deterministic. Read browser-only state such as online status after hydration.

Microfrontends

The Custom Elements registry is page-global. The first implementation that defines orb-z wins, so applications sharing one page must coordinate the Orbz version even though repeated defineOrbz() calls are guarded.

Checklist

Render <orb-z> directly in every framework.
Import /browser once from client code or call defineOrbz() explicitly.
Keep initial attributes identical across server and client.
Keep semantic status text outside the visual element.
Do not inspect the closed Shadow DOM.