reanimate は何をしますか?
ユーザーが指し示すものを、参照が動くように再構築し、フレームごとの比較でそれを証明し、比較に合格するまで繰り返します。成果物はユーザーのプロジェクト内のコード加上証拠(数値と比較シート)であり、「だいたい合ってる」では決してありません。
「完了」の定義
ユーザーの言葉から忠実度レベルを選択し、最初のメッセージでそれを明示します。これにより検証基準が決まります。
| レベル | 使用するとき | 一致必須 | 異なってもよい |
|---|---|---|---|
| motion-faithful(デフォルト) | 「このアニメーションをクローンして」「私たちのものを相手のように」「Xと同じヒーローだけど私たちのコピーで」 | トリガー、シーケンスと順序、スターガー、各ステップのタイミング(±80ミリ秒)、イージングファミリー、要素サイズに対する移動方向と距離、レイアウトの比率 | コピー、色、フォント、画像、ブランド詳細 |
| pixel-faithful | 「完全に一致させて」「ピクセルパーフェクトで」「細部まで合わせて」「1:1で」 | 上記すべてに加え、フォント、サイズ、色、間隔、角丸、シャドウ、アセット;フレーム平均不一致 ≤ 2% | ユーザーが変更を依頼しなかったものは一切なし |
| mixed | 「XをクローンしてYを追加して」「相手のものと同じだけど価格帯は私たちのもの」 | 上記いずれかのレベルでクローンした部分 | 追加部分。説明と表示はするが、クローンモーションを壊していないことのみ検証する |
ユーザーは対象を1つのセクション、1つのウィジェット、1ページ、または動画の時間範囲(「最初の3秒」「0:12から0:15」)に絞ることができます。その部分だけを正確にクローンし、ページの残りは取り込みません。
ワークフロー
以下はすべてユーザープロジェクト内の .reanimate/<name>/ に配置します(証拠をコミットしたくない場合は .gitignore に追加)。各ラウンドの成果物は保持します。それらが証拠です。
0. スコープ
キャプチャ前に .reanimate/<name>/spec.md の先頭に3行を記述します。
- Target: 何をクローンするか。ユーザーの言葉で可能な限り正確に(URL + セレクター / 時間範囲 / 「gif内のトグル」)。
- Destination: コードの配置場所と使用するスタック(
package.json、既存のコンポーネント、使用中のアニメーションライブラリを読み、新しいものを導入するのではなくそれに合わせる)。 - Fidelity: motion-faithful、pixel-faithful、またはmixed。mixedの場合は追加リストも含める。
リクエストとリポジトリから推測できるものは推測します。2つの解釈で異なる作業が必要になる場合にのみ質問します(たとえば、2つの候補セクションがあるページの「ヒーロー」)。参照がログイン壁のあるページや、ここでダウンロードできないYouTube/Loomリンクの場合は、ユーザーにスクリーン録画を依頼し、その間それ以外の作業を続けます。
1. セットアップ
以下で <skill> はこのSKILL.mdが置かれているディレクトリです。スクリプトには Bun が必要です。初回実行時にPlaywrightのChromiumと静的ffmpeg(約250 MB)をダウンロードします。
bash <skill>/scripts/setup.sh # playwright、ffmpeg、pixelmatchを一度インストール;"ready"と表示
すべてのスクリプトは bun <skill>/scripts/<name>.ts --help で実行します。これらは決定論的であり、1つのルールを共有します。参照とクローンを同じビューポート、セレクタークロップ、トリガー、持続時間、fpsでキャプチャすること。そうしないと、比較は作業ではなく設定を測定することになります。
2. 参照のキャプチャ
ソースの種類に応じた手順は references/capture.md を参照してください。簡潔に言うと:
- Website:
capture.ts --url … --out ref --selector <section> --trigger load|scroll|hover|click|none --duration … --track "<moving elements>"。video.webm、frames/、inspect.json(宣言されたアニメーション、キーフレーム、計算済みスタイル、フォント、検出されたライブラリ)、track.json(各トラッキング要素のアニメーションフレームごとの位置、サイズ、不透明度、トランスフォーム)を取得します。CSS/WAAPIモーションの場合、inspect.jsonに正確な持続時間、遅延、イージングが含まれていることがよくあります。それらを使用してください。推定するより優れています。 - Videoまたはgif:
frames.ts --in file --out ref/frames --fps 10..30 --start … --end … --crop …。まず--probeで調査し、数フレームを表示してクローンするウィジェットのクロップ位置を見つけます。 - Canvas、WebGL、WebGPU、3D(
inspect.json › canvasesに表示されるか、three.js、Pixi、Babylon、Splineなどを使用している場合): キャプチャに--clock virtual --gl --assetsを追加し、gl/summary.md(gl.ts summary <out>)を読みます。シェーダーソース、すべての定数uniform、シーングラフ、レンダーパス、テクスチャとモデル、およびアニメーション化された各uniformまたはオブジェクトプロパティがgl-track.jsonのチャンネルとして取得されます。仮想クロックによりすべてのフレームが正確になり、すべてのキャプチャが同一になります(ランダムパーティクルも含む)。references/webgl.mdを参照してください。 - Lottie / Rive / プロトタイプ出力: ファイル自体が仕様です。それを読み、ピクセルから再導出しないでください。
次に、ラベル付きのシートを作成して確認します。sheet.ts filmstrip --frames ref/frames --out ref/sheets。すべてのシートを画像ビューアで確認します。これはユーザーが求めたフレームごとの検査です。スキップしたり最初のシートだけをサンプリングしたりしないでください。
3. モーション仕様の記述
references/analysis.md のテンプレートを使用して spec.md を記入します。要素ごと、プロパティごとに1行。トリガー、開始時間、持続時間、遅延またはスターガー、from→to、イージング、メモ。数値は、優先順位の高いものから取得します。inspect.json のアニメーションとキーフレーム → track.json またはキャンバスの場合は gl-track.json --channel に対する easing.ts → フレームを読む(変化する最初のフレーム、変化する最後のフレーム、オーバーシュートの有無)。また、モーションが依存する静的な事実も記述します。要素のサイズと位置、z順序、オーバーフロークリッピング、トランスフォーム原点。pixel-faithfulの場合はフォント、色、間隔、アセットも。
仕様は参照とクローンの間の契約です。すべての行がステップ5のチェックになります。「?」がある行は、まだフレームを読み終えていません。
4. 実装
ユーザーのスタックで references/implementation.md(イージングテーブル、スターガー計算、スクロール/ホバートリガー、モーション削減設定)に従って実装します。DOM構造は参照のロール構造に近づけ、トラッキングセレクターが同等になるようにします。mixedの場合は、追加部分を明確に分離されたコンポーネントまたはブロックに配置し、spec.md の「Additions」に記載します。
クローンが参照と同じ方法でキャプチャできるようにします。参照ビューポートでコンポーネントを同じトリガーでレンダリングするルートまたは静的ページを作成します。開発サーバーでも問題ありません(capture.ts --url http://localhost:5173/…)。スタンドアロンのHTMLファイルでも機能します。
5. 検証、修正、繰り返し
参照と同じコマンドでクローンをキャプチャします。--url と --out clone-N のみ変更します。その後:
bun <skill>/scripts/compare.ts --ref ref/frames --clone clone-N/frames --out compare-N
bun <skill>/scripts/sheet.ts compare --ref ref/frames --clone clone-N/frames --diff compare-N/diff --out compare-N/sheets --every 2
bun <skill>/scripts/easing.ts --track clone-N/track.json --selector "<el>" --prop <translateY|opacity|…> --compare-track ref/track.json
キャンバス作業の場合は、gl.ts compare --ref ref --clone clone-N も実行します。これにより、キャンバス設定、描画構造、およびすべてのアニメーションチャンネルがチェックされます。
レポートの読み方、各忠実度レベルの合格基準、および各失敗の種類に対して通常必要な修正については、references/verify.md を参照してください。比較シートは毎ラウンド自分で確認してください。数値は何かがおかしいことを示し、シートは何がおかしいかを示します。
すべての仕様行が合格するまでループします。各ラウンド:証拠が指し示す最小のものを変更し、再キャプチャし、再比較します。2〜5ラウンドを想定してください。5ラウンド後も行が失敗する場合は、その数値と理由(不足しているフォント、ユーザーがコピーできない可能性のあるシェーダーやモデル、近似した物理バネ)を報告して停止し、しきい値を静かに下げたり行を削除したりしないでください。
6. 報告
最終メッセージは単独で完結している必要があります。
- 忠実度レベルとクローンしたもの、追加したもの。
- コードの場所(ファイル)とモーションをトリガーする方法。
- 最後の比較ラウンドの短い表:タイミング誤差、平均不一致、キー要素ごとのイージング一致、合格/不合格。
- 最終比較シートへのパス。環境が表示できる場合は画像として埋め込む。
- 残存する差異。それぞれに数値と理由を付ける。
ラウンドを無駄にする落とし穴
- 参照とクローンでビューポートまたはクロップが異なる:コードに触れる前にキャプチャを修正する。
- 最初と最後のフレームだけで判断する:イージングは中間フレームにあります。シートを読んでください。
- フォント:異なる代替フォントはすべてのフレームのピクセルを変えます。pixel-faithfulの場合は、不一致を判断する前に同じフォント(
inspect.jsonfontsから)をロードしてください。motion-faithfulの場合は、テキストピクセルを無視してタイミング列を読みます。 - 読み込み済みページで記録された参照と、コールドでキャプチャされたクローン:
--wait-beforeを使用するか、--trigger noneと--pre-jsでアニメーションを再起動して、両方が静止状態から開始するようにします。 - スクロール駆動モーション:時間の関数ではなくスクロール位置の関数です。両方を同じ
--scroll-stepsと--scroll-msでキャプチャし、秒ごとではなくスクロール位置(トラックのscrollY)ごとに比較します。 - JSライブラリ(GSAP、Framer Motionスプリング):
--playback-rateはそれらを遅くしません。track.jsonとeasing.ts(オーバーシュートと「スプリング状」を報告)を使用し、オーバーシュートと整定時間でスプリングパラメータを調整します。 - 他の人の画面の動画には、カーソル、ブラウザのクローム、圧縮ノイズが含まれます。それらをクロップして、ノイズを追うのではなく
--pixel-thresholdを少し(0.15)上げてください。 - 実クロックでキャプチャされたCanvasとWebGL:ソフトウェアGLではフレームがドロップし、ランダムコンテンツはロードごとに異なるため、比較はマシンを測定することになります。両側を
--clock virtualと同じ--seedでキャプチャしてください。 - スクリーンショットからシェーダーを再構築する:トレースにはすでにそのソースとすべての定数があります。GLSLを書く前に
gl/shaders/と固定uniformを読んでください。