reanimate

reanimate

ユーザーが指定したものを再構築し、参照と同じように動くようにします。フレームごとの比較でそれを証明し、比較に合格するまで続けます。納品物はユーザーのプロジェクト内のコードと証拠（数値および並べて表示したシート）であり、「だいたい合っているように見える」ではありません。

「完了」の定義

ユーザーの言葉から忠実度レベルを選び、最初のメッセージで明示します。どの項目を検証するかは、このレベルで決まります。

レベル	該当する場合	一致させる項目	異なってもよい項目
動きに忠実（デフォルト）	「このアニメーションをクローンして」「あちらのような雰囲気にして」「X と同じヒーローをこちらのコピーで」	トリガー、シーケンスと順序、スタッガー、各ステップのタイミング（±80 ms）、イージングの種類、要素のサイズに対する動きの方向と距離、レイアウトの比率	コピー、色、フォント、画像、ブランドの詳細
ピクセルに忠実	「完全に一致させて」「ピクセル単位で完璧に」「細部まで一致させて」「1:1」	上記すべてに加え、フォント、サイズ、色、余白、角丸、シャドウ、アセット。フレームの平均不一致率は ≤ 2 %	ユーザーが変更を求めていないものは、何も変更しません
混合	「X をクローンして Y を追加」「あちらのように、価格帯は自社のものに」	クローンした部分は上記いずれかのレベルに一致させます	追加部分は説明して提示しますが、クローンした動きに影響しないことのみを検証します

ユーザーは対象を1つのセクション、ウィジェット、ページ、または動画の時間範囲（「最初の3秒」「0:12から0:15」）に絞ることができます。指定された対象だけを正確にクローンし、ページのほかの部分は取り込みません。

ワークフロー

以下のすべては、ユーザーのプロジェクト内の .reanimate/<name>/ に保存します（証拠のコミットを希望されない場合は、.gitignore に追加します）。各ラウンドの成果物は、証拠として残しておきます。

0. 範囲

キャプチャを行う前に、.reanimate/<name>/spec.md の先頭に次の3行を書きます。

• 対象：クローンする対象を、ユーザーの説明どおりにできるだけ具体的に記します（URL + セレクター／時間範囲／「gif 内のトグル」）。
• 配置先：コードの配置先と使用する技術スタックを記します（package.json、既存コンポーネント、すでに使用しているアニメーションライブラリを確認し、新しいものを導入せず、既存のものに合わせます）。
• 忠実度：動きに忠実、ピクセルに忠実、または混合を記し、混合の場合は追加内容の一覧も記します。

依頼内容とリポジトリから推測できることは推測します。解釈の違いによって作業内容が変わる場合に限り、確認します（たとえば、ページに候補となるセクションが2つあるときの「ヒーロー」など）。参照先がログイン必須のページ、またはここではダウンロードできない YouTube／Loom のリンクである場合は、画面録画をユーザーに依頼し、並行してほかの作業を進めます。

1. セットアップ

以下の <skill> は、この SKILL.md が置かれているディレクトリです。スクリプトの実行には Bun が必要です。初回実行時に Playwright の Chromium と静的 ffmpeg がダウンロードされます（約250 MB）。

bash <skill>/scripts/setup.sh      # installs playwright, ffmpeg, pixelmatch once; prints "ready"

すべてのスクリプトは bun <skill>/scripts/<name>.ts --help で実行します。各スクリプトは決定論的で、共通のルールがあります。参照とクローンは、同じビューポート、セレクターの切り抜き範囲、トリガー、時間、fps でキャプチャしてください。そうでないと、比較で測定されるのは作業内容ではなくセットアップになってしまいます。

2. リファレンスをキャプチャする

ソースの種類に応じた手順は references/capture.md を読んでください。概要は次のとおりです。

• ウェブサイト：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 に正確な時間、遅延、イージングが含まれていることがよくあります。推定するより正確なので、これらを使ってください。
• 動画または 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 行とし、トリガー、開始時間、時間、遅延またはスタガー、開始値 → 終了値、イージング、メモを記載してください。数値は、優先順に、inspect.json のアニメーションとキーフレーム → track.json に対する easing.ts、または Canvas の場合は gl-track.json --channel に対する easing.ts → フレームを読んで得られる情報（変化が始まる最初のフレーム、変化が終わる最後のフレーム、オーバーシュートの有無）から取得します。また、モーションが依存する静的な情報として、要素のサイズと位置、前後関係、オーバーフローによるクリッピング、変形の原点も記録してください。ピクセル単位で忠実に再現する場合は、フォント、色、余白、アセットも記録します。

仕様はリファレンスとクローンの間の取り決めです。すべての行がステップ 5 のチェック項目になります。行に「？」が残っている場合、フレームの確認が完了していません。

4. 実装する

references/implementation.md に従い、ユーザーのスタックで実装してください（イージングの表、スタガーの計算、スクロールとホバーのトリガー、動きを減らす設定）。追跡対象のセレクターに対応する要素を配置できるよう、DOM 構造はリファレンスのロール構造に近づけてください。複数の要素を組み合わせる場合は、追加分を明確に分離されたコンポーネントまたはブロックに配置し、「追加項目」として spec.md に記載します。

クローンをリファレンスと同じ方法でキャプチャできるようにしてください。リファレンスと同じトリガーを使い、同じビューポートでコンポーネントを表示するルート、または静的ページを用意します。開発サーバーでも構いません（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. レポート

最終メッセージだけで内容が完結するようにしてください。

• 忠実度レベル、クローンしたもの、追加したもの。
• コードの場所（ファイル）と、モーションの再生方法。
• 最後の比較ラウンドの簡潔な表：タイミング誤差、平均不一致度、主要な要素ごとのイージング一致度、合否。
• 最終比較シートのパス。環境で画像が表示される場合は、画像として埋め込みます。
• 残存する差異と、それぞれの数値および理由。

試行を無駄にする落とし穴

• 参照とクローンでビューポートやクロップが異なる：コードに手を入れる前にキャプチャを修正します。
• 最初と最後のフレームだけで判断する：イージングは中間フレームに現れます。シートを確認してください。
• フォント：異なる代替フォントを使うと、すべてのフレームのピクセルが変わります。ピクセル忠実度を重視する場合は、不一致を判断する前に同じフォント（inspect.json のフォント）を読み込んでください。モーション忠実度を重視する場合は、テキストのピクセルを無視し、タイミングの列を確認してください。
• ページの読み込み後に記録した参照と、読み込み直後にキャプチャしたクローン：--wait-before を使うか、アニメーションを再開する --pre-js とともに --trigger none を使い、両方を静止状態から開始してください。
• スクロール駆動のモーション：時間ではなく、スクロール位置に応じて動作します。両方を同じ --scroll-steps と --scroll-ms でキャプチャし、1秒ごとではなく、各スクロール位置（トラックの scrollY）で比較してください。
• JS ライブラリ（GSAP、Framer Motion のスプリング）：--playback-rate では速度が落ちません。track.json と easing.ts を使って（オーバーシュートと「spring-like」を報告します）、オーバーシュートと収束時間を基準にスプリングのパラメーターを調整してください。
• 他人の画面を撮影した動画には、カーソル、ブラウザーの枠、圧縮ノイズが含まれます。これらをクロップして除き、ノイズを追いかける代わりに --pixel-threshold を少し（0.15）上げてください。
• 実時間のクロックでキャプチャした Canvas や WebGL：ソフトウェア GL ではフレームが落ち、ランダムなコンテンツは読み込みごとに異なるため、比較結果はマシンの性能を測ることになります。両方を --clock virtual と同じ --seed でキャプチャしてください。
• スクリーンショットからシェーダーを再構築する：トレースにはソースとすべての定数がすでに含まれています。GLSL を書く前に、gl/shaders/ と固定のユニフォームを確認してください。