SSR とハイドレーション

Orbz は、サーバーで安全に使える定義と、実行環境を確認するブラウザー登録処理を分離しています。モジュールのスコープで HTMLElement のサブクラスを評価することはありません。

エントリーポイントの動作

インポート	用途	サーバーでの動作
`@neongate-ai/orbz`	型、定数、アダプター、ヘルパー、明示的な登録	自動登録しない
`@neongate-ai/orbz/browser`	すべてのフレームワーク向けのブラウザーエントリー	Custom Elements レジストリがなければ何もしない
`@neongate-ai/orbz/standalone`	自己完結したブラウザー/CDN ビルド	実行環境を確認するブラウザー登録経路を使う

サーバーはこのタグを通常の 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();

クライアント境界は登録と対話的な状態のためにだけ使い、ネイティブタグを直接表示します。


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

サーバーとクライアントの初回描画で属性を確定的に保ってください。オンライン状態など、ブラウザーにしか存在しない状態はハイドレーションの後で読み取ります。

Custom Elements レジストリはページ全体で共有されます。最初に orb-z を定義した実装が使われるため、defineOrbz() の重複呼び出しが保護されていても、同じページを共有するアプリケーション間では Orbz のバージョンを統一する必要があります。