contribute-catalog

HyperFrames Registry へのコントリビュート

新しいレジストリブロックまたはコンポーネントのアイデアから、PR のマージまでユーザーを導きます。

ワークフロー

1. Clarify → 2. Scaffold → 3. Build → 4. Validate → 5. Preview → 6. Ship

ステップ 1：要件を確認する

何を作ろうとしているのか尋ねます。レジストリには 2 種類のアイテムがあります。

• ブロック（registry/blocks/、タイプ hyperframes:block） — 固定の寸法と長さを持つ、単体で完結したコンポジションです。キャプションスタイル、VFX エフェクト、タイトルカード、ローワーサードなどが該当します。
• コンポーネント（registry/components/、タイプ hyperframes:component） — 固定の寸法や長さを持たない、再利用可能なスニペットです。CSS エフェクト、テキストの装飾、あらゆるコンポジションサイズに適応するオーバーレイなどが該当します。

続けて、次の点を尋ねます。

• エフェクトの説明（1 文）
• 視覚的な参考資料（URL、スクリーンショット、または説明）
• どのようなユーザーが、どのようなときに使うのか？

ステップ 2：ひな形を作成する

レジストリの構成を作成します。

ブロックの場合：

registry/blocks/{block-name}/
  {block-name}.html
  registry-item.json

コンポーネントの場合：

registry/components/{component-name}/
  {component-name}.html
  registry-item.json

命名規則：

アイテム名	ID の接頭辞	ID の例
cap-hormozi	hz	hz-cg-0、hz-cw-3
cap-typewriter	tw	tw-cg-0、tw-ch-0-5
vfx-chrome	vc	vc-canvas

2〜3 文字の接頭辞を使います。サブコンポジション内で ID が重複しないよう、すべての要素 ID にこの接頭辞を付ける必要があります。

ブロック用の registry-item.json：

{
  "$schema": "https://hyperframes.heygen.com/schema/registry-item.json",
  "name": "{block-name}",
  "type": "hyperframes:block",
  "title": "{Human Title}",
  "description": "{one sentence}",
  "dimensions": { "width": 1920, "height": 1080 }, // adjust: 1080x1920 for portrait/social
  "duration": 10, // adjust for your composition
  "tags": ["{category}", "{subcategory}"],
  "files": [
    {
      "path": "{block-name}.html",
      "target": "compositions/{block-name}.html",
      "type": "hyperframes:composition"
    }
  ]
}

コンポーネント用の registry-item.json（dimensions と duration は含めません）：

{
  "$schema": "https://hyperframes.heygen.com/schema/registry-item.json",
  "name": "{component-name}",
  "type": "hyperframes:component",
  "title": "{Human Title}",
  "description": "{one sentence}",
  "tags": ["{category}"],
  "files": [
    {
      "path": "{component-name}.html",
      "target": "compositions/components/{component-name}.html",
      "type": "hyperframes:snippet"
    }
  ]
}

ステップ 3：構築する

種類に応じた適切なテンプレートを適用します。コピーして使えるひな形については、templates.md を参照してください。

キャプションブロック

必ず守るキャプションのルール：

• フォント：プロポーショナルフォントは 最低 96px にします。等幅フォントは 64〜72px でもかまいません（文字幅が広いため、小さめのサイズで十分です）。
• 読みやすさ：-webkit-text-stroke: 2-3px または複数レイヤーの text-shadow を使います。
• はみ出し対策：各グループで window.__hyperframes.fitTextFontSize() を呼び出します。
• カラオケ表示：tl.to(wordEl, { color/scale }, WORDS[wi].start) を使って、アクティブな単語を強調表示します。
• 確実に非表示にする：すべてのグループで、tl.set(groupEl, { opacity: 0, visibility: "hidden" }, g.end) を設定します。
• 同じ位置で tl.from(el, { opacity: 0 }) と tl.set(el, { opacity: 1 }) を使わないでください — from が set の設定を上書きします。代わりに tl.to を使います。

文字ごとのアニメーション（タイプライター、スクランブル）：

• 各文字を <span> で囲み、ID を {prefix}-ch-{group}-{char} にします。
• 単語のタイムスタンプから算出した間隔で tl.set を使ってずらします。
• カーソルや装飾要素には、間隔を指定して tl.set を使います。CSS アニメーションは使いません（シークできないため）。

配置のバリエーション：

• 中央揃え：display: flex; align-items: center; justify-content: center;
• ローワーサード：position: absolute; bottom: 100px; left: 0; width: 100%; text-align: center;
• 左揃え：position: absolute; bottom: 100px; left: 120px; text-align: left;

VFX ブロック（Three.js）

• CDN から [email protected] を使います（グローバルスクリプト）。
• tl.eventCallback("onUpdate", renderScene); renderScene(); を使います。requestAnimationFrame は使いません。
• 状態プロキシパターン：GSAP でプレーンな JS オブジェクトをアニメーションさせ、レンダー関数からそのオブジェクトを読み取ります。
• 乱数にはシード付き PRNG（mulberry32）を使います。

すべての種類に共通

• data-composition-id は window.__timelines["id"] と一致させる必要があります。
• すべての要素 ID にブロックの略称を接頭辞として付けます。
• gsap.timeline({ paused: true }) を使い、タイムラインは常に一時停止状態にします。
• Math.random() と Date.now() は使いません。

ステップ 4：検証する

hyperframes lint                    # 0 errors required
hyperframes validate --no-contrast  # 0 console errors required

ステップ 5：プレビューする

# Render preview video
hyperframes render -o preview.mp4

# Snapshot for visual QA
hyperframes snapshot --at "1.0,3.0,5.0,7.0"

# Publish to hyperframes.dev for review
npx hyperframes publish

カタログのプレビュー画像 — カタログカードでは、docs/images/catalog/{kind}/{name}.png（{kind} は blocks または components）の PNG を使います。スナップショットから画像を生成した後、次の手順を実行します。

• HeyGen の社内コントリビューター： scripts/upload-docs-images.sh を実行します（AWS プロファイル engineering-767398024897 が必要です）。
• 外部コントリビューター： プレビュー MP4 を PR の説明に添付します。マージ前にメンテナーがカタログ画像を生成してアップロードします。

ステップ 6: 出荷

すべてのステップが必須です。どれか一つでも欠けると、カタログエントリが壊れます。

{kind} は、ステップ 1 で作成したものに応じて blocks または components になります。

# 1. Create branch
git checkout -b feat/registry-{name}

# 2. Format HTML
npx oxfmt registry/{kind}/{name}/*.html

# 3. Update registry/registry.json — add entry to the "items" array:
#    { "name": "{name}", "type": "hyperframes:block" }  (or "hyperframes:component")

# 4. Generate catalog docs page
npx tsx scripts/generate-catalog-pages.ts

# 5. Publish to hyperframes.dev so reviewers can preview
npx hyperframes publish

# 6. Stage everything
git add registry/{kind}/{name}/ registry/registry.json docs/catalog/

# 7. Commit
git commit -m "feat(registry): add {name} — {one sentence}"

# 8. Push and open PR with hyperframes.dev link
git push origin feat/registry-{name}
gh pr create --title "feat(registry): {name}" --body "preview: {hyperframes.dev-url}"

GitHub アカウントをお持ちでない場合: PR を作成するにはアカウントが必要です。https://github.com/signup でサインアップし、gh auth login を実行してください。

品質ゲート

• hyperframes lint → エラー 0 件
• hyperframes validate → コンソールエラー 0 件
• npx oxfmt --check がパスする
• registry/registry.json に新しいエントリが追加されている
• scripts/generate-catalog-pages.ts を実行済み（ドキュメントページが生成されている）
• npx hyperframes publish を実行済み（プロジェクト URL を取得する）
• プレビュー MP4 を PR に添付済み（外部）またはカタログ PNG をアップロード済み（内部）
• すべての ID が一意でプレフィックスが付いている