変更履歴

このページでは、公開パッケージ @neongate-ai/orbz、カスタム要素 <orb-z> の契約、および対応する統合方法に関するユーザー向けの変更を記録します。

実装の正本は GitHub リポジトリ です。公開版は npm 、完全なドキュメントは orbz.site  で確認できます。

1.0.2 — 2026-09-08

Neongate プリセットの修正

• neongate を既定プリセットの正式名に戻しました。DEFAULT_ORBZ_PRESET、ORBZ_PRESET_NAMES、要素の正規化済みプリセット getter が対象です。Neongate の色は変わりません。
• 1.0.1 で誤って使われたアカウント由来の名前を、非推奨の入力別名として維持しました。既存の属性、プロパティ代入、型付き入力、ガードは引き続き受け付けます。正規化と属性への反映には neongate を使います。
• 非推奨のパレットキーを、ORBZ_PRESETS.neongate の不変かつ列挙不可の別名として維持しました。正式なプリセット一覧は引き続き6件です。
• 旧形式の簡略・完全設定オブジェクトを、呼び出し元の入力を変更せず正規化します。指定された色と厳密な検証を維持します。

1.0.1 からの更新

公開済みの修正版をインストールし、固定バージョンの CDN URL を更新してください。

npm install @neongate-ai/orbz@1.0.2

新しく明示するプリセットには neongate を使ってください。廃止されたアカウント由来のキーも互換性を維持するため、都合のよい時点で移行できます。正規化済みの名前を読むコードは neongate を想定してください。既定の例とパレット参照は Neongate プリセットの命名を参照してください。

この修正は、履歴として以下に残す 1.0.1 の命名案内に優先します。npm スコープは @neongate-ai/orbz のままです。保守対象のソースリポジトリは現在 jonatassales 配下にあります。

npm で 1.0.2 を表示 · v1.0.2 のソースタグを見る · タグ間のソースを比較 

1.0.1 — 2026-09-08

クリーンアップと簡略設定

• Orbz ソースの orb cleanup（別名 orb clean）を修正し、ルートと下位階層の未追跡 node_modules および生成物を既定で削除するようにしました。--dry-run は対象を表示し、--keep-dependencies は依存関係を保持します。追跡済み内容、ソース/アセット、ハーネスメタデータ、入れ子のリポジトリは保持し、ディレクトリのシンボリックリンクはたどりません。
• 手書きの設定 JSON を簡略化しました。変換処理は省略された内部の外観・動作・音声グループを型付き既定値で補い、実行時設定を検証、複製、凍結します。これらのグループの明示的な上書きは引き続き可能です。
• GitHub の所有者リンクを当時の個人アカウントに更新し、README、CLI ガイド、エンジニアリングチェックも更新しました。npm パッケージ名は @neongate-ai/orbz のままです。

1.0.0 からの更新

修正版をインストールし、固定バージョンの CDN URL を更新してください。

npm install @neongate-ai/orbz@1.0.1

この版では既定プリセットを一時的に個人アカウント名へ変更しましたが、従来の neongate の色は維持しました。1.0.2 で正式名を neongate に戻したため、新しい統合では <orb-z preset="neongate"></orb-z> を使ってください。ソースを保守する場合、node_modules を残すには orb cleanup --keep-dependencies を使います。orb cleanup だけでは削除されます。パッチリリースであっても、この移行事項は適用されます。

npm で 1.0.1 を表示 · タグ間のソースを比較 

1.0.0 — 2026-09-06

音声モデルと Realtime 会話

• web-speech、openai-speech、openai-realtime 用の型付き JavaScript プロパティ voiceModel を追加しました。プロバイダーの選択だけでは発話しません。ユーザー操作後、ホストが明示的に発話や会話を開始します。
• OpenAIRealtimeAdapter とブラウザーからプロバイダーへの直接 WebRTC 音声を追加しました。アプリケーションは独自エンドポイント、または SDP answer を返す非同期コールバックを使い、realtimeSession でセッション開始を認可します。
• startConversation()、stopConversation()、interruptConversation()、読み取り専用 conversationState、orbz-conversation-state-change と orbz-transcript を追加し、アプリ側の操作・文字起こし UI に対応しました。
• プロバイダーキーはアプリのバックエンドに保持します。モデル設定は公開情報だけを含み、エンドポイントオブジェクトは apiKey、token、headers などの未知のフィールドを拒否します。秘密情報やセッショントークンを HTML 属性、コンポーネントプロパティ、設定 JSON に入れないでください。

正式な設定と CLI

• フォークの保守者は src/orbz.config.json でコンポーネント、外観、動作、音声、Realtime の既定値を編集し、再ビルドします。インストール済みパッケージは同梱の既定値を使い、実行時に設定を取得しません。
• 読み取り専用 orbzConfiguration と純粋な transformOrbzConfiguration() を追加しました。パッケージのシングルトンを変更せず、完全な設定を検証、複製、変換、凍結できます。
• Orb CLI のコマンド処理とヘルプを統合しました。既存の公開エクスポート、視覚属性、ネイティブ登録、明示的な voiceEngine 統合は引き続き利用できます。

0.4.3 からの更新

公開版をインストールし、固定バージョンの CDN URL を更新してください。

npm install @neongate-ai/orbz@1.0.0

既存の視覚サンプルは同じ <orb-z> タグとブラウザー入口を使います。新しい構造化オプションは JavaScript プロパティで設定し、voice-model HTML 属性はありません。Realtime にはアプリ側のセッション認可と明示的な操作が必要です。更新だけでは音声を開始したりマイクを要求したりしません。明示的に設定した voiceEngine は voiceModel に優先します。

npm で 1.0.0 を表示

0.4.3 — 2026-09-04

0.3.1 以降の主な変更

• 公開 POSIX shell CLI orb をパッケージの実行ファイルとして追加しました。npx -y --package=@neongate-ai/orbz@latest orb で一時実行できます。
• Orb のセットアップはメタデータとロックファイルから npm、pnpm、Yarn、Bun を検出し、実行中の Orbz バージョンをインストールします。アプリソースは生成・上書きしません。
• WebSpeechAdapter の既定言語はブラジルポルトガル語（pt-BR）になりました。別の言語が必要なら en-US などで language を上書きできます。
• 定型の挨拶、ペルソナ、既定の会話フローは同梱されなくなりました。利用側が speech または talkFlow を渡し、voiceEngine を設定して startTalking() を明示的に呼びます。

npm で 0.4.3 を表示

0.3.1 — 2026-08-25

明示的な音声の有効化

• <orb-z> の接続やアップグレードだけでは既定エンジンや会話フローを開始しなくなりました。
• voiceEngine の既定値は undefined です。アプリが明示的にエンジンを指定し、訪問者の同意操作後に startTalking() を呼びます。
• エンジンの設定だけでは発話しません。stopTalking() は進行中のフローを停止し、undefined の代入はエンジン設定を解除します。
• HTML やサーバー描画マークアップの数値文字列を、数値プロパティと同様にピクセル長へ正規化します。

npm で 0.3.1 を表示

0.3.0 — 2026-08-23

React と Next.js の型定義

• React と Next.js の TypeScript プロジェクト用に、任意の @neongate-ai/orbz/react-types 入口を追加しました。
• JSX を拡張し、フレームワーク用ラッパーなしで <orb-z> の型を提供します。
• React は引き続き Orbz の実行時依存に含まれません。React 型は任意の宣言入口のビルドだけに使用します。

0.2.0 — 2026-08-22

Orbz 0.2.0 は、従来の視覚アシスタントを音声対応のフレームワーク非依存カスタム要素へ拡張します。会話ランタイム、交換可能な音声・知能ポート、厳密な外観制御、強化したカプセル化、全対応フレームワークで共通のネイティブ統合を導入しました。

1.0 前の破壊的変更を含むリリース： 0.1.0 の colors、公開 CSS 変数、Shadow Parts、開いた Shadow DOM、@neongate-ai/orbz/react を使うアプリは移行が必要です。

音声と会話ランタイム

• 初回の接続済み描画後に始まる、自動で決定的な会話フローを追加しました。
• 公開 talk オブジェクトと DEFAULT_TALK_FLOW に welcoming、askName、help、answer ステップを追加しました。
• 実行時だけの会話メモリーを追加しました。既定フローは訪問者の名前を talkContext で提供し、Cookie、ローカルストレージ、IndexedDB、バックエンドには書き込みません。
• 現在の実行コンテキストをリセットし、設定済みフローを再開する startTalking() を追加しました。
• アプリが自身の UI で受け取ったテキストで質問・回答ステップを続ける receive(input) を追加しました。
• 進行中のフローと音声を停止する stopTalking() を追加しました。
• 設定可能な voiceEngine、talkFlow、intelligence を追加しました。
• 公開 TypeScript 契約 OrbzTalkStep、OrbzTalkContext、OrbzVoiceOptions を追加しました。
• コンポーネントを変えずに音声出力を交換する OrbzVoiceEnginePort を追加しました。
• 製品ロジックや認証情報を Orbz 外部に保ったまま、エージェントや回答プロバイダーを接続する OrbzIntelligencePort を追加しました。
• 知能プロバイダーが未設定または失敗した場合のローカル代替応答を追加しました。
• { speaking: boolean } を持つ orbz-speaking-change を追加しました。
• 元のエラーを { error: unknown } に含む orbz-talk-error を追加しました。
• 音声再生中は一時的に speaking 状態となり、終了後に以前の視覚状態へ戻ります。
• マイク収録、音声認識、権限、文字起こし、テキスト入力の責任はホストアプリに残します。Orbz は receive() に渡されたテキストだけを受け取ります。

ブラウザー音声

• 設定不要の既定エンジンとして WebSpeechAdapter を追加しました。
• 既定の音声言語を en-US に変更しました。
• 非同期の音声一覧が読み込まれてから音声を選びます。
• 無関係な OS 既定音声を使う代わりに、明示的な英語フィルターを追加しました。
• 設定済みの優先音声と、ブラウザーが提供する高品質な Google、Microsoft、自然、ニューラル、プレミアム、拡張、オンライン音声の選択を追加しました。
• 言語、優先音声、速度、ピッチ、音量、音声読み込みタイムアウトを設定できます。
• 発話開始の失敗を検出し、フローが無期限に待機しないようにしました。
• 自動音声が NotAllowedError で拒否された場合、初回描画の音声を最初のポインター・キーボード・タッチ操作後に自動再試行します。
• 発話前にすべてリセットで要素を再マウントする必要があったサンプルの動作を削除しました。
• 音声は訪問者のブラウザーと OS が提供することを明確にしました。選択を改善しても、システム音声が OpenAI 生成音声になるわけではありません。

OpenAI 音声

• アプリ経由で OpenAI の読み上げを使う OpenAISpeechAdapter を追加しました。
• 既定で gpt-4o-mini-tts、marin、MP3 出力、自然な米国英語の指示を使用します。
• モデル、音声、応答形式、指示、認証情報、ヘッダー、fetch 実装を設定できます。
• 旧 tts-1 と tts-1-hd に対応し、互換の既定音声と非対応指示の省略を追加しました。
• OpenAI API キーはブラウザーと Orbz パッケージ外に保持します。アダプターは実装者のエンドポイントから生成音声を取得します。
• 出力停止・置換時に保留中の音声要求をキャンセルします。
• 再生、キャンセル、失敗後に生成音声のオブジェクト URL を解放します。
• ブラウザーのアクティベーションエラーを処理し、生成音声もブラウザー音声と同じ初回操作での再試行に参加します。

外観とコンポーネント API

• 自由な colors プロパティを、厳密で排他的な2つの外観モードに置き換えました。

  • preset 属性またはプロパティ。
  • color-primary、color-secondary、color-accent、color-highlight、color-background の5属性。

• neongate、periwinkle、magenta、peach、mocha、ivory の6プリセットを追加しました。

• プリセットと独自色は排他的です。両方を指定すると競合を通知し、プリセットを適用して、その属性を削除するまで独自色を無視します。

• 任意の中央影を付ける真偽値属性・プロパティ elevated を追加しました。

• idle、listening、thinking、speaking、asleep の公開状態を維持しました。

• 正の速度倍率、サイズ正規化、停止・再生、アニメーション再開、system・always・never の動きを抑える方針を維持しました。

• 状態、プリセット、動きの抑制、サイズ、速度、色の公開定数・ガード・正規化関数を維持しました。

• Shadow DOM を開いた状態から閉じた状態へ変更しました。

• 公開 Shadow Parts と外部 ::part(...) スタイルを削除しました。

• 公開 --orbz-* CSS 変数による変更を削除しました。内部セレクターと変数は私的な実装詳細です。

• ソーススタイルを src/element/index.css に移し、閉じた shadow root に保持して、同じ内容を dist/index.css に出力します。

フレームワーク統合とパッケージ入口

• 専用 React コンポーネントと @neongate-ai/orbz/react 入口を削除しました。
• 実行時パッケージの peer dependency と開発依存から React を削除しました。
• 全フレームワークでリテラルの <orb-z> を使用するよう統一しました。
• React と Next.js はブラウザー入口を登録して <orb-z> を直接描画します。
• ラッパーを導入せずに TypeScript に認識させるため、React と Next.js サンプルにローカル JSX intrinsic-element 宣言を追加しました。
• @neongate-ai/orbz は型、定数、アダプター、ポート、ファクトリー、明示的登録ヘルパーの副作用なし入口として維持しました。
• @neongate-ai/orbz/browser は <orb-z> を登録する入口として維持しました。
• @neongate-ai/orbz/standalone は CDN や直接スクリプト向けの自己登録する独立バンドルとして維持しました。
• SSR 環境での要素クラス生成・登録のガードを維持しました。
• 複数バンドルやマイクロフロントエンドによる登録時も defineOrbz() は冪等です。
• 高度な要素クラス生成関数を orbzElementClassFactory() に改名しました。
• 登録の副作用をパッケージルートから明示的ブラウザー入口へ移しました。

ビルド、配布、内部構成

• npm pack や npm publish 前に厳密な TypeScript 検証と新規ビルドを行う prepack を追加しました。
• npm 内容を dist 生成物と、自動で含まれる package.json、README.md、LICENSE などに限定しました。
• 文書、サンプル、内部エージェント指示、ソース、ワークスペース設定は npm tarball に含めません。
• 共有 tsdown 設定の import に .ts を明記し、Node のネイティブ TypeScript 設定読み込みに対応しました。
• 内部モジュールを core、element、factories、ports、services、talk に整理しました。
• 従来の voice 領域を talk に改名しました。
• 関連する型宣言を .types.ts に統合しました。
• 公開 Orbz* 名は維持し、内部ファイル名の冗長な orbz 接頭辞を削除しました。
• 不要な単一ファイルのディレクトリを平坦化しました。
• React ランタイム実装をパッケージソースから完全に削除しました。

サンプルとドキュメント

• 共通の <orb-z> UI に基づく Vanilla、React、Vue、Svelte、Angular、Next.js の同期サンプルを追加しました。
• 再マウントせずに状態を戻すリセット操作へ更新しました。
• 元の VitePress 構成を Nextra 文書サイトへ置き換えました。
• ネイティブ、フレームワーク、CDN 統合の入門を追加しました。
• 設計思想、状態、外観、動作、アクセシビリティの概念説明を追加しました。
• フレームワーク、マイクロフロントエンド、SSR、音声アシスタントのガイドを追加しました。
• 要素とパッケージエクスポートの完全な API リファレンスを追加しました。
• サンプル、トラブルシューティング、移行案内を追加しました。
• orbz.site  を主な文書公開先に定めました。
• フレームワーク別サブドメインを同期サンプルの配備先に定めました。

npm で 0.2.0 を表示

0.1.0 からの移行

React アダプターを置き換える

従来の React 入口からの import を削除します。

import { Orbz } from "@neongate-ai/orbz/react";
 
export function Assistant() {
  return <Orbz state="idle" />;
}

代わりにブラウザー入口を登録し、ネイティブカスタム要素を描画します。

import "@neongate-ai/orbz/browser";
 
export function Assistant() {
  return <orb-z state="idle"></orb-z>;
}

TypeScript が orb-z を認識しない場合は、ローカル JSX intrinsic-element 宣言を追加します。これはコンパイル時の型情報のみを提供し、React コンポーネントを生成しません。

色の API を置き換える

従来の colors オブジェクトを削除します。

orb.colors = {
  primary: "#7C3AED",
  secondary: "#22D3EE"
};

組み込みプリセットを使います。

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

または preset を指定せず、対応する5つの色属性を使います。

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

プリセットを意図的に優先する場合を除き、明示的プリセットと独自色を併用しないでください。

外部からの Shadow DOM 変更を削除する

次に依存する統合を削除します。

• element.shadowRoot。
• 内部セレクター。
• ::part(...)。
• 公開 --orbz-* CSS 変数。
• 内部 DOM 構造への仮定。

代わりに、文書化された属性、プロパティ、メソッド、ポート、アダプター、イベント、エクスポートを使います。

カスタム要素を明示的に登録する

現在のモジュールで <orb-z> を登録する場合はブラウザー入口を使います。

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

ブラウザーの副作用なしに型やツールを import する場合はパッケージルートを使います。

import {
  defineOrbz,
  type OrbzElement
} from "@neongate-ai/orbz";

登録をホストアプリ側で管理する場合は defineOrbz() を明示的に呼びます。

音声を明示的に有効にする

0.2.0 と 0.3.0 は初回の接続済み描画後に会話を予約しました。0.3.1 でこの動作を削除しました。現在は voiceEngine、talkFlow、intelligence を設定し、訪問者の操作後に startTalking() を明示的に呼びます。

import '@neongate-ai/orbz/browser'
import {
  OpenAISpeechAdapter,
  type OrbzElement
} from "@neongate-ai/orbz";
 
const orb = document.createElement("orb-z") as OrbzElement;
 
orb.voiceEngine = new OpenAISpeechAdapter({
  endpoint: "/api/orbz/speech"
});
 
document.body.append(orb);
 
const startVoiceButton = document.querySelector<HTMLButtonElement>("[data-start-voice]");
 
startVoiceButton?.addEventListener("click", async () => {
  await orb.startTalking();
});

明示的な操作でもブラウザーが音声を拒否した場合、Orbz は次の操作時にその要求済みフローを再試行します。

0.1.0 — 最初の公開リリース

• 最初の @neongate-ai/orbz を npm に公開しました。
• Web Components 製のフレームワーク非依存 AI 音声ビジュアルとして Orbz を確立しました。
• idle、listening、thinking、speaking、asleep の5状態を提供しました。
• サイズ、速度、停止・再生、アニメーション再開、動きを抑える設定を提供しました。
• SSR に安全なカスタム要素作成・登録を追加しました。
• ブラウザー登録入口と独立バンドルを追加しました。
• 初期 React アダプターを追加しました。
• JavaScript の colors で色の上書きを公開しました。
• --orbz-* CSS 変数を公開しました。
• 開いた Shadow DOM と名前付き Shadow Parts で外部カスタマイズに対応しました。

npm で 0.1.0 を表示

バージョン管理方針

文書化された属性、プロパティ、メソッド、イベント、ポート、アダプター、型、定数、パッケージエクスポートは公開 API です。

Orbz 1.0.0 以降：

• 非互換の公開 API 変更はメジャーバージョンを上げます。
• 後方互換の機能追加はマイナーバージョンを上げます。
• 後方互換の修正はパッチバージョンを上げます。

サンプル、文書、配備設定、内部ソース構成は、新たな公開実行時契約を作らずに変更される場合があります。公開パッケージを説明・実演しますが、明示的にエクスポートするか文書化されたコンポーネント契約に含めない限り、npm API の一部にはなりません。