SSR 与水合

Orbz 将可安全用于服务端的定义与带有保护机制的浏览器注册分开。它不会在模块作用域中求值 HTMLElement 子类。

入口行为

服务端渲染的标记

服务器可以像普通 HTML 一样输出该标签：

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

从稳定的客户端模块导入浏览器入口。注册执行时，现有元素会在原位置升级。

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

也可以显式注册：

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

React 和 Next.js

仅将注册与交互状态放在客户端边界内，然后直接渲染原生标签：

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

确保服务端与客户端首次渲染的属性值一致且可确定。在线状态等仅存在于浏览器的状态应在水合之后读取。

微前端

Custom Elements 注册表在整页范围内共享。最先定义 orb-z 的实现生效，因此共享同一页面的应用必须协调 Orbz 版本，即使重复调用 defineOrbz() 已有保护机制。

检查清单

• 在每个框架中直接渲染 <orb-z>。
• 从客户端代码导入 /browser 一次，或显式调用 defineOrbz()。
• 保持服务端与客户端的初始属性一致。
• 将有语义的状态文本保留在视觉元素之外。
• 不要检查封闭的 Shadow DOM 内部。