hyperframes-registry

HyperFrames レジストリ

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

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

クイックリファレンス

hyperframes add data-chart              # install a block
hyperframes add grain-overlay           # install a component
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 — レイヤーの順序（数値が大きいほど手前）

詳細は 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 を参照してください。

検索

利用可能な項目を表示します。

# Read the registry manifest
curl -s https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry/registry.json

各項目の registry-item.json には、名前、種類、タイトル、説明、タグ、サイズ（ブロックのみ）、再生時間（ブロックのみ）、ファイル一覧が含まれています。

種類やタグによる絞り込みの詳細は discovery.md を参照してください。

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

新しいレジストリ項目（キャプションのスタイル、VFX ブロック、トランジション、ローワーサード、再利用可能なコンポーネント）を作成し、既存の項目をインストールするのではなく、アップストリームの PR として提供する場合は、contributing.md にある、アイデアの検討 → 雛形の作成 → ビルド → 検証 → プレビュー → 提出のワークフローに従ってください。コピーして使えるスターターテンプレート（キャプション / VFX / コンポーネント / registry-item.json）は templates.md にあります。