マイクロフロントエンドでの Orbz

Web Component は、実行時の契約が特定のフレームワークではなくブラウザーに属するため、マイクロフロントエンドの境界に適しています。Orbz は Vue のリモートで表示し、Angular のシェルで更新し、後から React の画面に置き換えても、タグや属性を変更する必要がありません。

Orbz は意図的に末端の視覚コンポーネントとして設計されており、ルーティングシステムや完全なマイクロフロントエンド基盤の役割は持ちません。ナビゲーション、データ、認証情報、デプロイには既存の構成方式を使ってください。orb-z は、それらのシステムの画面で共通のアシスタントの存在を表現するために使います。

共通の契約

最も長く維持しやすい連携は、Web プラットフォームのマークアップを使う方法です。


<orb-z
  state="idle"
  size="18rem"
  reduced-motion="system"
></orb-z>

ドメインの状態が変わると、シェルまたはリモートが公開プロパティを更新します。


import type { OrbzElement, OrbzState } from "@neongate-ai/orbz";
 
export function renderAssistantState(state: OrbzState) {
  const orb = document.querySelector<OrbzElement>("orb-z");
  if (orb) orb.state = state;
}

フレームワークのオブジェクトは境界を越えません。契約を構成するのは文字列、数値、真偽値属性、そして三つのメソッドです。

要素を登録する担当を決める

実用的な方式は三つあります。

1. シェルが Orbz を登録する

アプリケーションシェルがブラウザー用エントリーを一度だけインポートします。


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

リモートは <orb-z> を表示するだけです。パッケージコードの重複を抑え、バージョン管理の責任を明確にシェルへ集約できます。シェルがすでに全体の基本デザイン要素を管理している場合、最も分かりやすい標準の選択肢です。

2. 各リモートが同じ固定バージョンをインポートする

各リモートは Orbz を独立した依存関係として持ち、インポートできます。登録は冪等なので、後からインポートしても orb-z を再定義せず、既存の定義を使用します。

デプロイ間でパッケージの厳密なバージョンを統一してください。Custom Elements レジストリは定義済みのタグを置き換えられず、ページで最初に登録されたバージョンが使われます。そのため、登録自体がエラーにならなくても、バージョンの不一致によって動作がリモートの読み込み順序に左右されることがあります。

Module Federation、import map、その他の実行時共有機構により、パッケージのインスタンスを一つにできます。重複する転送量を減らせますが、これは最適化であり、Orbz の必須条件ではありません。ツールでパッケージをシングルトンに設定している場合でも、バージョンのルールを明確にしてください。

責任の所在を明確にする

各責務を一つの担当に割り当てます。

責務	推奨する担当
`orb-z` の登録	シェル、または連携して管理する共有依存関係
音声セッションとモデル呼び出し	アシスタント機能またはプラットフォームサービス
ドメイン状態から Orbz 状態への変換	セッションを管理する機能
オーブのサイズとプリセット	レイアウトとブランドの文脈を管理する画面
状態テキストと操作部品	表示を担当するリモート
Orbz のアニメーションと内部スタイル	Orbz 自体

複数のリモートが同じ要素に書き込む構成は避けてください。共有サービスがアシスタントのドメイン状態を公開することはできますが、その状態を変換して適用するのは、オーブを表示するリモートだけにします。

DOM 操作の指示ではなくドメイン状態を伝える

「オーブを紫にする」「三つ目のレイヤーを停止する」といった命令を公開する契約は脆弱です。表示の詳細がプラットフォームのバスに漏れ出してしまいます。

より堅牢な契約では、意味のあるアプリケーション状態を公開します。


type AssistantStatus =
  | { phase: "ready" }
  | { phase: "capturing" }
  | { phase: "processing" }
  | { phase: "playing" }
  | { phase: "offline" }
  | { phase: "error"; message: string };

表示を担当するリモートが capturing を listening に、processing を thinking に変換します。エラーは説明のないアニメーションで表すのではなく、実際のテキストと操作として提示します。

独立したデプロイ

リポジトリ構成とデプロイ構成は別々に選べます。共有リポジトリでローカルの起動管理を便利にしながら、各サンプルやマイクロフロントエンドを独立した Vercel プロジェクトとして維持できます。逆に、無関係なリポジトリ同士でも、同じ npm バージョンを使って同一のオーブを表示できます。

独立してデプロイする画面では、次の手順を取ります。

そのアプリケーション自身の依存関係に @neongate-ai/orbz を追加する。
使用可能なバージョンを固定するか、一元管理する。
アプリケーションのクライアントエントリーから /browser をインポートする。
アプリケーションの既存データ契約を通じてアシスタントの状態を公開する。
Orbz のソースや別のサンプルアプリケーションをインポートせずにデプロイする。

Vanilla 、React 、Vue 、Svelte 、Angular 、Next.js の公開サンプルは、同じコンポーネントのインターフェースを使う六つの独立したホストを示しています。

障害時とフォールバックの動作

登録前の未知のカスタム要素は、有効な、動作を持たない HTML として残ります。これは段階的な機能追加に役立つ境界です。コンポーネントのバンドルを読み込んでいる間も、周囲のラベルや操作部品を表示できます。

アニメーションがなくてもアシスタントの状態が伝わるよう、ホストを設計してください。


<div role="status" aria-live="polite">
  <orb-z state="thinking"></orb-z>
  <span>Assistant is preparing a response</span>
</div>

リモートの読み込みに失敗しても、テキストは状態を伝え続けます。Orbz が後から登録されると、既存の要素がその場でアップグレードされます。

マイクロフロントエンドの確認項目

npm パッケージを境界とし、別のアプリケーションの src/ をインポートしない。
同時に読み込むリモート間で Orbz の厳密なバージョンを統一する。
可能であれば、決まった一か所で登録する。
表示された各オーブへの書き込み担当を一つにする。
アプリケーションバスには内部の表示詳細ではなくドメイン状態を公開する。
状態テキストと操作部品は閉じた Shadow DOM の外に置く。
動きの軽減と JavaScript の遅延読み込みを有効にしてホストの更新をテストする。
タグ名と文書化された属性を、安定した連携 API として扱う。