gsap-astro

GSAP Astro

マウント → 初期状態 → イントロ → 安定状態 → アウトロ → 最終状態 → アンマウント

<ClientRouter /> を使用しない場合は、ドキュメント全体の読み込みに gsap-vanilla を使用します。使用する場合、マウントとアンマウントは body の入れ替えに対応します。モジュールスクリプト、グローバルリスナー、タイムライン、永続化された要素は、その後も維持される場合があります。アニメーションが担うのは、入れ替えの間にある5つのフェーズです。

求められている見た目と、既存のプロジェクトの規約を維持してください。GSAP／プラグインは必要な場合にのみ追加し、依頼がない限り、選択済みのアニメーションライブラリを置き換えないでください。

このスキルでは、モーションを実行するタイミングを決めます。何を動かすか、またはプレミアム感や遊び心のある雰囲気にする方法については、インストール済みであれば animaxxing スキルも読み込んでください。そのレシピと、雰囲気を見つけるためのガイドは、このライフサイクルと連携します。

まずプロジェクトを確認する

リポジトリの指示、既存のアニメーション、レイアウト、ナビゲーション、CSS、アクセシビリティの規約、チェック方法を確認してください。その後、次の手順を行います。

1. インストールされている Astro のバージョンを確認します。記憶に頼る前に、node_modules/astro/dist/transitions/router.js、swap-functions.js、node_modules/astro/components/ClientRouter.astro を読み、リリースノートで該当バージョンを確認してください。パッケージには変更履歴が含まれていません。バージョンごとの機能：<ClientRouter />（5.0、4.x では <ViewTransitions />、6.0 で削除）、loader と newDocument を伴うライフサイクルイベント（3.6）、フォームナビゲーション（4.0）、transition:persist-props と data-astro-rerun（4.5）、swapFunctions（4.15）。
2. <ClientRouter /> の配置場所（共通の head、一部のページ、またはどこにもない場合）と、その fallback プロパティを確認します。どこにもない場合は、CSS の @view-transition も含めて gsap-vanilla を使用します。
3. どのフレームワーク統合がアイランドをレンダリングしているか、またどの client:* ディレクティブが使われているかを確認します。
4. astro.config で prefetch と experimental.clientPrerender を確認します。

エンジンを選ぶ

ClientRouter の下でスナップショットのモーフィング、フェード、スライドを行う場合は、transition:name / transition:animate を使用します。スワップを保留するライブ DOM のアウトロ、中断可能なシーケンス、分割テキスト、スクロール連動モーションには GSAP を使用します。1つの要素に使うエンジンは1つにしてください。詳しくはエンジンの併用を参照してください。

必要な情報だけを読む

• 見えないままのイントロ、初期化の失敗、インデックス作成、初回読み込みのパフォーマンス：初期化と復旧、およびフレームワーク統合。
• ルーターのイベントシーケンス、スワップ前のアウトロ、クリーンアップ、遷移先ページの初期状態、方向、戻る／進む、スクロール、フォーカス、プリフェッチ、フォールバックに対応するブラウザー：ClientRouter ナビゲーション。
• 再実行されるスクリプト、ページをまたいで残るリスナー、カスタム要素、アイランドと client:* ディレクティブ、transition:persist：スクリプトとアイランド。
• 5つのフェーズ、GSAP のセットアップ、コンテキスト、表示と非表示、レイアウトの安定性、スクロール、テキスト、プラグイン：ライフサイクルの実装。
• スワップをまたいだ Lenis、ScrollSmoother、またはイージング付きのページスクロール：スムーズスクロール、およびルーターとの統合。
• カーテン、初回訪問時のプリローダー、共有要素のモーフィング：トランジションのパターン、およびイベントの対応付け。
• タッチ、ビューポートの変更、デバイスの予算：デバイスと入力。
• Tauri、Electron、Wails のデスクトップシェル：デスクトップ WebView。
• 作業完了とする前に：検証。

このリポジトリと併せてGSAP 公式スキルをインストールしてください。API の詳細には gsap-core を、コンポーネントのセットアップには gsap-frameworks を、必要に応じて読み込みます。

ルール

• セットアップ成功時は目に見えないイントロを維持し、失敗時は現在の受信側オーナーを復元します。非表示ルールを追加する前に、初期化の契約に従ってください。
• GSAP は対象の DOM が存在してから実行します。gsap.context でセレクターの範囲をページまたはコンポーネントのルートに限定します。オーナーを削除するスワップの前に、すべてのトゥイーン、トリガー、分割、リスナーをクリーンアップしてください。
• モジュールスクリプトはページごとではなく、訪問ごとに 1 回実行されます。セットアップは astro:page-load から実行し、新しい body でも同じ body でもう一度実行しても正しく動作するようにします。
• document と window に登録したリスナーはページをまたいで存続します。ルーターのリスナーは 1 か所で 1 回だけ登録し、各ハンドラーは処理を行う前に現在のページを特定するようにします。
• 通常の CSS と安定したラッパーで最終的な配置を確保し、レイアウト領域を二重にせずに、退出するコンテンツと入ってくるコンテンツを重ねます。
• 描画前に初期値を設定してから表示します。初回読み込み時はインラインの head スクリプトで、スワップ後は astro:before-swap と astro:after-swap で行います。初期化に成功した場合、イントロの前に表示後のコンテンツが一瞬表示されることはなく、JavaScript がなくてもページが真っ白になることはありません。
• 表示状態が確定したら一時的なスタイルを消去します。will-change はアニメーション中だけ使用してください。これにより、gsap-performance の静的なヒントは上書きされます。
• デバイスの階層には機能クエリを使用します。タッチ状態は解除され、ホバーなしでもコントロールが機能するようにします。
• アウトロは astro:before-preparation で event.loader 内のライブ DOM に対して再生され、ルーターはその完了を待ちます。astro:before-swap ではアニメーションしないでください。ユーザーが見ているのはスナップショットです。
• 戻る操作と進む操作には、イントロのみの経路を用意します。トラバースではすべてのイベントが発火するため、意図的に navigationType === "traverse" の場合はアウトロをスキップします。
• transition:persist 要素はページレベルのクリーンアップとイントロの対象から除外します。タイムラインも含め、要素は生きたままスワップを越えて引き継がれます。
• ネイティブのリンク動作、ルーターの履歴、スクロール復元、ルート通知を維持します。モーションのためにルーターと並行してクリックを横取りする処理を追加しないでください。唯一のクリックリスナーは、ナビゲーション中にロックを維持するキャプチャフェーズのガードです。
• スワップ前のクリーンアップではページコンテキストを破棄しますが、元に戻す処理は行いません。元に戻すと、まだアタッチされている body にイントロの開始値が書き戻されます。
• モーション低減設定でも同じ確定状態に到達し、すべての完了コールバックが引き続き発火します。ルーターは prefers-reduced-motion に応じて、独自のアニメーションをすでに無効化します。
• 一連の処理にはタイムラインを使用します。連続クリックやアニメーションの中断時の動作を事前に決めてください。アウトロの実行中に 2 回目のクリックがあると、ルーターは最初のナビゲーションを中止するため、最初のクリックを優先するにはロックガードが必要です。
• 可能であれば、同じページへの 2 回目の訪問、戻る操作、進む操作、アウトロ中のクリックを含め、実際のブラウザーで検証してください。