submit-element

Remotion Element を提出する

デザインと品質基準の正式な情報源は、Element の貢献ガイドです。変更を加える前に、すべて読んでください。このスキルとガイドで合格基準に違いがある場合は、ガイドに従ってください。

このスキルでは、コントリビューターによる提出のワークフローを扱います。まず、scaffold-element スキルで作成した Element を用意します。リポジトリへの書き込み権限があるコントリビューターは、レビュー済みのプレビューを直接アップロードします。それ以外のコントリビューターは、一時的なレビュー用アセットをコミットし、後でメンテナーがaccept-element スキルを使って処理します。

1. Element の準備ができていることを確認する

次のファイルと、packages/docs/src/components/Elements/element-definitions.ts 内の対応するエントリーがすでに存在することを確認します。

• packages/docs/elements/<category>/<slug>/index.mdx
• packages/docs/elements/<category>/<slug>/<slug>.tsx

このスキルから Studio を起動しないでください。先に進む前に、開発者に docs Remotion Studio で element-<category>-<slug> を目視でレビューし、正しく表示されることを明示的に確認してもらってください。テストの完了やエージェント自身による確認から、承認されたと判断してはいけません。開発者の承認が得られていない場合、またはビジュアル面の追加開発が必要な場合は、次のコマンドを提示し、提出ワークフローを中止してください。

bun run build
cd packages/docs
bun run remotion

2. 提出方法を選択する

正規リポジトリに対する、認証済み GitHub アカウントの権限を確認します。Git リモート、ブランチ名、コミットのメールアドレスからメンバーシップを推測してはいけません。

login=$(gh api user --jq '.login' 2>/dev/null || true)
permission=$(
  if [ -n "$login" ]; then
    gh api "repos/remotion-dev/remotion/collaborators/$login/permission" \
      --jq '.permission' 2>/dev/null || true
  fi
)
printf 'GitHub user: %s\nRepository permission: %s\n' \
  "${login:-unknown}" "${permission:-unknown}"

permission が write、maintain、または admin の場合に限り、直接メンバーの方法を使用します。この方法を続ける前に、値を表示せずに、Bun が AWS_ACCESS_KEY_ID と AWS_SECRET_ACCESS_KEY の両方を読み取れることを確認してください。

(
  cd packages/docs
  bun -e 'process.exit(Bun.env.AWS_ACCESS_KEY_ID && Bun.env.AWS_SECRET_ACCESS_KEY ? 0 : 1)'
)

作業ディレクトリが packages/docs であるため、Bun が packages/docs/.env を読み込みます。このサブシェルは意図的なものです。Element のプレビューアップロードでは packages/remotion-media/.env を使用しません。これらには汎用の upload-r2 または offload-r2 スキルを使用しないでください。

リポジトリへの書き込み権限があるコントリビューターがどちらかの認証情報を持っていない場合は、そこで中止し、プレビューを直接アップロードするための認証情報が必要であることを伝えてください。そのようなコントリビューターのために、一時的なアセットを黙ってコミットしてはいけません。

権限が read、triage、none、不明の場合、または GitHub の照会に失敗した場合は、外部コントリビューターの方法を使用します。この方法ではアップロード用の認証情報は必要ありません。

3. 提出内容をレビューする

完成したソース、MDX ページ、中央の定義を、Element の貢献ガイドおよびscaffold-element スキルの技術要件に照らしてレビューします。プレースホルダーの内容を解消し、説明、表示名、コントリビューター、寸法、再生時間、installationMode、宣言された依存関係、プレビューのパディング、ポスターフレームを確定します。

レンダリングとレビューの間は、ローカルのレビュー用 URL をそのままにします。

• posterUrl: '/elements/<category>-<slug>-preview.png'
• videoUrl: '/elements/<category>-<slug>-preview.mp4'
• ページのフロントマターにある image: /elements/<category>-<slug>-preview.png

プレビューアセットは標準の背景に合成します。また、Element 自体が透明度に対応している場合も、幅広いブラウザー、ソーシャルカード、埋め込みでの互換性を確保するため、MP4 を使用します。

Element に Studio で編集可能なコントロールがある場合は、インタラクティビティのベストプラクティススキルを使ってレビューします。

Element が packages/docs で利用できないパッケージをインポートしている場合は、packages/docs/package.json に追加し、bun install を実行して、bun.lock を含めてください。

4. ギャラリーに追加する

• packages/docs/src/components/Elements/element-definitions.ts のエントリーによって、Element が生成された概要ページとカテゴリーライブラリに表示されることを確認します。
• packages/docs/elements-sidebars.ts の該当するカテゴリーに '<category>/<slug>/index' を追加します。

サイドバーの順序を維持してください。カテゴリーインデックスに手動でリンクを追加しないでください。ビジュアルライブラリと生の Markdown ライブラリは、中央の定義から生成されます。タスクで新しいカテゴリーを明示的に追加する場合は、フィルター済みの ElementLibrary を表示するインデックスを作成し、この手順の一環としてサイドバーグループを追加してください。

ギャラリーへの登録を完了とする前に、Element が概要ページ、カテゴリーのページ、生成された生の Markdown の各ルートに表示されることを確認してください。

packages/docs/src/remotion/Root.tsx は編集しないでください。Element のコンポジションは中央の定義から生成されます。

5. プレビューをレンダリングして確認する

提出する Element だけをレンダリングします。

cd packages/docs
bun run render-element-previews --element=<category>/<slug>
cd ../..

すべての Element をレンダリングし、プレビュー出力全体を消去するため、Element のフィルターを指定せずに render-element-previews を実行しないでください。

次のファイルを確認し、目視確認用に両方のパスを開発者に伝えてください。

• packages/docs/.element-previews/<category>/<slug>/preview.png
• packages/docs/.element-previews/<category>/<slug>/preview.mp4

両方のプレビューが正しいと開発者が明示的に確認するまで、作業を止めて待ってください。承認を受ける前に、アセットをアップロードしたりコピーしたりしないでください。

6A. メンバーからの直接提出の場合：レンダリング結果をアップロードする

プレビューを packages/docs/static/elements にコピーしたり、Git に追加したりしないでください。確認済みのレンダリング結果をそのままアップロードします。

cd packages/docs
bun run upload-element-preview \
  --element=<category>/<slug> \
  --source=render
cd ../..

アップローダーは、ローカル URL、署名、合計サイズ、アップロード後のサイズ、公開 HTTP レスポンス、コンテンツタイプを検証します。packages/docs から実行すると、Bun は packages/docs/.env を読み込みます。両方のアップロードが検証されるまで、先に進まないでください。

その後、次の作業を行います。

1. packages/docs/src/components/Elements/element-definitions.ts のローカルの posterUrl と videoUrl を、出力された https://remotion.media の URL に置き換えます。
2. packages/docs/elements/<category>/<slug>/index.mdx のローカルの image URL を、公開ポスター URL に置き換えます。
3. packages/docs/static/elements に該当するファイルが存在しないことを確認します。

アップロード後に Element の見た目が変わった場合は、ローカル URL に戻し、再度レンダリングして確認したうえで、直接アップロードをやり直し、その後に公開 URL に戻してください。

6B. 外部からのコントリビューションの場合：確認用アセットを追加する

R2 にアップロードしたり、ローカル URL を置き換えたりしないでください。確認済みのファイルを、指定されたフラットな確認用パスにコピーします。

mkdir -p packages/docs/static/elements
cp packages/docs/.element-previews/<category>/<slug>/preview.png \
  packages/docs/static/elements/<category>-<slug>-preview.png
cp packages/docs/.element-previews/<category>/<slug>/preview.mp4 \
  packages/docs/static/elements/<category>-<slug>-preview.mp4

PNG と MP4 の合計サイズは 10 MiB 以下にしてください。Git の無視対象である .element-previews ディレクトリは追加しないでください。packages/docs/static/elements 内の 2 つのファイルは意図的に追跡対象になっているため、コントリビューターとレビュー担当者に 404 が返らないよう、プルリクエストに含める必要があります。

accept-element スキルは、承認済みのアセットをアップロードし、レビュー後にローカル URL を置き換えます。

7. フォーマットとテスト

変更した TypeScript ファイルと TSX ファイルだけをフォーマットします。通常のファイルは次のとおりです。

bunx oxfmt \
  packages/docs/elements/<category>/<slug>/<slug>.tsx \
  packages/docs/src/components/Elements/element-definitions.ts \
  packages/docs/elements-sidebars.ts \
  --write

cd packages/docs
bun test src/test/elements.test.ts
cd ../..

メンバーからの直接提出の場合、対象を絞ったテストで、正確な公開 URL とローカルの確認用アセットが存在しないことを検証します。外部からのコントリビューションの場合、ローカル URL、フラットな確認用アセット、ファイルシグネチャ、コントリビューション全体のサイズを検証します。

8. リポジトリの最終チェックを実行する

bun run build
bun run stylecheck
git diff --check
git status --short

作業を終える前に、ページが生成された概要ページとカテゴリーライブラリ、生成された生の Markdown、サイドバーに掲載されていること、すべてのチェックに合格していること、意図したファイルだけが変更に含まれていることを確認してください。

メンバーからの直接提出の場合は、検証済みの公開プレビュー URL を 2 つ報告し、プレビューアセットが追跡対象になっていないことを確認してください。外部からのコントリビューションの場合は、追跡対象の確認用アセットを 2 つ報告し、プルリクエストを作成する場合は「Allow edits from maintainers」を有効のままにしてください。どちらの場合も、レビュー用のコントリビューションの準備が整った時点で作業を終了してください。