hyperframes-registry

プラグインのインストール： このスキルが HyperFrames プラグイン内にある場合は、セットアップや最新状態の確認を行う前に、プラグインの実行ルールに従ってください。単独でインストールした場合は、以下の更新手順に従ってください。

HyperFrames Registry

レジストリには、hyperframes add <name> でインストールできる再利用可能なブロックとコンポーネントが用意されています。

• ブロック — 独自の寸法、再生時間、タイムラインを持つ単独のサブコンポジションです。ホストコンポジションの data-composition-src で読み込みます。
• コンポーネント — 独自の寸法を持たないエフェクトのスニペットです。ホストコンポジションの HTML に直接貼り付けます。

クイックリファレンス

hyperframes add data-chart              # install a block
hyperframes add grain-overlay           # install a component
hyperframes add captions                # install every block tagged captions
hyperframes add shimmer-sweep --dir .   # target a specific project
hyperframes add data-chart --json       # machine-readable output
hyperframes add data-chart --no-clipboard  # skip clipboard (CI/headless)

インストール後、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 — Studio のタイムライン行。表示専用です。レイヤーには CSS の z-index を使用してください

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

コンポーネントの組み込み

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

1. インストールしたファイルを読みます（例：compositions/components/grain-overlay.html）
2. HTML 要素をコンポジションの <div data-composition-id="..."> にコピーします
3. <style> ブロックをコンポジションのスタイルにコピーします
4. <script> の内容があれば、コンポジションのスクリプトにコピーします（タイムラインのコードより前に配置）
5. コンポーネントが GSAP タイムラインとの連携機能を提供している場合（スニペットのコメントブロックを参照）、その呼び出しをタイムラインに追加します

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

ディスカバリー

CLI を主な検索手段として使います。一覧を眺める前に、目的に基づいて検索してください。 レジストリには目視で確認できる量を超える項目があるため、一覧表示して名前やタグを照合する方法は時間がかかり、作成者の表現が異なると見つけられません。

# Rank the whole catalog against what the beat should do
npx hyperframes catalog --query "reveal a headline one line at a time"
npx hyperframes add caption-clip-wipe

検索はローカルで行われ、データは送信されません。デフォルトでは、項目の名前、タイトル、説明と共通する語彙に基づいて順位付けされるため、検索語を再利用している項目しか見つかりません。--on-device を指定すると、モデルを一度ダウンロードした後、意味に基づいて順位付けされます。--json では、どの段階が応答したかがエンベロープに記載されるため、順位付けが行われたと思い込まず、そちらを確認してください。

動画の言語にかかわらず、必ず英語で検索してください。 カタログは英語で書かれており、どちらの検索方式も英語でインデックス化しています（デバイス上のモデルも英語専用です）。別の文字体系で検索すると、検索可能な語句が見つからず、何も返されません。日本語や中国語のプロジェクトでは、概要、字幕、ナレーションがすべてその言語で書かれており、検索語も自然とその言語になるため、間違えやすい点です。動作を英語で説明してから、動画に必要な言語で画面上のテキストを書いてください。検索結果に No searchable words in query と表示された場合、これはこのルールに起因するものであり、コンポーネントの欠落ではありません。ギャップレポートを出す必要はありません。

インストール可能かどうかは順位付けの後に判定されます。ベクトルには存在していても、このレジストリでは提供できない名前は結果から除外され、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 "<the query you ran>" --wanted "<the move you needed>" --tier <the tier that answered>

catalog --query は、この行をあらかじめ入力した状態で出力し、--json では report_gap として含めます。そのため、適合するものがないと判断した時点で、すでに報告に使えます。

どちらのティアでも、検索結果に目的を果たすものがない場合は必ず報告してください。 オンデバイスのティアが回答するまで待たないでください。利用には同意のうえで 33 MB のダウンロードが必要なため、明示的にオプトインしていないエージェントの実行は 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 にあります。