widget-forms

ウィジェットフォームのホストアダプター

正規エージェントの生の <widget>、<choices/>、<visual-option> タグは ChatCut 内でのみレンダリングされます。公開済みの Codex または Claude Code プラグインから、これらのタグを出力しないでください。

セマンティックコントラクトのマッピング

このアダプターは、ホストに依存しない呼び出し元のフォームコントラクトを、プラグインホストがどのように実装するかを担います。ワークフローで必要なフィールドを決定するものではありません。

セマンティックなフィールド型を次のようにマッピングします。

• short_text：テキスト入力を1つ表示します。
• explicit_consent：呼び出し元が指定した完全なローカライズ済み文言を使用する、明示的な確認コントロールを1つ表示します。初期状態では未選択にします。添付ファイルや、ほかの送信済みフィールドを同意として扱うことはできません。
• audio_reference：プラグインフォームではメディアを録音またはアップロードできません。ほかのフィールドを表示し、音声を会話に添付するようユーザーに依頼してから、asset-import を読み込みます。インポートされた ChatCut 音声の assetId を呼び出し元のワークフローに返します。ローカルパス、添付ファイルの URL、または生のバイト列をアセット ID として返してはいけません。
• playable_single_choice：値が安定した選択肢とローカライズ済みラベルを備えた選択肢 UI を1つ表示し、ホストが対応している場合は再生可能なメディアも表示します。ホストが表示ラベルを返す場合に備えて、値とラベルの対応表をコンテキストに保持します。
• playable_preview：送信対象にならない、表示専用の音声 UI を1つ表示します。呼び出し元から渡されたランタイムメディア URL をそのまま使用します。ホストが対応する安全なメディアレンダラーのみを使用してください。生の <audio> HTML を出力したり、通常の文章として URL を公開したりしてはいけません。

Codex

ChatCut MCP ツール ask_followup_questions を呼び出します。関連するフィールドを1つのフォームにまとめ、表示テキストをユーザーの言語で記述し、送信された回答がチャットに表示されるまで、呼び出し後は停止します。フィールドと選択肢の形式には、現在のツールスキーマを使用してください。

playable_single_choice は、variant:"voice" を指定した single フィールド1つにマッピングします。安定した各値を選択肢 ID として使用し、ローカライズ済みラベル、説明、audioUrl を、呼び出し元から渡された同じ項目に紐付けます。再生可能なメディアがないアクションには audioUrl を設定しません。

MG の参照スタイル選択は、variant:"visual" を指定した single フィールド1つにマッピングします。参照 ID を選択肢 ID として使用し、短いタイトルをラベルにし、選択した詳細の heroPreview.url を preview に指定します。ユーザーの言語で「その他」とラベル付けした __other__ 選択肢を1つ含めます。この選択肢では、ツールがテキスト入力欄を表示します。この分岐では、新しい設定または別のバッチのリクエストのどちらも受け付けます。「さらに表示」選択肢を別途追加しないでください。選択された参照 ID を MG スキルに返します。適用処理は MG スキルが担います。apply_preset を参照 ID に直接紐付けないでください。

取得した候補リストに参照用プレースホルダーを置き換え、ラベルをローカライズしたフィールドの例：

{
  "id": "mg_style",
  "label": "Choose a Motion Graphics style",
  "type": "single",
  "variant": "visual",
  "options": [
    { "id": "REFERENCE_ID", "label": "TITLE", "preview": "HERO_PREVIEW_URL" },
    { "id": "__other__", "label": "Other" }
  ]
}

「その他」の回答では、スタイルを適用したり制作を開始したりせずに、探索に戻ります。次のステップでも画像選択肢の ID は変更しないでください。

AI アバターのアイデンティティ選択は、variant:"visual" を指定した single フィールド1つにマッピングします。ライブの identityId を選択肢 ID として使用し、返された name をラベルにし、previewVideoUrl を previewVideo に、previewImageUrl を preview に指定します。動画の読み込みに失敗した場合、画像はポスター画像および自動フォールバックとして残ります。create_avatar はラベルのみの選択肢として保持します。これを選択すると、その値がワークフローに返されます。ChatCut のネイティブアバターダイアログは開きません。そのため、ソースを別途添付するよう依頼し、asset-import を使用してください。

受動的なプレビューは質問ではないため、playable_preview の表示のみを目的として ask_followup_questions を呼び出してはいけません。利用可能な場合は、Codex が対応する音声添付／メディアレンダリングを使用してください。このホストセッションにランタイム URL 用の安全な音声レンダラーがない場合は、プレビューを ChatCut プロジェクトのアセットで利用できると伝え、呼び出し元が指定する別の分岐判断に進みます。HTML、URL のみの表示、または偽のウィジェットタグを出力してはいけません。

explicit_consent は、確認用選択肢を1つだけ含む単一選択フィールドにマッピングします。呼び出し元が指定した完全な確認文言をラベルとして使用し、事前選択状態にはしないでください。ブロック要因となるすべてのフィールドを必須として設定し、送信後、続行する前にすべての必須回答が揃っていることを確認してください。

Claude Code

chatcut-plugin-basics-claude の構造化入力のレシピに従ってください。visualize.show_widget の Elicitation フォームを 1 つ使用し、送信は .elicit-submit からのみ行い、ユーザーが入力済みのプロンプトを送信するまで待ってください。Claude Code では、ホストが MCP-App の結果をレンダリングしないため、ChatCut の ask_followup_questions を呼び出さないでください。

explicit_consent は、呼び出し元のローカライズ済み文言を完全な形で使い、チェックの入っていないチェックボックスに割り当ててください。audio_reference 用のファイル選択機能は追加せず、会話の添付ファイルをフォーム外でリクエストし、ユーザーが送信した後に asset-import を読み込んでください。

playable_single_choice では、バンドルされたメディアキーを ${CLAUDE_PLUGIN_ROOT}/assets/widget-media/manifest.json を使って解決してください。キーがない場合はラベルのみのカードを使用し、元のソース URL を埋め込んだり処理したりしないでください。安定した値はラベルと ID のマップに保持し、DOM のオーディオキーとして公開しないでください。ランタイムのメディア URL はバンドルされたマニフェストに含まれていません。Elicitation の HTML に埋め込まないでください。ホストの通常の安全なリンク／オーディオ表示機能で提示し、その後、ラベルのみの確認コントロールを使用してください。

AI アバターのプレビューはランタイムカタログのメディアであり、プラグインのマニフェストにはバンドルされていません。各権威ある identityId を、返された name に対応付け、Elicitation ではラベルのみの選択可能なカードを使用し、ChatCut の AI Avatars ライブラリでライブ動画プレビューを利用できることをユーザーに伝えてください。プロバイダーのプレビュー URL を埋め込んだり表示したりしないでください。create_avatar の選択後はワークフローに戻り、通常の会話への添付と asset-import の手順に進んでください。

MG の参照候補については、同じマニフェスト内で正確な参照 ID（たとえば mg-reference:style:… キー）を検索してください。画像エントリーには path が含まれます。そのパスをマニフェストの不変の baseUrl に対して解決し、Elicitation フォームで短いタイトルの横にその画像を表示してください。参照 ID は表示ラベルに対応付けてください。名前が似たプリセットで代用しないでください。

新たに追加された参照が、まだマニフェストに含まれていない場合があります。エントリーが見つからないときはラベルのみの選択肢を使用し、画像プレビューは ChatCut で利用できることを伝えてください。会話中に CDN パスを推測したり、メディアをダウンロードまたは再公開したり、ランタイムの S3 URL を埋め込んだりしないでください。テキスト入力欄付きの、ラベルのみの「その他」選択肢を 1 つ含めてください。別の候補群に対する希望やリクエストがあった場合は、スタイルの適用ではなく、探索に戻ってください。