パッケージのエクスポート

Orbz は、純粋な API アクセス、環境を確認したうえでのブラウザー登録、単独のブラウザーバンドルを分離しています。どのフレームワークでも、ネイティブの <orb-z> 要素を描画します。

エントリーポイント一覧

インポート	公開するもの	副作用
`@neongate-ai/orbz`	ネイティブ要素、対話ランタイムの型、定数、プリセット、正規化ヘルパー、`orbzElementClassFactory()`、`defineOrbz()`	タグを登録しない
`@neongate-ai/orbz/browser`	ルートエントリーが公開するすべての内容	`defineOrbz()` を呼び出す
`@neongate-ai/orbz/react-types`	ネイティブの `<orb-z>` タグに対する任意の React JSX 型拡張	なし
`@neongate-ai/orbz/standalone`	ブラウザーエントリーを単独で使えるブラウザー用ビルド	`defineOrbz()` を呼び出す
`@neongate-ai/orbz/index.css`	閉じた Shadow Root に埋め込まれるものと同じソーススタイルシート	なし
`@neongate-ai/orbz/package.json`	公開パッケージのメタデータ	なし

ブラウザー用と standalone のエントリーポイントは、バンドラーが登録呼び出しを削除しないよう、パッケージのマニフェストで副作用ありと指定されています。

react-types には React コンポーネントやランタイムアダプターは含まれません。JSX で <orb-z> を認識する必要がある React または Next.js の TypeScript プロジェクトでのみインポートしてください。

ルートエントリー

明示的な登録と再利用可能なドメイン型には、ルートエントリーを使います。


import {
  DEFAULT_ORBZ_PRESET,
  defineOrbz,
  ORBZ_PRESETS,
  ORBZ_STATES,
  type OrbzElement,
  type OrbzPresetName,
  type OrbzState,
} from "@neongate-ai/orbz";
 
defineOrbz();
 
const nextState: OrbzState = "listening";
const preset: OrbzPresetName = DEFAULT_ORBZ_PRESET;
const colors = ORBZ_PRESETS[preset];
const orb = document.querySelector<OrbzElement>("orb-z");
 
if (orb) orb.state = nextState;

ルートモジュールをインポートするだけでは、orb-z は登録されません。ページでタグをカスタム要素として有効にする場合は、defineOrbz() を呼ぶか /browser をインポートしてください。

定数

エクスポート	意味
`ORBZ_TAG_NAME`	文字列 `"orb-z"`
`ORBZ_OBSERVED_ATTRIBUTES`	変更に反応するネイティブ属性名
`ORBZ_STATES`	対応するすべてのアシスタント状態
`ORBZ_REDUCED_MOTION_MODES`	`system`、`always`、`never`
`ORBZ_PRESET_NAMES`	`neongate` から始まる6つの正式なプリセット名
`ORBZ_PRESETS`	各正式プリセットの凍結された色の値。アカウント名に由来する非推奨の列挙不可エイリアスを保持
`ORBZ_COLOR_ATTRIBUTES`	色のキーからネイティブ属性名へのマップ
`ORBZ_COLOR_KEYS`	5つの色のキー
`DEFAULT_ORBZ_STATE`	`idle`
`DEFAULT_ORBZ_SIZE`	`16rem`
`DEFAULT_ORBZ_SPEED`	`1`
`DEFAULT_ORBZ_REDUCED_MOTION`	`system`
`DEFAULT_ORBZ_PRESET`	`neongate`。プリセットの命名を参照
`DEFAULT_ORBZ_COLORS`	Neongate プリセットの色
`config`	`config.ORBZ_STATES` を含むパッケージ定数を公開する凍結された名前空間
`talk`	互換性のための凍結された空オブジェクト（`{}`）。ステップはホストで定義
`DEFAULT_TALK_FLOW`	凍結された空配列（`[]`）。挨拶、人格、会話は組み込まれない

配列とプリセットのレコードを使えば、パッケージが受け入れる値をコピーせずに、検証済みのコントロールを生成できます。


import { DEFAULT_ORBZ_PRESET, ORBZ_PRESET_NAMES, ORBZ_STATES } from "@neongate-ai/orbz";
 
for (const state of ORBZ_STATES) {
  stateSelect.add(new Option(state, state));
}
 
for (const preset of ORBZ_PRESET_NAMES) {
  const label = preset === DEFAULT_ORBZ_PRESET ? "Neongate" : preset;
  presetSelect.add(new Option(label, preset));
}

型

エクスポート	構造
`OrbzState`	5つの状態名のユニオン型
`OrbzReducedMotion`	`"system" \| "always" \| "never"`
`OrbzPresetName`	6つの正式名と、アカウント名に由来する非推奨の入力エイリアスのユニオン型
`OrbzSize`	`number \| string`
`OrbzColors`	必須の文字列 `primary`、`secondary`、`accent`、`highlight`、`background`
`OrbzColorOverrides`	部分的な `OrbzColors`
`OrbzBaseOptions`	状態、サイズ、速度、一時停止、浮き上がりの影、動きを抑える設定
`OrbzPresetOptions`	プリセットモード。カスタム色のキーは `never`
`OrbzCustomColorOptions`	カスタム色モード。`preset` は `never`
`OrbzColorSelection`	プリセットモードとカスタム色モードのユニオン型
`OrbzOptions`	基本オプションと色選択のユニオン型を組み合わせたもの
`OrbzElement`	ネイティブ要素のプロパティと再生メソッド
`OrbzElementConstructor`	型付きのカスタム要素コンストラクター
`OrbzTalkStep`	決定的な、またはインテリジェンスによる型付き対話ステップ
`OrbzTalkContext`	対話ランナーが取得してメモリに保持する値
`OrbzVoiceOptions`	任意の音声エンジン、対話フロー、インテリジェンスの設定
`OrbzVoiceEnginePort`	実装者が提供する音声出力の契約
`OrbzIntelligencePort`	任意の非決定的な応答の契約
`WebSpeechAdapterOptions`	ロケール、優先する音声、速度、ピッチ、音量、音声の読み込み設定
`OpenAISpeechAdapterOptions`	安全なエンドポイントと OpenAI の音声モデル、音声、指示、形式の設定

音声アダプター

エクスポート	用途
`WebSpeechAdapter`	ロケールと音声を明示的に選択するブラウザーの音声合成
`OpenAISpeechAdapter`	実装者が管理する安全なエンドポイントを通じた OpenAI 品質の音声

OpenAISpeechAdapter の既定値は gpt-4o-mini-tts、marin、MP3 です。OpenAI API キーはエンドポイント側に保持し、ブラウザーのコードには一切含めません。

検証と正規化の関数

エクスポート	用途
`isOrbzState()`	対応する状態の型ガード
`isOrbzPresetName()`	正式名とアカウント名に由来する非推奨のエイリアスを受け入れる型ガード
`isOrbzReducedMotion()`	動きを抑える設定値の型ガード
`normalizeOrbzState()`	非対応の入力を `idle` に変換
`normalizeOrbzPreset()`	アカウント名に由来する非推奨の入力を `neongate` に正規化。非対応の入力は `DEFAULT_ORBZ_PRESET` に変換
`normalizeOrbzReducedMotion()`	非対応の入力を `system` に変換
`normalizeOrbzSize()`	数値をピクセルに変換。無効な数値や空の入力は `16rem` に変換
`normalizeOrbzSpeed()`	正でない値や有限でない値を `1` に変換
`mergeOrbzColors()`	有効で空でない上書き値を基本の配色に統合

信頼できない設定は、保存する前に正規化してください。


import {
  normalizeOrbzPreset,
  normalizeOrbzSpeed,
  normalizeOrbzState,
} from "@neongate-ai/orbz";
 
const config = {
  preset: normalizeOrbzPreset(payload.preset),
  speed: normalizeOrbzSpeed(payload.speed),
  state: normalizeOrbzState(payload.state),
};

登録ヘルパー

defineOrbz() は通常の明示的な登録 API です。SSR で安全に使用でき、冪等です。


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

orbzElementClassFactory() は、globalThis.HTMLElement が存在するときだけクラスを作成し、キャッシュします。高度な統合向けに公開されていますが、ほとんどのアプリケーションでは defineOrbz() を呼んでください。


import { orbzElementClassFactory } from '@neongate-ai/orbz'
 
const constructor = orbzElementClassFactory()
// undefined on a server; an OrbzElementConstructor in a browser

どちらのヘルパーも、DOM が利用できない環境では HTMLElement のサブクラスを評価しません。