sillytavern-embedded-ui

SillyTavern 埋め込み UI

共通コミュニケーション

TW の平易な表現とガイダンスのルールを適用します。用語は初出時に説明し、ユーザーが選択した新人／入门／熟练／老手のレベルを保ち、どのレベルでも必要な変更やバグについて説明します。ソウルモードや文章モードによって、この基本方針が無効になることはありません。

プラグインの実行環境

このスキルがプラグイン、クラウドホスト、またはリモートマシンを通じて実行される場合は、実行開始時にプラグイン実行契約を読み、ホスト固有のコマンドを実行する前に、ホスト、ツール、永続化に関する確認事項を適用します。このスキルの範囲、認可、受け入れ基準を維持してください。

埋め込みインターフェースを設計または変更する前に、sillytavern-embedded-uiルートを指定して$consult-tavernweave-libraryを使用します。A0、該当する最小限の UI／モバイルガイド、選択したデザイン／モーションのリファレンスを読みます。選択した項目は、プロジェクトの権限者が採用するまで、すべてproposedのままです。

共通のフロントエンドデザイン品質基準を、デフォルトのデザイン要件として適用します。関連するウェブデザインを積極的に探して確認し、作者の意図に基づいた個性的な解決策を考案し、レイアウトを視覚的に表現します。目指すのはAwwwards級の品質です。整った構成と役立つ文言は必須であり、ギャラリー向けの参考例として任意に取り入れるものではありません。作者の言語と実際の機能ラベルを維持しつつ、装飾的なマイクロコピーや重複する英語のキャプションは避けます。完全なワークフローと証拠の範囲については、共通リファレンスを参照してください。

ロールカードの実際のライフサイクルに合う、保守可能な最小限のインターフェースを構築します。ポータブルな基本構成として、セマンティック HTML、CSS、JavaScriptを使用します。既存のプロジェクトですでにフレームワークが使われている場合、またはインタラクションの複雑さから明確に必要な場合に限り、フレームワークを採用します。

作者に技術的な質問票への回答を求めるのではなく、自ら提案を作成します。一貫したデザイン案が1つあれば十分です。選択肢を作り出したり、承認済みの決定を再び問い直したりしないでください。認可された作業を続行し、未解決の重要な選択についてのみ確認を求めます。任意のワークシートにはエージェントの作業を記録しますが、同等のプロジェクト記録で代用できます。

実装範囲を守る

このスキルの対象は、埋め込み UI の設計、ソースコードの実装またはレビュー、補助的な検証、およびランタイムテストに引き継ぐ受け入れ基準です。このスキルでは、稼働中のSillyTavernセッションを操作したり、ランタイムでの受け入れを主張したりしないでください。

対象のランタイムで動作を再現または受け入れる必要がある場合は、ビルド済みの正確な成果物と関連するチェックリストをsillytavern-runtime-debugに引き継ぎます。そのランタイム検証で UI ソースの不具合が見つかった場合は、ここで実装を再開し、新しい成果物のリビジョンをビルドして、ランタイム受け入れを完了するために返します。

サーフェスを特定する

コンポーネントを設計する前に、サーフェスを選択します。

サーフェス	主な役割	ライフサイクル
メッセージコンテンツページ	手紙、日記、フォーラムなど、メッセージから生成されたコンテンツを表示します	対象のメッセージとそのレンダリングのライフサイクルに従います
オープニングページ	挨拶、またはサポートの開始に関する選択やセットアップを表示します	挨拶に従います。セットアップウィザードは、コミットが正常に完了すると終了します
ステータスバー／HUD	メッセージの近くに、頻繁に確認するゲームの状態を表示します	メッセージ／ランタイムのライフサイクルに合わせて再作成または更新されます
コントロールセンター	設定、パッケージ、ワールドデータ、高度な操作を管理します	通常は長期間存続し、シングルトンです
ポップアップ／ドロワー／モーダル	周囲の状態を失わずに、1つの詳細や判断に集中できるようにします	一時的で、明示的な開閉動作があります

少数の別パターンの挨拶をアプリケーションにしたり、ステータスバーにコントロールセンターのワークフローを担わせたりしないでください。

メッセージから生成されるページについては、メッセージコンテンツページを読み、必要に応じて任意のワークシートを使用してください。MVU の読み取り専用表示については、MVU ステータスバー設計と任意のワークシートを読んでください。それぞれの分岐は品質基準を共有しますが、コンテンツの管理元は分けておきます。複合サーフェスでは、表示する各情報の出典を明示します。新しいカードの種類や状態システムが必ず必要になるわけではありません。

設計前に確認する

既存の HTML、CSS、JavaScript、データスキーマ、正規表現／マウント経路、ランタイムの所有関係を確認します。次の点を記録してください。

• UI のレンダリング場所：メッセージ本文、Tavern Helper のフレーム、ネストされたフレーム、ホストドキュメントのいずれか
• 信頼できるコードの境界と、信頼できないユーザー／モデル／リモートの値すべて
• 状態の出典とスコープ：ドラフト、ローカル UI 設定、チャット、メッセージフロア、ワールドブック、MVU の stat_data のいずれか
• DOM を再作成するライフサイクルイベント
• 再利用する価値のある既存のデザイントークン、セレクター、コンポーネントパターン
• UI が対応する必要のある、最小サイズのデスクトップおよびモバイルのコンテナー

色や装飾を磨き込む前に、構造と状態の流れを確認してください。

状態の所有関係を明確にする

次の関心事を分けます。

data state       persisted game or configuration data
draft state      reversible, unconfirmed user input
UI state         active tab, open panel, focus, scroll, and transient errors
derived view     formatted values, counts, progress, and summaries

タブ、アコーディオン、スクロール位置がゲームプレイの一部として意図されていない限り、これらをワールドブックや MVU に永続化しないでください。ドラフトを編集するたびに正式なゲーム変数を書き込まないでください。実用上可能な場合は、データ更新後もユーザーが操作した表示状態を維持してください。

プレビュー、検証、最終送信に表示するコンテンツには、同じビルダーを使用してください。乖離する可能性のあるテンプレートを並行して作成しないでください。

構造とスタイル

• 意味に合ったコントロールを使用します。対応している場合は、実際の button、input、select、textarea、見出し、リスト、ダイアログを使用してください。
• ID、ストレージキー、カスタムイベント、CSS 変数、クラスには、カードまたは機能ごとの名前空間を付けます。
• JavaScript のバインディングには、安定した data-* 属性を使用します。装飾用クラスはスタイル指定として扱い、ビジネスプロトコルにはしないでください。
• 背景、テキスト、境界線、アクセント、間隔、角丸、文字サイズの段階には、小規模なトークンレイヤーを使用することを優先してください。
• box-sizing: border-box と、縮小する flex／grid 子要素の min-width: 0 を使用し、内部スクロール領域の挙動を予測可能にします。
• repeat(auto-fit, minmax(...)) のような可変グリッド、折り返し可能なコントロール、min()／max()／clamp() による制約を使用します。
• 狭いメッセージコンテナーからはみ出す固定幅を避けます。モバイルでは、高さの指定方法を 100vh だけに頼らないでください。
• iframe 内では、ホストウィンドウではなく、iframe またはコンポーネントのコンテナーを基準に考えます。有効な幅が不明確な場合は、コンテナーの寸法を使用してください。
• 運用サーフェスは、密度を保ちつつ整理された状態にします。ヒーローサイズのタイポグラフィと華やかな演出は、実際のオープニング場面に限って使用してください。
• カードの境界線を入れ子にしたり、過剰なぼかしを使用したりしないでください。backdrop-filter を使用する場合は、ぼかしを使わない代替表示も用意してください。

防御的なデータ描画

ユーザー、モデル、パッケージ、リモートのコンテンツはすべて信頼できないものとして扱います。

• テキスト値には、textContent と DOM の構築を優先して使用します。
• HTML が本当に必要な場合は、挿入前に信頼できるランタイムサニタイザーでサニタイズし、その後サニタイズ済みの文字列を変更しないでください。
• HTML 属性に埋め込むすべての値をエスケープします。URL のプロトコルとオリジンを検証します。
• モデルの出力を innerHTML で挿入しないでください。
• 想定外の null、配列、オブジェクト、長い文字列、欠落フィールド、不明な列挙値を正規化します。
• 進捗値とサイズを上限内に収め、フォールバックのラベルと色を用意します。
• 長い CJK テキストや改行されないテキストは、意図したとおりに折り返す、折りたたむ、またはスクロールできるようにします。
• 不正なデータやサポート対象外のデータは、黙って非表示にせず、診断状態として表示します。

リモート UI には、宣言的な HTML と信頼できるローカルバインダーを優先して使用します。HTTPS または信頼できるローカルソース、タイムアウト、サイズ制限、整合性またはリリースのピン留め、プロトコルバージョン、必須ノードの検証、サニタイズを強制します。別途レビュー済みの設計で必要とされる場合を除き、リモートスクリプト、入れ子のフレーム、ベース URL の変更、自動フォームは拒否します。

ライフサイクルと統合

• DOMContentLoaded だけに頼らず、ランタイムで実際に使われる準備完了の経路を通じて初期化します。
• バインドを冪等にします。互換性のある既存インスタンスは再利用し、互換性のないインスタンスは置き換える前に破棄します。
• イベントの解除処理、オブザーバー、タイマー、fetch の中断コントローラー、一時的な DOM、body のスクロールロック、共有グローバルを対象とする、単一のクリーンアップ経路を維持します。
• 親ドキュメントへのアクセス可否を確認し、フレーム間アクセスを try/catch で囲みます。
• MVU などのオプションの統合機能を使う場合は、そのイベントやデータを読み取る前に準備が整うまで待ちます。
• 対象となるメッセージの開始位置または永続化スコープを明示的に読み取ります。
• イベント駆動の更新をデバウンスし、並行するレンダリングを防ぎます。
• 動的リストにはイベント委譲を優先します。モジュールスコープの関数に依存するインラインハンドラーは避けます。
• 無関係なユーザーデータを保持し、書き込み後に再読み込みします。

SillyTavern は、静的なメッセージ HTML 内のクラスに名前空間を付与する場合があります。後から追加される動的 DOM には、同じ変換が適用されないことがあります。実際のランタイムで生のクラス名トークンと算出スタイルを検証し、オフラインプレビューだけから正しいと判断しないでください。

実装中はリアルタイムコンパイルを使用する

ユーザーがリアルタイム編集を求めた場合は、ソースの実装をここに置き、sillytavern-card-pipeline を使って、対象プロジェクトに既存のウォッチャーがあるかを確認し、実行します。共通の watch コマンド、ポート、ローカルサーバー、出力の対応関係を作り出さないでください。

編集前に、保守対象のソース、カードが読み込む正確な開発用出力、現在のビルド成功を示すマーカーを記録します。編集のたびに、次の手順を実施します。

1. ビルドが成功するまで待機し、コンパイラーエラーが発生したら停止します。
2. 新しい出力の識別情報を sillytavern-runtime-debug に渡します。
3. Tavern Helper が対象のメッセージまたはスクリプトの iframe を再読み込みしたことを確認します。ライブリスニングが利用できない場合は、プロジェクトで宣言された手動の更新／再バインドの代替手順を使います。
4. 続行する前に、結果の DOM、コンソール、インタラクション、データ状態を確認します。

リスナーが接続されていても、最新のソースがコンパイルされたとは限りません。また、ウォッチビルドが成功しても、SillyTavern がそれを読み込んだとは限りません。どちらの確認記録も残してください。ライブのフィードバックループで実装のフィードバック時間を短縮した後、本番ビルドを実行し、その正確な成果物を最終ランタイム受け入れ確認に渡します。

パッケージ化前の任意のフロントエンド・サンドボックス

作成者が埋め込み UI を仕上げたい場合は、特にパッケージ化前に、任意の作業ループとしてローカルのフロントエンド・サンドボックスを提案してください。変更が容易な段階で、レイアウト、操作、状態、モジュール間の問題を明らかにできます。作成者は利用を見送ることもできます。見送ってもゲートの不合格にはならず、通常のビルドや実ランタイムでの手順が妨げられることもありません。削減できる時間や見つかるバグの数はプロジェクトによって異なります。実ランタイムでの確認回数が一定数減ると約束しないでください。

TavernWeave は、このループの仕様と作業方法を提供します。合意したテスト用ワークスペース内で、作成者が保守しているソースからプロジェクト固有のサンドボックスを構築し、プロジェクトのプレビューサービスと開発スタックを再利用してください。汎用の TW ワークベンチ、デモアプリケーション、導入案内ページは新たに作らないでください。既存の採用／見送りの判断を再利用してください。サンドボックスの構築依頼があれば、それは採用の意思表示です。見送りの場合、サンドボックスを作成せず、既存のワークフローを続行してください。

範囲、実装手順、エビデンスの境界についてはサンドボックスのワークフロー、状態、イベント、UI パラメーターについては統合契約、単一モジュールまたは複数モジュールのチェックを選ぶ際はシナリオのレシピを参照してください。これらは実装要件であり、出荷済みランタイムの API ではありません。名称とレイアウトはプロジェクトに合わせて調整してください。任意で利用できるリポジトリのユーザーガイドには、そのまま使える依頼文が用意されています。上記の同梱リファレンスだけでも、オフラインのスキルのみのインストールには十分です。

プロジェクトの最小限のホストアダプターを通じて、保守対象のコンポーネントソース全体を読み込み、選択したすべてのモジュールについて、実際のソースパス、リビジョン、SHA-256 を一覧にしてください。提示されたハッシュに unverified と記されている場合は、整合性チェックとして扱わず、未検証と報告してください。必須の iframe／blob 階層と API のウィンドウ位置を維持してください。完全なシミュレーションでは、合意した範囲内のすべてのモジュール、エントリー、機能を対象にします。読み込み済み、未接続、未サポート、未テストの項目は、それぞれ分けて示してください。集中して確認する場合は単一モジュールを使い、共有状態やイベントが重要な場合は関連するモジュールをまとめてマウントしてください。差し替えたモックのスクリーンショットでは、ソースへの忠実性を証明できません。

ゲームデータと一時的な UI 設定は分離してください。データソース、バッチ、対象のチャット／フロア、変更前後の差分、想定されるイベントを示してください。注入前に、バッチ、範囲、状態リビジョンに紐づく明示的な確認を必須にしてください。初期プリセットとシナリオの全手順についても確認を求めてください。承認済みのシーケンスでは、内部の各ステップごとに承認を繰り返す必要はありません。書き込みせずにキャンセルできるようにし、対象またはリビジョンが変更された場合は承認を無効にしてください。実際に確定された状態を、各モジュールが観測したフィールドと比較してください。UI スライダーと数値入力は、採用された範囲内で即時にプレビューできるようにしてください。ベースラインとの比較、リセット、プリセット、パラメーターのエクスポートも用意してください。手動調整中にユーザーのビューポートサイズを変更しないでください。選択した変更をバックポートした後、一時的なオーバーライドを削除し、保守対象のソースから同じシーンを再実行してください。シナリオ記録と残っているホスト側の不足事項をエクスポートし、正確にビルドした成果物を sillytavern-runtime-debug に渡してください。サンドボックスでのチェックによって driverAccepted を設定したり、実際のホスト、デバイス、モデル、人間による視覚的なエビデンスを置き換えたりしてはいけません。

公開ドキュメントでは、仕組みを示す合成例を使用してください。非公開のカードソース、元のチャット、プレイヤーデータ、ローカルのエビデンスは、公開リポジトリやリリースには含めず、プロジェクトのテスト用ワークスペース内に保管してください。

オープニングページ

first_mes は、コンテキスト、スワイプ、編集、分岐、エクスポート、マクロ、正規表現、レンダリングに関わる実際のアシスタントメッセージとして扱ってください。

ページ自体が、ビルダーの オープニング契約 における挨拶の提示役を担う場合もあります。固定シーンや選択肢のページでは、その内容とプレイへの導入を確認してください。ページをレンダリングしても、それだけで状態の書き込みやメッセージの送信が許可されるわけではありません。利用可能な first_mes または選択された alternate_greetings の経路を維持し、モデルに渡る内容とプレイヤーに表示される内容を別々に確認してください。

固定のオープニングが数種類ある場合は、ネイティブの挨拶分岐を優先してください。カスタムセットアップウィザードを実装する場合は、次のトランザクションルールを適用してください。

• 表示領域を小さく保ち、大きな UI マークアップをモデルコンテキストに含めないでください。
• 安定したチャット ID ごとに下書きを分離し、保存済みの下書きを検証して移行してください。
• プレビューは読み取り専用にしてください。最終的にプレイヤーに送信されるメッセージと、永続的な影響をすべて表示してください。
• 確認時にチャットと下書きのコンテキストを固定し、書き込みと送信の前に再確認してください。
• 変更可能な対象のスナップショットを取り、再試行を冪等にし、取り消せない処理は最後に実行してください。
• SillyTavern の通常の送信経路を使用し、実際のユーザーメッセージとアシスタントの返信が作成されるようにしてください。
• 既存の入力テキストを保持し、自動化に失敗した場合も手動送信できるようにしてください。
• 実際のユーザーメッセージが確認されてから、オープニングを確定済みとして記録してください。
• 成功後はオープニングのワークフローを終了し、その後のプレイを通常の複数メッセージの流れに戻してください。

ステータスバーと HUD

• MVU が状態を提供する場合は、MVU ステータスバー設計を使い、プレイヤーの閲覧タスクをフィールドから表示へのマッピングに落とし込んでください。現在のスキーマを再利用し、不足している構造は上流で解決してください。レイアウトを埋めるために変数を作成しないでください。
• 見栄えよりも、繰り返し確認しやすいことを優先してください。
• 読み込み中、空、利用不可、不正なデータ、古いデータの各状態を適切に表示してください。
• 変数のパスと書式設定を一元管理してください。コンポーネントのコード内にスキーマのパスを散在させないでください。
• 対象のフロアから stat_data を読み取り、文書化されたイベントに基づいて更新してください。
• フィルター、タブ、モード切替はすぐに理解できるようにしてください。
• 長い値は、意図的に折りたたむ、折り返す、切り詰める（アクセシブルな全値表示手段を用意する）、またはスクロール可能にしてください。
• データ更新後も、アクティブなタブ、スクロール位置、展開したセクション、ユーザーが選択したマップや表示状態を維持してください。
• スワイプ、編集、再レンダリングの後に、フレームやマウントが重複しないようにしてください。
• 変更のないセクションの再レンダリングを避けるためにシグネチャや対象を絞った更新を使用しつつ、ユーザー操作後には意図的に強制更新できるようにしてください。
• フィールドの契約に従って、有効な 0 や false と、欠落、null、不正なデータを区別してください。読み取り専用の更新やローカルの表示操作で、ゲーム状態を初期化または修復してはなりません。

コントロールセンター

• メインのステータスと主要な操作を常に見える状態にし、設定の下に埋もれさせないでください。
• 起動制御、シェルの形状、コンテンツのレンダリング、データ操作を分離してください。
• パネルをシングルトンにし、チャットやホスト UI の再構築後も起動位置を復元してください。
• セクションのレンダリングエラーを分離し、不正なフィールドが1つあってもパネル全体が空白にならないようにしてください。
• オフライン、未認証、依存関係の不足、一部のみ成功、再試行の各状態を説明してください。
• ワールドブック、パッケージ、ID、変数への変更は、確定前にプレビューしてください。
• オープニングページのトランザクションにおいて、隠れた第2の信頼できる情報源としてコントロールセンターを使用しないでください。

ポップアップ、ドロワー、モーダル

• オーバーレイは、祖先要素の overflow、transform、フィルターによってクリップされないレイヤーにマウントしてください。フレームワークを使用しないコードでは、アクセス可能なドキュメントの body の直下に専用のオーバーレイルートを設ける方法が、ポータルに相当します。
• ホストドキュメントにアクセスできない場合は、パネル内に絶対配置のオーバーレイを使用し、スクロール方法を意図的に設計してください。
• 幅と高さを実際のコンテナーに合わせて制限し、内部にスクロール可能な領域を設けてください。
• サーフェス内にフォーカスを移動し、適切な場合は真のモーダル内にフォーカスを留め、Escape キーで閉じ、開いた要素にフォーカスを戻してください。
• 背景領域と閉じるボタンの動作を明確にしてください。破壊的な操作が誤って簡単に閉じられることのないようにしてください。
• body のスクロールやカーソルに加えた変更は、元に戻せるようにしてください。
• 確認ダイアログが入れ子になるフロー、長いコンテンツ、モバイルキーボード、高さの低いビューポートをテストしてください。

アクセシビリティのゲート

• 見出しの順序と DOM の読み上げ順序を論理的に保ってください。
• すべてのコントロールにアクセシブルな名前を付け、すべてのフィールドに表示されるラベルを付けてください。
• アクティブなタブ、展開されたセクション、選択された値、ビジー状態、検証エラーを、適切な ARIA 状態で通知してください。
• 必要に応じて、非同期のステータスやエラーに aria-live を使用してください。
• キーボードによる操作をすべて可能にし、フォーカスを視覚的に示してください。
• 色だけで状態を伝えないでください。
• 可能な場合は、タッチ操作のコントロールを約 44 × 44 CSS ピクセルにしてください。
• prefers-reduced-motion を尊重し、アニメーション中にしか存在しない重要な情報を避けてください。
• テキストのコントラスト、200％ズーム時のリフロー、長い CJK テキスト、スクリーンリーダーで認識しやすいエラーの関連付けを確認してください。

ランタイムへの引き継ぎを準備する

静的リンティング、ユニットテスト、オフラインプレビューは補助的なチェックです。実装候補の準備にこれらを使用したうえで、ビルド済みの成果物を sillytavern-runtime-debug に引き渡し、実際のSillyTavern実行エビデンスを取得して受け入れ確認を完了してください。同じ成果物リビジョンを対象とする別の runtime-debug レポートを引用しない限り、ここでランタイムケースを合格と判定しないでください。

該当するランタイムケースを選択し、引き継ぎに含めてください。

領域	要求するランタイムデバッグのエビデンス
レンダリング	新規チャット、各オープニングスワイプ、メッセージ編集、再レンダリング、再読み込み、チャット切り替え
状態	読み込み中、空、長いデータ、不正なデータ、依存関係の欠落、ネットワーク障害、再試行、一部成功
インタラクション	ポインター、キーボード、フォーカスの復帰、連続クリック、キャンセル、閉じる操作、入力内容の保持
レイアウト	デスクトップの広い画面、狭いメッセージコンテナー、約 320px の幅、低いビューポート、ズーム、モバイルキーボード
スタイル	計算済みの display、サイズ、オーバーフロー、重なり順、変換されたクラス名、ダーク／ライトの表示環境、モーションの軽減
データ	正しいスコープ／階層、イベントの更新、再読み込み後の永続化、無関係な変更がないこと、重複コミットがないこと
セキュリティ	ユーザー／モデルのテキストが不活性のままであること、リモートマークアップがビジネスロジックを実行できないこと、DOM やログにシークレットが現れないこと

メッセージコンテンツページでは、メッセージコンテンツページからプロトコルケースを選び、該当する場合は前後の文章が保持されることとコンテンツが不完全な場合を含めてください。MVU 表示では、MVU ステータスバーの設計からフィールドとコレクションのケースを選び、読み取り専用の更新も含めてください。正規表現のフィクスチャだけでは、パーサーや視覚的な動作を確認できません。無関係なデモアプリケーションを作成するのではなく、実際の変更の範囲内でこれらのチェックを行ってください。

フロントエンドのあいさつでは、実際のメッセージ／ブランチのキャリア、表示されるコンテンツ、プレイの開始、モデルから見える情報を確認してください。実際に提供するコントロールに応じて、インタラクションケースを選択してください。独自のセットアップウィザードではさらに、下書きの編集、更新／復元、プレビュー、確認、実際のプレイヤーメッセージ、重複送信のない実際のアシスタントの応答が必要です。採用した状態システムで変数の初期化が必要な場合は、それも確認してください。 HUD やコントロールセンターでは、スワイプ／編集／チャット切り替えのライフサイクルチェックと、計算済みスタイルの実際の検査を依頼してください。

成果物

以下を報告してください。

• 選択したサーフェスと状態の所有者。
• 調査した設計リファレンス、視覚的な提案、未検証の品質エビデンス。
• 最小限の実装またはレビューで判明した事項。
• セキュリティとアクセシビリティに関する判断。
• 裏付けとなるチェックと、デスクトップまたは狭いレイアウトでのエビデンス。
• 正確なビルド成果物の識別情報と、選択したランタイム引き継ぎケース。
• sillytavern-runtime-debug に関する既知のデバイス、アカウント、拡張機能、またはドライバーのブロッカー。