studio-dev

Studio の開発

Studio 自体を実装またはレビューする際は、以下の原則に従ってください。通常の Studio と remotion.new の Browser Studio が対象です。

楽観的な操作

すべての操作で楽観的更新を行う必要があります。サーバーリクエスト、ファイルシステムへの書き込み、codemod、ホットリロードを待つのではなく、ユーザーの意図をすぐに反映してください。結果がまだわからない操作では、完了したと誤解させることなく、保留中の状態をすぐに表示してください。

楽観的な状態を永続化された結果と整合させてください。更新されたソース／設定が HMR を通じて届くまで状態を維持し、失敗時にはロールバックして、エラーを表示してください。遅れて届いたレスポンスやロールバックによって、新しい編集や取り消しが上書きされないようにしてください。既存のミューテーションキューと履歴の仕組みを使用してください。enqueueStudioSourceMutation と 楽観的なコンポジションメタデータを参照してください。

エージェント、インタラクティブ操作、コードの同等性

• すべての状態とアクションを、プロジェクトコードまたは WebMCP を通じてエージェントから利用できるようにしてください。すでにプロジェクトのソースで編集可能なものは、この要件を満たしています。たとえば、シーケンスの移動やトリミングには WebMCP ツールは必要ありません。ソースに基づく編集アクションと同じ機能を提供するだけの重複ツールは追加しないでください。
• プロジェクトのソースで表現できない一時的な Studio の状態やアクション（再生、選択、保留中のレンダリングジョブ、レンダリングのキャンセルなど）は、WebMCP を通じて公開してください。WebMcp.tsx の既存の登録方法と、該当する機能のツールに従ってください。
• 新しい WebMCP ツールと、その入力または出力の変更はすべて、保留中の状態、結果、利用可能なモードを含めて、WebMCP のドキュメントに記載してください。
• ソースに基づく編集はすべて、インタラクティブ操作とプロジェクトコードの編集の両方で機能させてください。これにより、エージェントからも操作できるようになります。コードを直接変更した場合も、ホットリロード後に正しく反映されるようにしてください。WebMCP の編集ツールがある場合は、UI と同じソースミューテーション／履歴経路を使用させてください。信頼できる情報源を複数に分けないでください。
• 検証、楽観的な動作、取り消し／やり直し、エラー、モード制限は、インタラクティブ操作と WebMCP の両方の入口で一貫させてください。ツールの登録時に古いスナップショットを取得しておくのではなく、ツールの実行時に現在の状態を読み取ってください。

Studio の4つすべてのモードを考慮する

機能の利用可否を判断する際は、studio-modeを読んでください。新しいアクションとその WebMCP の入口が、以下の4つすべてのモードで適切に機能するか確認してください。

モード	考慮する機能
通常のインタラクティブ Studio	Studio サーバーへの接続。ソース編集、codemod、依存関係のインストール、サーバーレンダリング、サポートされている「Open in」アクション。
プレビューサーバーが切断された通常の Studio	previewServerConnected が false。実質的に読み取り専用ですが、クライアント側のレンダリングは引き続き利用できます。
読み取り専用のデプロイ済み Studio	サーバーに接続されていません。サーバー依存のアクションを非表示または無効にしてください。「Open in」アクションでサポートされるのは GitHub のみです。
Browser Studio（remotion.new）	ユーザーには見えない仮想ファイルシステムを持つ iframe 内で実行されます。codemod と依存関係のインストールをサポートしますが、「Open in」アクションは利用できません。

既存の機能チェックを使用してください。デプロイ済みの Studio が必ずしも読み取り専用とは限りません。Browser Studio には独自のミューテーション機能があります。サポートされていない UI アクションは非表示または無効にし、エージェント経由で実行された場合にも同じ制限を適用してください。

iframe のホバーの不具合を防ぐ

ホバーの不具合とは、ポインターが Studio の iframe から離れた後も、古いホバー状態が残ることです。 ブラウザーが pointerleave／マウスの離脱イベントを取りこぼすと、イベント駆動の React のホバー状態がそのまま残り、ポインターが離れた後もボタンやメニューの行がハイライトされたままになったり、ツールチップが表示され続けたりします。issue #9886 とツールチップとホバーの修正を参照してください。

• 見た目だけのホバースタイルには、hoverable.ts の HOVERABLE_CLASS_NAME と hoverableStyle() を使って、CSS の :hover だけで制御してください。既存のホバーグループクラスを使って、行のアクションを表示してください。色、背景、表示／非表示を変更するだけの目的で React のホバー状態を導入しないでください。
• 遅延メニューやツールチップなど、JavaScript の動作がホバーに依存する場合は、observeHover() を使ってください。離脱イベントの取りこぼし、ウィンドウのフォーカス喪失、表示状態の変化、および Browser Studio が転送する remotion-browser-studio-pointerleave イベントからの復帰に対応します。クリーンアップ時と非表示時に、オブザーバーを破棄し、保留中のタイマーをキャンセルしてください。
• 選択中、キーボードフォーカス中、メニューが開いている状態を意図せず変更しないでください。親の行がホバーされただけで、ネストされたアクションがホバー状態にならないようにしてください。アクションはキーボードとタッチでも使えるようにしてください。
• 通常の Studio に加えて iframe 内でも確認してください。ホバーし、フレームから出て再び入り、ウィンドウのフォーカスを切り替えます。ハイライトと保留中または表示中のツールチップが正しく消える必要があります。browser-studio.test.ts にある既存の回帰テスト clears hover backgrounds even if pointer leave events are lost は、離脱イベントを意図的に抑制して、この不具合を再現します。

Studio のデザインと CSS リセットに従う

UI を追加または変更する際は、studio-css-reset と no-pointer を読んでください。

• 既存の Studio コントロール、レイアウト、操作パターンの中から、最も近いものを再利用してください。色、フォント、フォントサイズ、コントロールのサイズ、余白、境界線、アイコン、およびホバー、フォーカス、選択中、無効時の見た目を合わせてください。独自のビジュアル言語を導入するのではなく、colors.ts の共有トークンと既存コンポーネントのスタイルを使ってください。
• .css-reset, .css-reset * ルールは、親だけでなくリセットコンテナー内のすべての子孫要素に適用されます。フォントサイズ、行の高さ、色、フォントファミリー、背景、ボックスサイズがリセットされます。親のテキストスタイルだけでは、子要素ごとのリセットを上書きできません。テキストや SVG を描画する要素にスタイルを設定するか、適切な子孫セレクターを使ってください。ネストされたラベルやアイコンを含め、計算済みスタイルを確認してください。
• ツールチップ用に DOM の title 属性を追加しないでください。title="" も使用しないでください。ツールチップコンポーネントを使用してください。既存の Studio 実装では、ActionTooltip.tsx に ActionTooltip と ClippedTextTooltip が用意されています。アクセシブルなラベルとキーボードフォーカスの動作を維持してください。
• Studio のコントロールやリンクに cursor: 'pointer' を使わないでください。cursor: 'default' を使ってください。共有のホバーと :focus-visible の規約に従い、キーボードフォーカスのインジケーターが常に見えるようにしてください。

パフォーマンスを低下させない

studio-perfをお読みください。値がアクション中にのみ必要な場合は、既存の安定した ref または命令型 getter を通じてコンテキストを取得することを優先してください。購読した後にリアクティブなコンテキスト値を ref にコピーしても、購読による再レンダリングは回避できません。

たとえば、イベントハンドラーや WebMCP ツール内では、所有コンポーネントに Internals.Timeline.useTimelinePosition() をインポートするのではなく、imperative-state.tsからgetCurrentFrame()を読み取ります。フレームごとに表示内容を更新する必要がある最小単位のリーフでのみ、フレームを購読してください。メモ化された境界をまたいで、props とコンテキスト値を安定させてください。

機能を追加するときはパフォーマンスをテストしてください。ソースコードの確認だけでは不十分です。ベースラインを記録し、変更後に同じ代表的な操作を再度行ってください。その機能がフレーム更新に関わる場合は、再生やスクラブも含めてください。レンダーやコミットの測定にはreact-scanを使用し、React 以外の処理にはブラウザーのプロファイリングを使用してください。コンポジション、ビューポート、繰り返し回数を同等に保ってください。不要なレンダー、コミット時間、操作のレイテンシ、再生の滑らかさなどを確認し、回帰があれば完了前に解消してください。測定結果と検証上の制約を報告してください。

機能を検証する

ソースに基づく編集は、UI とコードの直接変更の両方で試してください。一時的な Studio の状態や操作に対応するツールがある場合、または必要な場合は、WebMCP も試してください。即時のフィードバック、HMR 後の永続性、失敗からの復旧、履歴に含まれる編集の取り消し／やり直しを確認してください。また、各モードで利用可能かどうかと、上記に関連するホバー、フォーカス、カーソル、CSS リセットの動作も確認してください。

Studio のコードを変更した場合は、パッケージのビルドと関連する既存のチェックを実行してください。

bunx turbo run make --filter='@remotion/studio'
bunx turbo run lint test --filter='@remotion/studio'

変更が影響する境界をまたぐ場合は、影響を受けるパッケージと既存のブラウザー回帰テストも含めてください。テストを追加または変更する場合は、writing-testsに従ってください。