Orbz の設計思想

Orbz は小さな考えから始まります。アプリのフレームワークが変わるたびに、アシスタントの視覚的な存在感を作り直す必要はないはずです。

ブラウザーには共通のコンポーネントモデルが既にあり、Orbz はそれを使います。<orb-z> は通常の HTML、Vue、Svelte、Angular、React、Next.js、混在するマイクロフロントエンドで同じ状態・外観・動きの制御を公開します。

一つの契約、多くのホスト

フレームワーク別の統合はずれがちです。React にだけ機能が増え、Angular の既定値が異なり、通常の JavaScript 版が忘れられます。Orbz は一つのネイティブ実装を維持し、フレームワークを公開属性とプロパティに接続します。

すべてのホストで同じ語彙を使えます。

• 五つの状態：idle、listening、thinking、speaking、asleep
• 一つの preset 属性、または五つの独自色属性
• size、speed、paused、elevated、reduced-motion
• play()、pause()、restart() メソッド

六つのサンドボックスは意図的に同じ UI を示します。フレームワークのコードは異なっても、契約と利用体験は同じです。

任意の音声ポートを備えた視覚プリミティブ

Orbz は視覚表現を担当し、ブラウザーと OpenAI 互換の音声アダプターを備えた任意の会話フローを提供します。表現に意味を与える判断と安全上の境界はアプリが管理します。

• 音声の開始・停止と訪問者の同意操作
• マイク権限、音声収録、音声認識
• エンジン選択、保護された音声エンドポイント、認証情報
• モデル要求、ツール呼び出し、ストリーミング
• 発話順、キャンセル、エラー、再試行
• 文字起こし、ボタン、ラベル、その他の意味を伝える UI

この境界により、音声ベンダー、AI SDK、状態管理、バックエンドを自由に選べます。アプリがドメインイベントを五つの状態に変換し、必要な時だけ会話を開始して、Orbz が対応する姿を描画します。

実際の状態対応は音声アシスタントの構築を参照してください。

意図的に厳密な設計

対応範囲は意図的に属性中心です。Shadow DOM のパーツ、公開 CSS 変数、フレームワーク専用アダプターは公開しません。

厳密さには三つの目的があります。

1. 移植性。 同じ設定がどのホストでも同じ意味を持ちます。
2. 安定性。 内部レイヤーや動きを意図せず公開 API にせず進化させられます。
3. 一貫性。 チームは想定したトークンを変更し、セレクター単位でコンポーネントを置き換えません。

独自の見た目にはプリセットか文書化された五色を使います。異なる意味や操作が必要なら、オーブを囲むアプリで実装します。

分離は実装上の約束

各インスタンスは閉じた Shadow DOM を作ります。マークアップ、スタイル、アニメーションは非公開です。ページの CSS で書き換えられず、内部セレクターもページへ漏れません。

閉じていることはアクセシビリティがないことではありません。装飾的な内部画像は支援技術から隠し、ホストがアクセシブルなラベル、できれば近くの動的な状態テキストで現在の状態を伝えます。

サーバーで安全、ブラウザーでネイティブ

サーバー描画時にも、モジュール直下で HTMLElement サブクラスを評価せずインポートできます。登録は保護され冪等で、サーバーでは何もせず、ブラウザーでは未登録の時だけ orb-z を定義します。

これでサーバー描画のシェルと互換性を保ちながら、ブラウザー本来の実行方式を維持します。サーバーが要素を出力し、登録後にクライアントが拡張します。任意の react-types はラッパーやアダプターなしで JSX 型を追加します。

推奨パターンは SSR とハイドレーションを参照してください。

リポジトリも公開境界に従う

Orbz パッケージ、本サイト、Orbz Sandbox は独立したプロジェクトです。サンドボックスは npm の @neongate-ai/orbz@0.3.1 を使い、文書も例も隣接パッケージのワークスペースや非公開ソースを参照しません。

各サンドボックスは独立した Vercel プロジェクトとして配置でき、マイクロフロントエンドも同じパッケージを使えます。持続する境界は公開パッケージと <orb-z> 契約であり、共有リポジトリ構成ではありません。

新機能を判断する基準

公開範囲を広げる前に確認します。

• すべてのフレームワークに共通する視覚的な課題か
• 小さく直列化可能な属性か型付きプロパティで表せるか
• ネイティブ HTML とアダプターで決定的に動くか
• 閉じた厳密な境界を保てるか
• アプリがオーブの外でアクセシブルな意味を提供できるか

答えがいいえなら、機能はホスト側に置くのが適切でしょう。小さな契約は制約ではなく、一つのコンポーネントをどこでも一つのままに保つ仕組みです。