1仕組みと動作原理

React における唯一の推奨ソリューションを提示：@gsap/react の useGSAP() を採用し、useEffect の代わりにクリーンアップの責務を担当させる。

skills/gsap-react/SKILL.md

It handles cleanup automatically and provides a scope and **contextSafe** for callbacks.

主張する機能を実現できる理由：useGSAP = useLayoutEffect/useEffect + gsap.context のラッパーであり、アンマウント時にそのコンテキストで作成されたすべてのアニメーションおよび ScrollTrigger を自動的に revert します。本スキルは「React のメモリリーク」という頻出課題をフレームワーク層で根本から解消します。

登録の規律：useGSAP 自体もプラグインであるため、使用前に registerPlugin による登録が必須（gsap-plugins と同一の規約に準拠）。

skills/gsap-react/SKILL.md

gsap.registerPlugin(useGSAP); // register before running useGSAP or any GSAP code

登録を怠るとフックの挙動が不完全になり（contextSafe やクリーンアップが無効化される）、しかもエラーがスローされません。典型的なサイレント障害となるため、サンプルの1行目に明記されています。

scope は任意の最適化ではなく必須項目：セレクタは必ずコンポーネントのルートノード内に限定する必要があり、Do Not で「scope のないセレクタ」を明確に禁止。

skills/gsap-react/SKILL.md

❌ Target by **selector without a scope**; always pass **scope** (ref or element) in useGSAP or gsap.context() so selectors like `.box` are limited to that root and do not match elements outside the component.

ここでの目的：「コンポーネント内でグローバルセレクタを使用するとページ内の他の要素に意図せず影響を及ぼす」という React 特有の落とし穴を厳格なルール化すること。同時に、第2引数が依存配列または設定オブジェクトのいずれの形式も取れることを示しています。

contextSafe による「ランタイム生成アニメーション」の処理：イベントコールバック内で new された tween はコンテキスト外となり、アンマウント時に破棄されない。

skills/gsap-react/SKILL.md

This animation is created in an event handler that executes AFTER useGSAP() executes.

本スキルでは badRef/goodRef の対比コードを用いて、2つの不具合（アニメーションがコンテキストに含まれない＋イベントリスナーが解除されない）を同時に実演しています。正解はコールバックを contextSafe でラップし、cleanup 内で removeEventListener を実行することです。これは「なぜ contextSafe が必要なのか」についての最良の説明となっています。

useGSAP 以外のシナリオに対する等価なフォールバックの提示：useEffect + gsap.context() + ctx.revert() を用い、「必ず」クリーンアップを返すよう要求。

skills/gsap-react/SKILL.md

return () => ctx.revert();

適用条件の説明：@gsap/react が利用できない場合、あるいは effect 自体の依存関係／トリガー挙動が真に必要な場合。useEffect を使用する際は必ず ctx.revert() を併用しなければならず、怠るとアンマウントされたノードにインラインスタイルやインスタンスが残留します。

SSR の境界：GSAP はブラウザ向けライブラリであり、サーバーサイドレンダリング段階での gsap/ScrollTrigger の呼び出しを禁止。

skills/gsap-react/SKILL.md

GSAP runs in the browser. Do not call gsap or ScrollTrigger during SSR.

Next.js などの環境における実行可能な解決策：アニメーションをすべて useGSAP/useEffect（本質的にクライアントサイドでのみ実行）内に配置するか、バンドルサイズ抑制のために effect 内で必要に応じて動的 import を行います。

2コア機能

01useGSAP 優先のアニメーション組み込み（自動クリーンアップ + スコープ限定 + 設定オブジェクト）

02scope サンドボックス：セレクタをコンポーネント内部（ref または要素）のみに限定

03contextSafe：イベントコールバック内で作成されたアニメーションをコンテキストに含め、アンマウント時の確実な回収を保証

04gsap.context() + ctx.revert() による手動クリーンアップパス（useEffect 向けシナリオ）

05dependencies / revertOnUpdate による再実行および再破棄の制御

06ターゲットとしての refs（レンダリングを跨いだ誤った要素へのマッチングを防止）および複数要素のコンテナクエリ

07SSR セーフ：アニメーションをクライアント側のライフサイクル内でのみ実行

3外部依存関係

Kind	Dependency / Endpoint
package	@gsap/react（useGSAP hook 包）
package	gsap（动画引擎本体）
network	GSAP 官方 React 资源页

4推奨統制措置と判定根拠

安全運用のための推奨統制措置

Agent 向け

自動ロード可能

管理者向け

ソースとバージョンの記録

判定根拠（ファイルパスと抜粋）

SKILL.md: スクリプト実行や外部への影響を伴わない、純粋なプロンプト指示およびルールテキスト

監査ノート： 純粋な指示型スキル：ディレクトリ内には SKILL.md（6,565 B）のみが存在し、スクリプト、外部ネットワーク通信、クレデンシャル読み取り、ファイル書き込みは一切含まれません。外部リンクは1件のみです（gsap.com/resources/React）。提示されている2つの npm 依存関係（gsap, @gsap/react）はインストール用の指示文であり、スキルが自動インストールするものではありません。サプライチェーンリスクはユーザーが独自に npm install を実行する際のリポジトリ元に依存し、スキル自体は認証情報やプライベートレジストリには関与しません。注意点：クリーンアップの規律（scope/contextSafe/revert）はプロンプト層の制約であり、実装が漏れるとメモリリークや古いノードの更新が発生しますが、これはセキュリティリスクではなく実装の正確性に関する問題です。

5二重目の独立検証

[ok] 目录资产面：仅 SKILL.md — skills/gsap-react/ 下唯一文件 SKILL.md（6,565 B）；无 scripts/、references/、示例工程（示例在仓库 examples/react/）。
[ok] external_deps 逐条核实 — 两条 npm install 指令（gsap、@gsap/react）与一条 gsap.com/resources/React 链接均在文件内逐字命中。
[ok] useGSAP 行为描述是否与官方 hook 一致 — 「handles cleanup automatically」「provides a scope and contextSafe」与 @gsap/react 的 useGSAP 官方文档一致；dependencies/revertOnUpdate 配置项名称真实。
[ok] contextSafe 段落是否是真实失败模式（非编造） — 原文给出可复现机制：事件回调在 useGSAP 执行之后创建 tween → 不入上下文 → 卸载不回收；并指出监听器未移除会跨渲染残留。逻辑自洽且符合 gsap.context 的设计。
[ok] 安全反例搜索 — token 扫描：curl/wget/fetch(/XMLHttpRequest/exec(/child_process/process.env/.env/API_KEY/secret 零命中；URL 仅 1 条官方资源页。
[ok] 与 gsap-frameworks 分工是否重复 — gsap-react 首段声明 React 用本 skill、Vue/Svelte 用 gsap-frameworks；gsap-frameworks 亦反向声明「For React specifically, use gsap-react」，无内容重叠冲突。
[ok] 元数据与 pin — frontmatter license: MIT；HEAD = aed9cfd3277740755f6bfc1155c7aa645403b760；GitHub API stars 15326 / pushed_at 2026-07-29T17:36:08Z。
[ok] examples/react 与本文一致性 — examples/react/App.jsx 用 useGSAP + { scope: containerRef } + 注册 useGSAP，与 skill 的 Do/Do-Not 完全对应。

6結論

React 側における唯一のメインパス（useGSAP）を提示し、なぜ自動クリーンアップが可能なのかを解説することで、チームが useEffect の手動クリーンアップで同じ過ちを繰り返すのを防止。

正誤の対比により contextSafe の必要性を徹底解説：コールバックで作成されたアニメーションはコンテキストから漏れ、リスナーを削除しないとレンダリング間で残留する問題を明確化。

scope を Do Not 内の厳格なルールとして明記し、「コンポーネントのアニメーションがページ全体の要素に誤爆する」という高頻度なバグを直接予防。

SSR の境界（Next.js）を網羅し、「アニメーションをクライアント限定で実行する」「必要に応じて動的 import する」という2つの解決策を提示。

軽量かつ的確：6.5 KB で連携部分のみに特化し、GSAP 構文自体は core/timeline/scrolltrigger に委ねることで、学習・ロード双方のコストを最小化。

最適な用途： React / Next.js で GSAP を使用するすべてのプロジェクト、特に SPA のルーティング遷移、頻繁なコンポーネントのアンマウント、またはすでにメモリリークに悩まされているコードベースに最適。また、チーム内の「React アニメーション規約」のレビュー用チェックリストとしても適しています。

不向きな用途： Vue/Svelte プロジェクト（gsap-frameworks を使用してください）；CSS アニメーションのみを使用する、またはアニメーション要件がないプロジェクト；React 以外の GSAP API 解説を本スキルに期待するシナリオ（gsap-core / gsap-timeline / gsap-scrolltrigger を参照してください）。

Install Agent-Ready

① Verified Mirror 2026-09-15

Option A · Direct DownloadDownload gsap-react.tar.gz

sha256: 63017b31e6b9c157…

Option B · Copy Guide for Agent

install.json

Agent はこの JSON ガイドから自動的にダウンロードして検証します。

② Upstream GitHub

GitHub Repo ↗

Pinned to commit aed9cfd327.