gsap-sveltekit

GSAP SvelteKit

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

マウントとアンマウントは Svelte の領域で、その間の 5 つのフェーズはアニメーションが担います。SvelteKit はパラメーターが変わってもページを再利用し、共有レイアウトを維持するため、新しいページライフサイクルが必ずしも新しいノードを意味するわけではありません。

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

このスキルでは、モーションをいつ実行するかを決めます。何を動かすか、また高級感や遊び心といった雰囲気については、インストールされている場合は animaxxing スキルも読み込んでください。そのレシピと雰囲気を見つけるためのガイドを、このライフサイクルに組み込めます。

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

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

1. Svelte 5 の runes モードで SvelteKit を使用していることを確認します。SvelteKit のルーティングを使わない通常の Svelte は gsap-frameworks の対象です。Svelte 4 またはレガシーモードの場合はその旨を伝え、$effect に関する説明を onMount と onDestroy に対応付けてください。
2. インストール済みの @sveltejs/kit と svelte のバージョンを確認します。記憶に頼らず、同梱されている型定義を優先してください。node_modules/@sveltejs/kit/types/index.d.ts にはすべてのナビゲーションオブジェクトが、node_modules/svelte/types/index.d.ts には runes とライフサイクルのエクスポートが記載されています。バージョン要件：onNavigate（1.24）、$app/state（2.12。これより前は $app/stores を使用）、ナビゲーションターゲットの to.scroll（2.51）、svelte/motion の prefersReducedMotion（5.7）、{@attach}（5.29）。
3. svelte.config.js、ページオプション（ssr、csr、prerender）、src/app.html の body にある data-sveltekit-preload-data、および data-sveltekit-reload が付いたリンクを確認します。csr = false のページにはクライアントルーターもナビゲーションフックもありません。再読み込みリンクはドキュメント全体を読み込みます。どちらも通常のドキュメントとして扱ってください。

エンジンを選ぶ

単純なブロックのモーションや、アウトロの間だけ DOM を保持すればよい {#key} の切り替えには、Svelte の transition:／in:／out: を使用します。スナップショットのモーフィングやページのクロスフェードには、onNavigate から View Transitions を使用します。DOM を維持したままナビゲーションを保留する場合、中断可能なシーケンス、分割テキスト、スクロール連動モーションには GSAP を使用します。1 つの要素には 1 つのエンジンを使用してください。エンジンの併用を参照してください。

必要な情報だけを読む

• 見えない状態からの表示、初期化の失敗、インデックス作成、初回読み込み時のパフォーマンス：初期化と復旧とフレームワーク連携。
• ナビゲーションフックとその順序、ナビゲーション前のアウトロ、ロック、戻る／進む、スクロール、フォーカス、リンク、プリロード、View Transitions：SvelteKit のナビゲーション。
• ページの再利用と再マウント、レイアウト、{#key} と afterNavigate の使い分け、Svelte 5 のライフサイクル、GSAP と併用する Svelte のトランジション、浅いルーティングのモーダル、SSR：ページのライフタイム。
• 5 つのフェーズ、GSAP のセットアップ、コンテキスト、表示と非表示、レイアウトの安定性、スクロール、テキスト、プラグイン：ライフサイクルの実装。
• ルート間の Lenis、ScrollSmoother、またはイージング付きページスクロール：スムーズスクロールとフックの対応付け。
• カーテン、初回訪問時のプリローダー、共有要素のモーフィング：トランジションのパターンとレイアウト連携。
• タッチ、ビューポートの変更、デバイスの予算：デバイスと入力。
• Tauri、Electron、Wails のデスクトップシェル：デスクトップ WebView。
• 作業完了とする前に：検証。

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

ルール

• セットアップ成功時は非表示の導入アニメーションを維持し、失敗時は現在の受信側の所有者を復元します。非表示ルールを追加する前に、初期化の契約に従ってください。
• GSAP はブラウザーでのみ実行されます。onMount と $effect はサーバー上では実行されません。モジュールレベルのコードには browser ガードが必要です。セレクターのスコープには gsap.context を使用し、bind:this のルートに紐付けてください。すべてのトゥイーン、トリガー、分割、リスナーを、エフェクトのクリーンアップ処理または onMount の戻り値でクリーンアップしてください。
• 通常の CSS と安定したラッパーで最終的なジオメトリを確保し、レイアウト領域を二重に占有しないよう、退出するコンテンツと入ってくるコンテンツを重ねます。
• マウントしてから初期値を設定し、その後に描画します。初期化が成功した場合、導入アニメーションの前に確定後のコンテンツが一瞬表示されることはありません。サーバーの HTML はハイドレーション前に描画されるため、インラインスクリプトで設定したルート属性の配下に限り、初期フェーズ中のみ導入アニメーションの対象を非表示にし、JavaScript が無効な場合の表示経路も用意してください。
• 確定後に一時的なスタイルをクリアします。アニメーション中のみ will-change を使用してください。これは gsap-performance の静的なヒントを上書きします。
• デバイス階層の判定には機能クエリを使用します。タッチ状態は解除し、ホバーなしでもコントロールを操作できるようにしてください。
• アウトロと終了状態の間、退出するページをマウントしたまま表示し続けます。beforeNavigate でナビゲーションを保留して終了コールバックから再実行するか、onNavigate からアウトロの promise を返してください。onNavigate が実行される前に URL が変わるため、アウトロ中に URL を変更しないのは前者だけです。
• 新しいパラメーターを伴う同一ルートへのナビゲーションでは、ページがその場で更新されます。確定後の値をすでに持つ DOM に対して afterNavigate からライフサイクルを再実行するか、{#key} で再マウントしてください。
• 戻る操作と進む操作は、同じフックを経由して popstate として発生します。これらに対してアウトロを実行しないでください。スクロール復元後に導入アニメーションのみを実行する経路を用意します。
• ナビゲーションごとに再構築すべきでない限り、GSAP のセットアップを構築するエフェクト内で page、data、navigating を読み取らないでください。
• 1 つの要素に対して使用するエンジンは 1 つだけです。GSAP がアニメーションするノードに out: ディレクティブを指定すると競合し、ブロックはディレクティブが完了するまで DOM に残ります。
• ネイティブのリンク動作、data-sveltekit-* オプション、フォーカス、スクロール、JavaScript が無効な場合の読みやすさを維持してください。
• 動きを減らす設定でも同じ確定後の状態に到達し、すべての完了コールバックが引き続き実行されるようにします。Svelte のトランジションは CSS の動きを減らすルールを無視するため、prefersReducedMotion を使って時間をゼロにしてください。
• 中断と連続クリック時の動作を定義し、ナビゲーションの待機状態が必ず一度だけ解除されるようにしてください。
• 可能であれば実際のブラウザーで検証してください。ルート、設定、依存関係、リリースの変更には、本番ビルドを使用してください。