contribute-catalog

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

使用する場面

次のような場合に、このスキルを使用します。

• 公開カタログへのコントリビュート — ユーザーがブロック／コンポーネントを upstream FrameVideo registry に追加したい場合
• PR の提出 — ユーザーが再利用可能なエフェクトを作成し、共有したい場合
• レジストリ向けのパッケージ化 — ユーザーが registry-item.json とファイルの構成についてサポートを必要としている場合

使用しない場面

次の場合は、このスキルを使用しないでください。

• プロジェクト内のエフェクト — プロジェクト固有のキャプション／トランジションには framevideo スキルを使用します
• 既存アイテムのインストール — framevideo-registry スキルを使用します
• FrameVideo の学習 — コンポジションの作成には framevideo スキルを使用します

---

クイックスタート

コントリビューションのワークフローを完了します。

# 1. Clarify what to build
User: "I want to contribute a Hormozi-style caption block"
→ Ask: description, visual reference, use case

# 2. Scaffold registry structure
registry/blocks/cap-hormozi/
  cap-hormozi.html
  registry-item.json

# 3. Build the block
→ Use `framevideo` skill for HTML authoring
→ Use 2-3 letter prefix for all element IDs (e.g., "hz-")

# 4. Validate
npx framevideo lint registry/blocks/cap-hormozi/cap-hormozi.html
npx framevideo add cap-hormozi --dir ./test-project

# 5. Preview
npx framevideo preview ./test-project

# 6. Ship
git checkout -b contrib/cap-hormozi
git add registry/blocks/cap-hormozi/
git commit -m "Add Hormozi-style caption block"
# Create PR to framevideo repo

重要なポイント：

• 衝突を避けるため、すべての要素 ID に一貫したプレフィックスを使用します
• ブロックには固定の寸法／再生時間があり、コンポーネントにはありません
• PR を提出する前に framevideo add でテストします

---

ワークフロー

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

ステップ 1：内容を確認する

何を作成するのかを尋ねます。レジストリには次の 2 種類のアイテムがあります。

• Block（registry/blocks/、type framevideo:block） — 寸法と再生時間が固定された、単体で完結するコンポジションです。キャプションスタイル、VFX エフェクト、タイトルカード、ローワーサードなどが該当します。
• Component（registry/components/、type framevideo: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 にこのプレフィックスを使用する必要があります。

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

{
  "$schema": "https://www.chanjing.cc/schema/registry-item.json",
  "name": "{block-name}",
  "type": "framevideo: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": "framevideo:composition"
    }
  ]
}

コンポーネント用の registry-item.json（dimensions または duration はありません）：

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

ステップ 3：作成する

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

キャプションブロック

必須のキャプションルール：

• フォント：プロポーショナルフォントは最低 96px。等幅フォントは 64～72px でも可（文字幅が広いため、より小さいサイズで済みます）。
• 可読性：-webkit-text-stroke: 2-3px または複数レイヤーの text-shadow
• はみ出し：すべてのグループで window.__framevideo.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 を使用します。

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

• 各文字を {prefix}-ch-{group}-{char} という ID を持つ <span> で囲みます
• 単語のタイムスタンプから算出した間隔で 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：検証

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

ステップ 5：プレビュー

# Render preview video
framevideo render -o preview.mp4

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

# Publish to framevideo.dev for review
npx framevideo publish

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

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

ステップ 6：公開

すべての手順が必須です。1 つでも欠けると、カタログエントリーが正しく表示されません。

{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": "framevideo:block" }  (or "framevideo:component")

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

# 5. Publish to framevideo.dev so reviewers can preview
npx framevideo 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 framevideo.dev link
git push origin feat/registry-{name}
gh pr create --title "feat(registry): {name}" --body "preview: {framevideo.dev-url}"

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

品質ゲート

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