HyperFrames レジストリ

レジストリは、hyperframes add <name> でインストール可能な再利用可能なブロックとコンポーネントを提供します。

ブロック — 独立したサブコンポジション（独自の寸法、再生時間、タイムラインを持ちます）。ホストコンポジションに data-composition-src で含めます。
コンポーネント — エフェクトスニペット（独自の寸法はありません）。ホストコンポジションのHTMLに直接貼り付けます。

クイックリファレンス

hyperframes add data-chart              # ブロックをインストール
hyperframes add grain-overlay           # コンポーネントをインストール
hyperframes add captions                # captions タグが付いたすべてのブロックをインストール
hyperframes add shimmer-sweep --dir .   # 特定のプロジェクトをターゲット
hyperframes add data-chart --json       # 機械可読な出力
hyperframes add data-chart --no-clipboard  # クリップボードをスキップ（CI/ヘッドレス）

インストール後、CLIは書き込まれたファイルと、ホストコンポジションに貼り付けるスニペットを出力します。スニペットは開始点です。ブロックを配線する際には、data-composition-id（ブロックの内部コンポジションIDと一致する必要があります）、data-start、data-track-index 属性を追加する必要があります。

位置引数は最初に正確なアイテム名として解決されます。アイテムが一致せず、値がタグの場合は、コマンドはそのタグが付いたすべてのブロックをインストールします。レジストリの依存関係は、要求されたアイテムの前にインストールされます。hyperframes add はブロックとコンポーネントにのみ機能します。サンプルを使用するには、代わりに hyperframes init <dir> --example <name> を使用してください。

インストール場所

デフォルトでは、ブロックは compositions/<name>.html にインストールされ、コンポーネントは compositions/components/<name>.html にインストールされます。

これらのパスは hyperframes.json で設定可能です：

{
  "registry": "https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry",
  "paths": {
    "blocks": "compositions",
    "components": "compositions/components",
    "assets": "assets"
  }
}

詳細は install-locations.md を参照してください。

ブロックの配線

ブロックは独立したコンポジションです。ホストの index.html で data-composition-src を使用して含めます：

<div
  data-composition-id="data-chart"
  data-composition-src="compositions/data-chart.html"
  data-start="2"
  data-duration="15"
  data-track-index="1"
  data-width="1920"
  data-height="1080"
></div>

主要な属性：

data-composition-src — ブロックHTMLファイルへのパス
data-composition-id — ブロックの内部IDと一致する必要があります
data-start — ブロックがホストタイムラインに表示されるタイミング（秒）
data-duration — ブロックの再生時間
data-width / data-height — ブロックのキャンバスサイズ
data-track-index — レイヤーの順序（大きいほど前面）

詳細は wiring-blocks.md を参照してください。

コンポーネントの配線

コンポーネントはスニペットです。そのHTMLをコンポジションのマークアップに、CSSをスタイルブロックに、JSをスクリプト（ある場合）に貼り付けます：

インストールされたファイルを読み取る（例：compositions/components/grain-overlay.html）
HTML要素をコンポジションの <div data-composition-id="..."> にコピーする
<style> ブロックをコンポジションのスタイルにコピーする
<script> の内容をコンポジションのスクリプト（タイムラインコードの前）にコピーする
コンポーネントがGSAPタイムライン統合を公開している場合（スニペット内のコメントブロックを参照）、それらの呼び出しをタイムラインに追加する

詳細は wiring-components.md を参照してください。

ディスカバリ

主なディスカバリ手段としてCLIを使用してください。ブラウズする前に意図で検索してください： レジストリには目でスキャンできる以上のアイテムが含まれているため、リストアップして名前やタグでマッチさせるのは遅い方法であり、作成者の表現があなたの表現と異なる場合に失敗します。

# カタログ全体を、ビートが何をすべきかに基づいてランク付け
npx hyperframes catalog --query "見出しを一行ずつ表示する"
npx hyperframes add caption-clip-wipe

検索はローカルで実行され、何も送信しません。デフォルトでは、アイテムの名前、タイトル、説明と共有される語彙に基づいてランク付けされるため、入力した単語を再利用するアイテムのみが見つかります。--on-device は、1回限りのモデルダウンロード後に、意味に基づいてランク付けします。--json を使用すると、エンベロープにはどの層が応答したかが示されるため、ランク付けが行われたと仮定するのではなく、それを確認してください。

ビデオの言語に関係なく、常に英語でクエリを実行してください。 カタログは英語で書かれており、両方の層がそのようにインデックスを作成します（オンデバイスモデルも英語のみです）。他のスクリプトでのクエリは検索可能な用語を生成せず、何も返しません。これは、日本語や中国語のプロジェクトでは間違えやすいです。ブリーフ、キャプション、ナレーションがすべてその言語であり、クエリが自然にそれに従うためです。_動き_を英語で説明し、画面上のコピーはビデオが必要とする任意の言語で記述してください。クエリが「クエリに検索可能な単語がありません」と返ってきた場合、これはこのルールによるものであり、コンポーネントが欠落しているわけではなく、ギャップレポートの対象にはなりません。

インストール可能性はランク付けの前ではなく、後で適用されます。ベクターが運ぶがこのレジストリが提供できない名前は結果から削除され、dropped にカウントされます。したがって、dropped がゼロでない場合、それらは異なる世代であることを意味します。オフライン層、同意ゲート、および古いインデックスの更新方法については /hyperframes-cli を参照してください。

検索ではなくブラウズまたはフィルタリングするには：

npx hyperframes catalog
npx hyperframes catalog --type block
npx hyperframes catalog --type component
npx hyperframes catalog --type block --tag social
npx hyperframes catalog --json
npx hyperframes catalog --human-friendly

通常のテーブルモードと --json モードは一致するもののみをリストします。hyperframes add <name> で選択した名前をインストールします。--human-friendly はインタラクティブなピッカーを開き、選択したアイテムをすぐにインストールします。CIやエージェントのワークフローでは、--json の後に明示的な add を使用することをお勧めします。

カタログにないものを報告する

検索結果に該当するものがなく、どの結果も役に立たない場合は、手動でモーションを作成する前にその旨を報告してください：

npx hyperframes feedback --search-miss "<実行したクエリ>" --wanted "<必要だった動き>" --tier on-device

catalog --query はこの行を事前に入力して出力し、--json はそれを report_gap として保持します。つまり、何も合わないと判断した時点で、その情報はすでに手元にあります。

どちらの層でも、結果に該当するものがない場合は常に報告してください。 オンデバイス層が応答するのを待ってはいけません。同意が必要な33MBのダウンロードが必要なため、明示的にオプトインしない限り、エージェントの実行は words 層に依存しており、on-device を条件にするとほとんどすべての報告が抑制されます。--tier の値が一緒に送られるため、語彙のミスと意味のミスを読み取り時に区別できます。想像したアイテム名ではなく、実現したい効果を説明してください。返ってくるのは構築する価値のある動きのリストであり、存在しないアイテムを指定した報告は何も教えてくれません。これが唯一クエリをどこかに送信するパスであり、検索が自動的に行うのではなく、別個の意図的なコマンドとして存在する理由です。これは評価を含まず、評価指標に含まれることはありません。

これがカタログに対する需要シグナルの全体です。これをスキップすると、あなたが遭遇したギャップは代わりにインストール数から推測されることになり、誰もインストールできない動きを見つけることはできません。

CLIが設定されたレジストリに到達できない場合は、フォールバックとして生のマニフェストを確認してください：

curl -s https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry/registry.json

CLIが到達できないレジストリは、ディスカバリのためのカタログを空にしません。以前にフェッチされたマニフェストは、再検証に失敗した場合でも、24時間の更新ウィンドウを超えて提供され続けるため、catalog と catalog --query はディスク上の最後のコピーに対してリスト表示とランク付けを引き続き行います。

add は、昨日インストールしたアイテムであっても、ネットワークを必要とします。 キャッシュされるのはマニフェストのみで、アイテムの実際のファイルはインストールのたびにフェッチされます。したがって、オフラインでは検索でき、アイテムが何かを確認できますが、インストールはファイルフェッチで失敗します。ユーザーにオフラインインストールを約束しないでください。

各アイテムの registry-item.json には、名前、タイプ、タイトル、説明、タグ、寸法（ブロックのみ）、再生時間（ブロックのみ）、ファイルリストが含まれています。

タイプとタグによるフィルタリングの詳細は discovery.md を参照してください。

新しいブロックまたはコンポーネントのコントリビュート

新しいレジストリアイテム（キャプションスタイル、VFXブロック、トランジション、ローワーサード、または再利用可能なコンポーネント）を作成し、上流へのPRとして送信するには（既存のものをインストールするのではなく）、contributing.md の完全なアイデア→スキャフォールド→構築→検証→プレビュー→出荷のワークフローに従ってください。スターターテンプレート（キャプション/VFX/コンポーネント/registry-item.json）は templates.md にあります。

hyperframes-registry