ネイティブ Web コンポーネント

ネイティブの <orb-z> 要素は Orbz の基盤です。通常の JavaScript でもフレームワークでも、カスタム要素に対応する環境で動作します。

自動登録

アプリケーションのコードでブラウザーエントリーを一度インポートします。

main.ts


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

モジュールが defineOrbz() を呼び出します。登録処理には保護があり、サーバーでは何もせず、ページの別の部分で orb-z が登録済みなら既存のコンストラクターを返します。

タグはモジュール読み込みの前後どちらでも描画できます。カスタム要素が定義されると、ブラウザーが既存のタグをアップグレードします。


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

要素の接続やアップグレードで音声は始まりません。ホストが音声エンジンを設定し、訪問者の同意操作で startTalking() を呼び出す必要があります。

明示的な登録

登録のタイミングを厳密に選ぶにはルートエントリーを使います。


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

defineOrbz() はブラウザーで要素のコンストラクターを返し、customElements または HTMLElement が使えない場合は undefined を返します。繰り返し呼んでも安全です。

属性で制御する


<orb-z
  state="thinking"
  size="320px"
  speed="1.15"
  preset="periwinkle"
  reduced-motion="system"
  elevated
></orb-z>

要素は変更を監視するため、属性の更新が直ちに表示へ反映されます。


const orb = document.querySelector("orb-z");
 
orb?.setAttribute("state", "speaking");
orb?.setAttribute("speed", "1.25");
orb?.toggleAttribute("elevated", true);

プロパティで制御する

JavaScript で状態を変える場合は、プロパティの方が明確なことが多くあります。


import type { OrbzElement } from "@neongate-ai/orbz";
 
const orb = document.querySelector<OrbzElement>("orb-z");
 
if (orb) {
  orb.state = "listening";
  orb.size = 300; // normalized to "300px"
  orb.speed = 1.2;
  orb.reducedMotion = "system";
  orb.elevated = true;
}

各公開プロパティは対応する属性に反映されます。size はピクセルになる数値か、"20rem" などの CSS 長さ文字列を受け取ります。

音声エンジンと会話フローは JavaScript 専用プロパティです。フローを準備して要素を追加し、明示的なユーザー操作の後にのみエンジンを設定して音声を開始します。


import "@neongate-ai/orbz/browser";
import { WebSpeechAdapter, type OrbzElement, type OrbzTalkStep } from "@neongate-ai/orbz";
 
const flow = [
  { id: "welcome", kind: "say", needsAuth: false, text: "Hello." },
  { id: "name", kind: "ask", needsAuth: false, text: "What is your name?", capture: "fullName" },
  { id: "help", kind: "say", needsAuth: false, text: "How can I help, {{fullName}}?" },
  { id: "answer", kind: "respond", needsAuth: false, strategy: "openai", fallback: "I cannot answer that right now." }
] as const satisfies readonly OrbzTalkStep[];
 
const orb = document.createElement("orb-z") as OrbzElement;
orb.talkFlow = flow;
orb.voiceEngine = new WebSpeechAdapter({ language: "en-US" });
document.body.append(orb);
 
const startVoiceButton = document.querySelector<HTMLButtonElement>("[data-start-voice]");
startVoiceButton?.addEventListener("click", async () => {
  await orb.startTalking();
});

真偽値属性

paused と elevated は HTML 標準の真偽値属性です。設定した文字列にかかわらず、属性が存在すれば真になります。


<!-- Elevated -->
<orb-z elevated></orb-z>
 
<!-- Also elevated: "false" is still a present attribute -->
<orb-z elevated="false"></orb-z>

属性を削除するか、プロパティに false を設定します。


orb?.removeAttribute("elevated");
 
if (orb) {
  orb.paused = false;
  orb.elevated = false;
}

組み込みプリセットと独自パレット

preset 属性で組み込み配色を選びます。


<orb-z preset="magenta"></orb-z>

既定の外観は Neongate です。preset を省略すると、バージョンをまたいで既定の外観を選べます。他に periwinkle、magenta、peach、mocha、ivory があります。名前とバージョン互換性を参照してください。

独自パレットでは preset を省略し、五つの色属性のいずれかを設定します。


<orb-z
  color-primary="#7C3AED"
  color-secondary="#22D3EE"
  color-accent="#F472B6"
  color-highlight="#FDE68A"
  color-background="#09090B"
></orb-z>

未指定の色は Neongate の既定値になります。明示的な preset と color-* を併用しないでください。両方あるとプリセットが優先され、Orbz がコンソールに競合を報告します。

アプリケーションの状態機械で駆動する

アプリを状態の正本とし、Orbz にその状態を反映させます。


import type { OrbzElement, OrbzState } from "@neongate-ai/orbz";
 
const orb = document.querySelector<OrbzElement>("orb-z");
 
function presentAssistantState(state: OrbzState, message: string) {
  if (orb) orb.state = state;
 
  const status = document.querySelector<HTMLElement>("[data-assistant-status]");
  if (status) status.textContent = message;
}
 
presentAssistantState("thinking", "Assistant is preparing a response");

対応する状態は idle、listening、thinking、speaking、asleep の五つです。不明な値は idle に正規化されます。

再生メソッド

ネイティブ要素は、アニメーション用の三つのメソッドを公開します。


orb?.pause();   // freeze the current animation
orb?.play();    // resume it
orb?.restart(); // rebuild the current state's animation

宣言的に指定するには paused プロパティと属性を使います。命令的なブラウザー統合が便利な場合はメソッドを使ってください。

モーション設定

reduced-motion="system" は prefers-reduced-motion の設定と変更に追従します。always で動きの少ない表示、never で通常の動きを強制します。


<div role="status" aria-live="polite">
  <orb-z state="thinking" reduced-motion="system"></orb-z>
  <span data-assistant-status>Assistant is thinking</span>
</div>

意味のあるテキストはオーブの外に置きます。これは視覚的な合図であり、アシスタントの状態を知る唯一の手段にしてはいけません。

フレームワークのテンプレート

Vue、Svelte、Angular は /browser を一度インポートした後、リアクティブな値を直接タグへバインドできます。アプリと Orbz の間にフレームワークアダプターや共有ランタイムはありません。

完全なアプリはサンドボックスワークスペースで確認できます。