Motion Forge: Code-to-Video (Code2Video) 産業グレード制作スキルメインガイド

このプロジェクト自体が、完全に自己完結型で、独立して配布可能な Code-to-Video 産業グレードスキルです。システムは Remotion 4.x + React 19 + TypeScript + Three.js (@remotion/three) + Canvas 2D + SVG を統合したマルチテクノロジースタックカーネルを基盤とし、265 の原子化モーションカード（9 つの専門領域に分類）、基盤ビジュアル基盤（_shared/）、ビジュアルローカルデバッグワークベンチ、および厳格な G1/G2 2段階品質ゲートを内蔵しています。

コアアーキテクチャと5つの技術原則
2段階品質ゲート標準作業手順 (G1 & G2 Gates SOP)
マルチシナリオ独立パイプラインシステム (Scenario Pipelines)
265 のモーションカード全資産とディレクター意思決定の心得 (Creative & Open Motion Design)
Film IR ストーリーボードプロトコルとマルチテクノロジースタックレンダリング仕様
CLI ツールチェーンライフサイクルとローカルワークベンチインタラクション
最終納品とトラブルシューティングチェックリスト

一、コアアーキテクチャと5つの技術原則

動画のストーリーボードやレンダリングコードを作成する前に、Agent は以下の5つの不可侵な設計規律を遵守しなければなりません。

絶対的な疎結合とローカルクロックの原則 (Local Frame Only)：
- 各シーン（Scene）はローカルフレーム番号（frame 0 から durationInFrames）のみを使用し、シーン内で全編の絶対タイムスタンプ（absoluteFrame や from）をハードコードしてはなりません。全編の絶対クロックは Core 層がタイムラインの累積によってコンパイルします。
- シーン間で内部コンポーネントを相互に import してはいけません。すべてのシーンで共有される状態は、Film IR の props を介して渡されなければなりません。
- モーションカード（Cards）はモーション数学とビジュアルロジックのみを担い、プロジェクト固有の具体的なコピーやビジネス画像パスをカード内にハードコードしてはいけません。
純粋関数フレームクロック決定論 (Frame-Deterministic Execution)：
- すべてのアニメーション変形、オブジェクト移動、透明度変換は、現在のローカルフレーム frame の純粋な数学的计算関数でなければなりません：$Value = f(frame)$
- ブラウザの requestAnimationFrame、setInterval、setTimeout や外部の自己実行タイムラインの使用は厳禁です。
- シードなしの Math.random() の使用は厳禁です（Remotion 内蔵のシード付き random(seed) を使用しなければなりません）。これにより、同じフレームがいつシークレンダリングされても、画面のピクセルが 100% 冪等で一致することを保証します。
リアルな素材のローカルクロージャの原則 (Local Assets Only)：
- レンダリングエンジンは、動画合成において外部の未検証リモート URL に直接接続することを禁止します（ネットワーク断、ホットリンク防止、リクエスト遅延を防ぐため）。
- 外部画像、動画クリップ、オーディオ音楽は、Provider が事前にダウンロードしてプロジェクトのローカルディレクトリに保存し、assets.json に統一登録管理されなければなりません。不足している素材は明示的にマークされ、ユーザーに報告されなければならず、黙ってプレースホルダーや偽データでごまかしてはいけません。
マルチテクノロジー統一フレームレンダリングの哲学 (Multi-Tech Rendering)：
- タイポグラフィとインタラクティブ UI は HTML/CSS + Spring エラスティックアニメーション を使用します。
- 幾何学的輪郭、接続線、チャート、マスクは SVG パス補間 を使用します。
- パーティクル、流体、数万の高頻度移動点は Canvas 2D を使用します。
- 3D 立体モデル、空間ライティング、3D カメラワークは Three.js (@remotion/three) を使用します。
- すべてのテクノロジーパスは、Remotion の useCurrentFrame() フレーム同期クロックに統一的に従います。
プロジェクトエンジン独立化の原則 (Standalone Project)：
- このスキルディレクトリは、フロー仕様、モーションカードリファレンス、汎用ランタイムテンプレート、forge create プロジェクトジェネレーターのみをホストします。ユーザープロジェクトのすべてのコンテンツ（core/、cards/、scenes/、public/ アセット、film.json、package.json、ワークベンチ、レンダリング成果物）は、ユーザープロジェクト自身のディレクトリに配置され、独立した npm ci、独立した検証とレンダリングを行い、スキルディレクトリから独立して実行可能でなければなりません。
- プロジェクト固有のコード/アセットをスキルディレクトリに書き込んだり、プロジェクトコンテンツをスキルディレクトリにシンボリックリンクでマウントしたりしてはいけません。forge create は、ランタイム、モーションカード、デフォルトの Film を実際のファイルコピーとしてプロジェクトにコピーし、プロジェクト固有のシーンコンポーネントはプロジェクトの scenes/ に直接書き込まれます。
- スキルディレクトリ内の output/projects/ と CLI のゲートプロセスは、スキルに付属するサンプルにのみ適用されます。実際のプロジェクトの G1/G2 レビューレコードはプロジェクトディレクトリ内に保存されます。
新規プロジェクト初期化（入力：プロジェクト絶対パスと入力アセット；出力：依存関係を独立してインストール可能なプロジェクトスケルトン）：
1. テンプレートディレクトリで npm run forge -- create --dir /absolute/project --input <入力> [--audio-kind song|instrumental] [--name <id>] を実行します。ターゲットはテンプレート外の空ディレクトリである必要があります。このコマンドは、完全なランタイムコピーを生成し、ローカルアセットを public/assets/<id>/ にコピーし、プロジェクトドラフトを作成します。
2. 初期化後、PROJECT_ROOT に入り、npm ci、npm run validate -- --project <id> を実行します。実際のプロジェクトのコード、アセット、Film IR、承認ステータス、出力は、すべて PROJECT_ROOT/output/projects/<id>/ と PROJECT_ROOT/public/ に自己完結します。
3. ローカルアセットは public/ 以下の相対パスのみを使用します。リモートソースはソースメタデータレコードとしてのみ使用され、レンダリング参照には入りません。アセットが不足した場合は直ちに停止し、プロジェクトが絶対パスや外部シンボリックリンクで独立したプロジェクトを偽装することを許してはいけません。
4. 後続のすべてのコマンドは、まず cd <PROJECT_ROOT> を実行し、次にプロジェクト内のスクリプトを実行します。レンダリング成果物とレビューレコードはテンプレートディレクトリに書き戻してはいけません。
5. テンプレートディレクトリは create 時にのみ読み取り専用ソースとして使用されます。生成後、プロジェクト内の import、npm 依存関係、スクリプト、アセット参照は、そのディレクトリを再度指してはいけません。

失敗ブランチと回復パス

トリガー条件	一次対応	それでも失敗する場合、または変更が必要な場合
プロジェクトルートディレクトリが不明、またはスキルディレクトリに書き込まれようとしている	書き込みを停止し、ユーザーにプロジェクト絶対パスを確認。後続のコマンドはすべてそのプロジェクトディレクトリを作業ディレクトリとする	明確なパスが得られるまでは、方案の議論のみ行い、ファイルを作成しない
必要なアセットが不足している、読み取り不可、または権限が不明	具体的なパスと理由を報告し、影響を受けるシーンを一時停止。黙ってプレースホルダーを置いたり、アセットを捏造してはいけない	ユーザーがアセットを補充するか、代替案を明確に承認し、G1 を併せて修正する
G1 が確認されていない、または変更が要求されている	設計段階に留まり、`film.json` と `design-review.md` を修正する	サンプルショットを作成せず、G1 承認コマンドを実行しない
サンプルショットで黒画面、音声と映像のずれ、テキストのはみ出し、または品質不良	G2 ロックを維持し、特定のシーンを特定して修正し、サンプルショットのみを再レンダリングする	再度 G2 を提出する。全編レンダリングでサンプル検証を代替してはいけない
承認済みのナラティブ、レイアウト、尺、アセット、またはオーディオが変更される	元の G1/G2 結論を無効にし、G1 に戻って影響範囲を再確認する	新しい G1 通過後、有声サンプルショットを再作成し確認する
ビルド、検証、またはレンダリングコマンドが失敗する	完全なログを保持し、根本原因を修正した後、同じコマンドを再実行する。エラーをコメントアウトしたり、検証をスキップしたりしてはいけない	それでも通過しない場合は、納品を停止し、ブロッキング項目と完了した検証を明確に報告する
独立性スキャンで外部絶対パス、`file:` 依存関係、またはスキルディレクトリを指すシンボリックリンクが発見される	必要なコードまたはアセットをプロジェクトに実際にコピーし、プロジェクト内参照に変更する	隔離されたコピーで再インストールしレンダリングする。未通過の場合は、独立して実行可能と宣言してはいけない

二、2段階品質ゲート標準作業手順 (G1 & G2 Gates SOP)

Agent が「空想でコードを積み上げ、深刻な計算リソースの浪費と期待値の乖離を引き起こす」ことを防ぐため、システムは**2段階確認ゲート（Two-Gate Review）**を強制します。ゲートをスキップして直接全編をレンダリングしてはいけません！

[ユーザー入力] 
   ↓
[要件分析 & 素材準備] 
   ↓
[Film IR ドラフト作成] 
   ↓
【🔴 CHECKPOINT G1：ストーリーボードとデザイン確認】→ ユーザーに整形されたスクリプトとビジュアルテーブルを提示し、STOP して承認を待つ
   ↓ (ユーザー確認後、npm run forge -- approve-design を実行)
[実際の有声サンプルショットを作成] 
   ↓
【🔴 CHECKPOINT G2：有声サンプルショット確認】→ 代表的なショットの動画をレンダリングし、ユーザーが実際の視聴覚品質と音声と映像の同期を確認。STOP して承認を待つ
   ↓ (ユーザー確認後、npm run forge -- approve-sample を実行)
[全編コードアセンブリとバッチレンダリング]
   ↓
[最終納品 (MP4 + 編集可能なプロジェクト + ワークベンチ)]

1. G1 ゲート：ストーリーボードとビジュアルデザイン確認 (Design Review)

複雑なレンダリングコードを作成する前に、Agent はまず《G1 ストーリーボードとビジュアルデザイン案》を完成させ、整形された Markdown レビュー文書をユーザーに提示しなければなりません。少なくとも以下を含みます：

基本属性：動画タイプ、ターゲットオーディエンス、アスペクト比（横 16:9 / 縦 9:16）、目標総尺とフレームレート（例：30fps）；
ビジュアルテーマ：メインカラー、背景色、テキストメインカラー、ハイライト強調色（Accent）、タイポグラフィフォントファミリー；
メインクロック選定：ナレーションアライメント / 歌詞アライメント / インストゥルメンタルビートグリッド / テキスト読了時間；
ストーリーボード詳細テーブル（以下の表形式に厳密に従ってユーザーに提示しなければなりません）：

シーン番号	ショット名	ナラティブ目的とセマンティクス (Semantic)	ナレーション	実際の画面テキスト (On-Screen Text)	画面説明	プライマリモーションカード (Primary)	カメラカード (Camera)	トランジションカード (Transition)	ローカル尺 (Frames/Sec)
S01	開篇破局	Hook：サスペンスを生む	なぜ9割の企業AI変革は、最後にデモ段階で止まってしまうのか？	"なぜ 90% の企業AI変革は失敗に終わるのか？"	中央に巨大でコントラストの高いタイトル + 赤い警告発光背景パネル	`typography/halation-bloom`	`camera/slow-push`	`transition/cube-rotate`	90f (3.0s)
S02	データ表示	Data 証明：悲惨な統計を示す	まず2つの数字を見てみよう。78% がおもちゃ段階で止まり、12% がマイナスのリターンを生んでいる。	"78% がおもちゃ段階に留まる12% がマイナスのROI"	左右2列比較パネル + 動的数字と砂落としチャート	`data/particle-sand-fill`	無し	`transition/whip-pan`	150f (5.0s)

🔴 CHECKPOINT · STOP：ユーザーに提示後、このラウンドを終了し、ストーリーボード計画に同意するかどうかを尋ねなければなりません。同じラウンドで承認、サンプルショットの作成、または全編レンダリングを実行してはいけません。
通過シグナル：ユーザーが後続の返信で G1 を明確に確認した場合のみ、Agent は PROJECT_ROOT で以下を実行します：
```
npm run forge -- approve-design --project <project-id>
```

2. G2 ゲート：有声サンプルショット確認 (Sample Review)

G1 確認後、すぐに全編をレンダリングしてはいけません。全編の中で最も代表的で、視覚的に最も複雑で、実際の音声・映像要素を含む 1 つのシーン（通常は Hook ショットまたは核心的なクライマックスショット）を選択し、サンプルショット動画として作成・レンダリングしなければなりません：

レンダリングコマンド：

npm run forge -- render --project <project-id> --scope sample

品質チェックポイント：
- 音声と映像は正確に同期しているか？字幕は発音開始の 1～2 フレーム前に入場しているか？
- 画面テキストに隠れ、改行による破壊、安全領域からのはみ出しはないか？
- モーション速度と音楽の感情はマッチしているか？呼吸感はあるか？
🔴 CHECKPOINT · STOP：実際のサンプルショット動画と品質チェック結果を提供した後、このラウンドを終了し、ユーザーのレビューを待たなければなりません。自分でユーザーに代わって G2 を承認してはいけません。
通過シグナル：ユーザーがサンプルショットを明確に確認した場合のみ、PROJECT_ROOT で以下を実行します：
```
npm run forge -- approve-sample --project <project-id>
```
G2 承認が完了した後にのみ、プロジェクトステートマシンは全編最終レンダリングの権限を解除します！

三、マルチシナリオ独立パイプラインシステム (Scenario Pipelines)

異なる入力タイプのエンドツーエンド処理ロジックは、独立したガイドファイルに分割され、pipelines/ ディレクトリに格納されています。Agent はユーザー入力の実際のタイプに応じて、対応するガイドを参照する必要があります：

シナリオタイプ	適用される入力と動画タイプ	対応する独立パイプラインガイドファイル
シナリオ 1：URL リンクから動画へ	ブログ、WeChat公式アカウント、SaaSランディングページ、技術文書、ニュースリリース	`pipelines/url-to-video.md`
シナリオ 2：純粋な音楽音声から動画へ	純粋な楽器、エレクトロニック、壮大な伴奏音楽；哲学的作品、ビートカット、エッセイ	`pipelines/instrumental-to-video.md`
シナリオ 3：歌（ボーカル入り）から動画へ	完全な歌（歌唱＋伴奏）；ダイナミック歌詞MV、音楽ナラティブショートストーリー	`pipelines/song-to-video.md`
シナリオ 4：純粋なテーマから動画へ（自主計画）	一言テーマ/命題；深い科学解説、人文哲学、ビジネスインサイト、一般教養ショート動画	`pipelines/theme-to-video.md`
シナリオ 5：ユーザーマルチモーダルアセットミックス	ユーザー自身の画像、スクリーンショット、ショート動画クリップ、ナレーション録音；製品デモ、Vlog	`pipelines/assets-to-video.md`
コンテンツ企画共通仕様	テーマ/URL の構造化企画、ナラティブアーク、ファクトチェック、Film IR 変換	`pipelines/content-planning.md`
シナリオ拡張ガイド	新しい入力（例：テーブル、PPT、2人ポッドキャストなど）の拡張方法	`pipelines/extending-pipeline.md`

四、265 のモーションカード全資産とディレクター意思決定の心得 (Creative & Open Motion Design)

システムに内蔵された 265 の原子化モーションカード は、Agent が動画を制作するためのビジュアルブラシです。

1. オープンな選択原則：制限のない芸術的想像力

硬直した適用や教条的な制限は厳禁：本システムは、「特定の動画タイプは特定のカードを使用しなければならない」とは決して限定しません。逆に、Agent がコピーの感情的なテンション、ナラティブのサスペンス、聴覚的なビートに基づいて、自律的に組み合わせ、革新することを奨励します。
Agent は真のビジュアルディレクター：モーションカードはモジュール式のブロックセットです。テクノロジー製品向けの interaction/command-palette-summon を、古代の思想家の「知識検索」を表現するために使うこともできます。また、空港の機械式フリップボード typography/split-flap-flip を、時空を超えた移動や生命のカウントダウンを表現するために使うこともできます。
パラメータを自由に無段階調整：各カードは豊富なパラメータ（スプリングの硬さ、重力の大きさ、ブラーの半径、パーティクル数など）を公開しており、Agent は film.json の params で自由にカスタマイズされたモーション感覚を設定できます。

2. 9 つの領域モーション分類資産の全容 (265 カード)

すべての 265 カードは標準化されたカプセル化が完了しており、横画面・縦画面のデュアルモード自動適応をサポートし、領域ごとに完全に凝集・疎結合されています：

カテゴリ (Kind)	ディレクトリとカード総数	コアビジュアル機能	代表的なカード資産 (コード内で直接参照可能)
`camera` (カメラ)	`cards/camera/` (21枚)	空間的なドリー、パン、チルト、レンズ焦点距離、透視歪み。フラットな画面に奥行きのある空間を構築	`dolly-zoom` (ヒッチコックズーム), `slow-push` (深いスロープッシュ), `slow-pull` (遠ざかるプル), `shot-crash-zoom-punch` (インパクトズームパンチ), `space-camera-moves` (3D空間ロール), `tension-camera-moves` (地平線傾斜テンション), `overhead-camera-moves` (俯瞰大パン), `whip-pan` (ウィップパン), `orbit-drift` (オービットドリフト)
`typography` (タイポグラフィ)	`cards/typography/` (52枚)	タイトル入場、字幕リズム、キーフレーズ強調、コード端末、文字デコード	`split-flap-flip` (空港ビンテージ機械式フリップ), `scramble-decode` (スクランブルマトリックスデコード), `halation-bloom` (フィルム赤ハレーション), `type-rhythm-sync` (ビート字幕同期), `tracking-expand-reveal` (字間拡大表示), `terminal-typewriter` (ハッカー端末タイプライター), `keyword-reveal` (キーワードフェードイン), `quote-card` (エレガントな引用カード), `highlighter-sweep` (蛍光ペンライン), `cel-flash-stomp` (ストップモーションインパクトフラッシュ)
`interaction` (コンポーネントとインタラクション)	`cards/interaction/` (58枚)	スキューモーフィズム、インタラクティブパーツ、フローティングカード、ポップアップ、カーソルコラボレーション	`command-palette-summon` (Cmd+K フローティング召喚), `stack-reveal` (カードスタック展開), `popup-book-rise` (ポップアップブック立ち上がり), `masking-tape-slap` (マスキングテープ貼り付け), `autolayout-gap-dial` (オートレイアウトダイヤル), `carousel-3d` (3Dカルーセル), `theme-switch-moves` (テーマ切り替えリップル), `collab-cursor-moves` (マルチカーソルコラボ), `type-and-filter` (タイプ＆フィルター), `glassmorphism-card` (ガラスモーフィズムパネル)
`data` (データとチャート)	`cards/data/` (20枚)	物理パーティクル堆積、動的折れ線・棒グラフ、ダッシュボード、数字スプリント	`particle-sand-fill` (重力砂落とし堆積), `counter-confetti` (数字スプリント+紙吹雪), `number-counter` (数字カウンター), `chart-grow` (棒・折れ線グラフ成長), `chart-live-moves` (リアルタイムデータストリーム), `gauge-readout-moves` (ゲージ針ジャンプ), `before-after-slider-scrub` (ビフォーアフタースライダー), `scroll-brake-moves` (スクロールブレーキストップ)
`effects` (エフェクトとライティング)	`cards/effects/` (22枚)	ハレーションライトスイープ、HUD スキャン、3D 自旋結晶、雰囲気パーティクルフィールド	`three-crystal` (Three.js 3D自旋結晶), `light-play-moves` (ライトスイープ拡散), `spotlight-sweep-moves` (スポットライトスイープ), `glow-flyline-moves` (グローライン軌跡), `fui-hud-moves` (テクノロジーワイヤーフレーム展開), `impact-feedback` (アニメインパクト衝撃波), `canvas-particles` (数万の流動パーティクル), `flying-words` (ワードクラウドように飛び交う)
`rhythm` (編集とリズム)	`cards/rhythm/` (8枚)	リズムによるフレーム間引き、フラッシュカット、スプリットスクリーン対決、モンタージュカット	`beat-cut-moves` (ビートフラッシュカット), `speed-ramp-freeze` (スピードランプフリーズ注釈), `quad-split-parallel-scenes` (4分割パラレルビュー), `panel-grid-moves` (漫画コマ割り再配置), `rhythm-interrupt-moves` (ジャンプカットインパクト), `trailer-grammar-moves` (予告編インパクトブラック)
`commercial` (コマーシャルショット)	`cards/commercial/` (43枚)	製品プレゼンテーション、ブランドオープニング/エンディング、イントロ、最終エンドカード	`hook` (ペインポイントフック), `price-card` (価格プランカード), `features` (機能リストフロー), `store-card` (店舗・ロケーション案内), `fact-sheet` (ファクトシート), `brand-ink-open` (インク拡散オープニング), `logo-shrink-wordmark-lockup` (ロゴシュリンクエンドカード), `ui-to-brand-morph` (UIからブランドロゴへのモーフィング)
`transition` (トランジション)	`cards/transition/` (26枚)	ショット境界における時空間の変化と視線の遷移。唐突なジャンプカットを排除	`cube-rotate` (3Dキューブ回転), `clock-wipe` (時計ワイプ), `bubble-swarm-takeover` (バブル群マスク), `color-block-step-wipe` (カラーブロックステップワイプ), `paper-plane-messenger` (紙飛行機メッセンジャー), `push-through` (プッシュスルー), `whip-pan` (高速ウィップパンブラー), `dark-tunnel` (ダークトンネルトラバース)
`media` (マルチメディア表示)	`cards/media/` (15枚)	外部画像、動画クリップの入場構図、ピクチャーインピクチャー比較	`media-pop-in` (軽快ポップイン), `split-compare` (左右スプリットスライダー比較), `svg-path` (ベクターパス延長), `video-pip-float` (フローティングピクチャーインピクチャー), `photo-polaroid-scatter` (ポラロイド写真散乱)

ベース基盤 (cards/_shared/)：全ライブラリ共通のレンダリングプリミティブ（例：SpeedBlur モーションブラー、softShadow 2層物理ソフトシャドウ、Stage ステージライトリフレクター）と商用タイポグラフィのフォントサイズ自動適応計算を提供します。独立したカードとして外部には公開されません。

3. 6 つの動画タイプのクラシックなインスピレーションコンビネーションパラダイム (あくまで参考、自由に革新)

以下は、一般的なスタイルのインスピレーション組み合わせの参考であり、固定ルールではありません。Agent は実際の創造性に基づいて自由にミックス＆マッチできます：

科学解説とハードコア教養 (Science Explainer)：
- インスピレーション組み合わせ：typography/scramble-decode（文字デコードで幕開け）+ data/particle-sand-fill（物理砂落としで規模を示す）+ media/svg-path（概念の線で結ぶ）+ transition/color-block-step-wipe。
哲学的思索と深遠なエッセイ (Philosophical Essay)：
- インスピレーション組み合わせ：typography/halation-bloom（ハイライトフィルムハレーション）+ camera/dolly-zoom（空間奥行きへの没入感）+ typography/quote-card（エレガントな引用）+ effects/canvas-particles（微かな浮遊塵）。
テクノロジー製品と機能発表 (Product Promo)：
- インスピレーション組み合わせ：effects/three-crystal（3D コンポーネントお披露目）+ interaction/command-palette-summon（生産性呼び出し）+ data/counter-confetti（パフォーマンス記録更新）+ transition/cube-rotate。
ビジネス戦略とデータダッシュボード (Business & Strategy)：
- インスピレーション組み合わせ：data/gauge-readout-moves（ゲージ針）+ data/chart-live-moves（曲線成長）+ typography/highlighter-sweep（データマーキング）+ transition/clock-wipe。
音楽の感情とダイナミック MV (Music Story & Lyrics)：
- インスピレーション組み合わせ：typography/type-rhythm-sync（バースビートテキスト）+ typography/cel-flash-stomp（コーラスストップモーションアクセント）+ camera/shot-crash-zoom-punch（インパクトクラッシュ）+ transition/whip-pan。
ビンテージハンドメイドとスクラップブック (Scrapbook & Handcrafted)：
- インスピレーション組み合わせ：interaction/masking-tape-slap（マスキングテープ貼り）+ interaction/popup-book-rise（ポップアップブック立ち上がり）+ typography/split-flap-flip（機械式フリップ）+ transition/paper-plane-messenger。

4. 4 スロットアセンブリ仕様と客観的な品質基準

各ショットは film.json の motion プロパティで、4 つの疎結合スロットをサポートします：

{
  "motion": {
    "camera": { "cardId": "camera/slow-push", "params": { "scale": 1.15 } },
    "primary": { "cardId": "data/particle-sand-fill", "params": { "gravity": 1.2 } },
    "text": { "cardId": "typography/halation-bloom", "params": { "bloomIntensity": 0.8 } },
    "transitionOut": { "cardId": "transition/cube-rotate", "params": { "direction": "left" } }
  }
}

客観的な品質基準（厳守しなければなりません）：
1. 明確なビジュアルフォーカス：同じショット内で、画面には明確な主役が存在する必要があります。激しい primary コンポーネントモーションを使用する場合、カメラワーク camera は安定した呼吸を維持するのが適切です。カメラワークで強い shot-crash-zoom-punch を使用する場合、コンテンツは比較的静的に保ち、動きすぎによる視覚的な眩暈を避ける必要があります。
2. 十分な認知保持時間 (Cognitive Hold Time)：モーションが入場展開を完了した後、画面のテキストとコア構造は、少なくとも 45～90 フレーム（1.5秒～3.0秒）の安定した保持時間を確保し、視聴者が余裕を持って読んで理解できるようにしなければなりません。アニメーションが完了した瞬間にすぐにカットしてはいけません。
3. テキスト長さと画面サイズのマッチング：横画面の1行テキストは 22 文字以内、縦画面の1行は 14 文字以内を推奨します。折り返しによる重なりや、動画の安全領域からのはみ出しを防ぎます。

五、Film IR ストーリーボードプロトコルとマルチテクノロジースタックレンダリング仕様

film.json は、全プロジェクトにおける唯一のセマンティックファクトソースです。

1. 標準 Film IR 構造

{
  "id": "project-slug",
  "title": "プロジェクトビデオタイトル",
  "genre": "explainer",
  "brief": {
    "goal": "コアナラティブ目標",
    "audience": "ターゲットオーディエンス",
    "tone": "トーン",
    "primaryClock": "audio"
  },
  "output": { "width": 1920, "height": 1080, "fps": 30 },
  "theme": {
    "background": "#0a0f1d",
    "foreground": "#f8fafc",
    "accent": "#38bdf8",
    "fontFamily": "Inter, PingFang SC, sans-serif"
  },
  "scenes": [
    {
      "id": "scene-01",
      "title": "ショット名",
      "intent": "ナラティブ意図",
      "semantic": "hook",
      "durationInFrames": 90,
      "onScreenText": ["実際の画面上メインタイトル", "サブタイトル説明文案"],
      "layout": { "kind": "center-headline" },
      "renderer": "html",
      "sceneComponent": "scene/stack-explainer",
      "motion": {
        "camera": { "cardId": "camera/slow-push" },
        "primary": { "cardId": "interaction/stack-reveal" },
        "text": { "cardId": "typography/scramble-decode" },
        "transitionOut": { "cardId": "transition/cube-rotate" }
      },
      "props": {},
      "qa": { "keyFrames": [20, 45, 80] }
    }
  ]
}

2. デュアルモード自動適応メカニズム (16:9 ↔ 9:16)

すべてのシーンとカードは、統一されたレスポンシブスケーリングをサポートします。ショットコードでは、ベース比率のコンテナを使用します：

import React from 'react';
import { useVideoConfig } from 'remotion';

export const AdaptiveStage: React.FC<{ children: React.ReactNode }> = ({ children }) => {
  const { width, height } = useVideoConfig();
  const isPortrait = height > width;
  const baseWidth = isPortrait ? 1080 : 1920;
  const baseHeight = isPortrait ? 1920 : 1080;
  const scale = Math.min(width / baseWidth, height / baseHeight);
  return (
    <div style={{ 
      width: baseWidth, height: baseHeight, 
      transform: `scale(${scale})`, 
      transformOrigin: 'top left',
      overflow: 'hidden'
    }}>
      {children}
    </div>
  );
};

3. マルチテクノロジーレンダリングパスセレクター

film.json の scene.renderer プロパティにより、ショットのレンダリングパスを指定します：

`renderer` 値	適用される技術	典型的なユースケース	参照コードパス
`html`	React 19 + HTML/CSS + SVG	テキストタイポグラフィ、2Dチャート、UIインタラクション	`cards/typography/`, `cards/data/`, `cards/interaction/`
`canvas`	Canvas 2D (useCanvas)	大規模パーティクル、流体、ピクセル操作	`cards/effects/canvas-particles`, `cards/effects/flying-words`
`three`	Three.js (@remotion/three)	3D立体、空間ライティング、3Dカメラ	`cards/effects/three-crystal`, `cards/camera/space-camera-moves`
`media`	画像/動画プレーンオーバーレイ	製品画像ショーケース、動画証拠、人物肖像	`cards/media/`

4. 状態管理とプロップスプロトコル

外部状態の禁止：ショットの props は、film.json の props オブジェクトによって静的に注入されなければなりません。ショット間での React Context、Redux、Zustand の共有は禁止されています。
タイマーの禁止：useEffect 内で setTimeout、setInterval、または外部ライブラリの時間関数を使用してはいけません。すべての時間依存ロジックは useCurrentFrame() から派生しなければなりません。
同期限定：useCallback、useMemo の使用は推奨されますが、任意のフレームで非同期的に状態を更新する useEffect / useLayoutEffect の使用は禁止されています（Remotion のフレームレンダリングモデルに違反するため）。

六、CLI ツールチェーンライフサイクルとローカルワークベンチインタラクション

1. CLI コマンド一覧

# 1. プロジェクト作成（必須の初回ステップ）
npm run forge -- create --dir /absolute/project/path --input <input> [--name <project-id>]

# 2. プロジェクト検証（必要な依存関係とアセットのチェック）
npm run validate -- --project <project-id>

# 3. G1 デザインレビュー承認
npm run forge -- approve-design --project <project-id>

# 4. G2 サンプルショットレンダリング
npm run forge -- render --project <project-id> --scope sample

# 5. G2 サンプルショット承認
npm run forge -- approve-sample --project <project-id>

# 6. 全編レンダリング
npm run forge -- render --project <project-id> --scope full

# 7. ワークベンチ起動
npm run forge -- workbench --project <project-id>

# 8. 全フレーム一括書き出し（デバッグ用）
npm run forge -- frames --project <project-id> --scene <scene-id>

2. ワークベンチ機能

ローカルワークベンチは、localhost:3000 で起動するビジュアルデバッグツールです：

ショットリスト：すべてのショットを時系列で表示。各ショットのサムネイルと継続時間を確認。
単一ショットプレビュー：任意のショットを任意のフレーム位置で seek して個別プレビュー。
パラメータ調整：スライダーで motion.params をリアルタイム調整。変更内容は film.json に反映可能。
レンダリングキュー：バッチレンダリングの進捗を管理。各ショットのレンダリング状態を表示。
検証レポート：G1/G2 の承認状態、アセット完全性、フレーム決定論チェックの結果を表示。

七、最終納品とトラブルシューティングチェックリスト

納品成果物

最終動画ファイル：PROJECT_ROOT/output/projects/<id>/final.mp4（H.264 コーデック、指定解像度）
編集可能なプロジェクト：PROJECT_ROOT/ ディレクトリ全体。npm ci && npm run forge -- workbench で完全に再現可能。
ワークベンチスナップショット：PROJECT_ROOT/output/projects/<id>/workbench-snapshot/ に、各ショットのキーフレーム画像を保存。
制作レポート：PROJECT_ROOT/output/projects/<id>/production-report.md に、使用されたカードのリスト、レンダリング時間、アセットソースを記載。

トラブルシューティングチェックリスト

問題	原因	解決策
黒画面でレンダリングされる	ショットコンポーネントが正しくエクスポートされていない	`npm run validate -- --project <id>` を実行してショットの参照を確認し、`scenes/` のファイル名とコンポーネント名の一致をチェック
アセットが読み込めない	`public/` にファイルが存在しないか、`assets.json` に登録されていない	アセットを `public/assets/<id>/` にコピーし、`assets.json` のエントリを確認
音声と映像がずれる	`primaryClock` が audio に設定されていない、または音声ファイルが正しくない	`film.json` で `brief.primaryClock` を確認し、音声ファイルが正しくトリミングされ、指定された fps と一致しているか確認
フレームがランダムに異なる	`Math.random()` がシードなしで使用されている	すべてのランダム性を Remotion の `random(seed)` に置き換える
G1/G2 承認がスタックする	ユーザーが明示的に承認していない	次のステップに進むために、ユーザーに明確な確認を求める
レンダリングが遅すぎる	ショットの `durationInFrames` が長すぎる、またはエフェクトが重すぎる	ショットの尺を見直すか、`canvas-particles` のパーティクル数を減らすか、`three-crystal` のポリゴン数を減らす

Motion Forge: コードから動画生成 (Code2Video) 産業グレード制作スキル