1仕組みと動作原理

失敗の構造的な根本原因をまず明確にする：App Router のナビゲーションは古いルートのコンテンツを即座に置き換えてしまうが、AnimatePresence はアンマウントされる子要素がマウントされたままでラッパーが存続している場合にのみ exit を実行できる。

skills/page-transition-animation/SKILL.md

The reason is structural — in the App Router, when navigating, Next.js unmounts the old route's content and mounts the new one almost immediately.

ラッパーの常駐、ルート変更に連動する child key、終了遷移中も古いサブツリーが古いコンテンツを描画し続けること、という 3 つの必須条件を明確に定義する。

アプローチ A は、template.tsx（ナビゲーションごとに再マウント）+ pathname を key とする AnimatePresence + FrozenRouter（LayoutRouterContext をスナップショットして古いツリーに古いコンテンツを描画させ続ける）で構成される。

skills/page-transition-animation/SKILL.md

const frozen = useRef(context).current;

3 つのファイル（template.tsx、page-transition.tsx、frozen-router.tsx）の完全なコードと、各パラメータの役割（mode="wait"、initial={false}）を提示する。

アプローチ B は、ネイティブの View Transitions API（::view-transition-old/new アニメーションと document.startViewTransition でラップした router.push）、または next-view-transitions ライブラリを用いた即時導入で構成される。

skills/page-transition-animation/SKILL.md

::view-transition-old(root) { animation: fade 0.25s both reverse; }

選定基準を明確化：シンプルなフェードや変形には View Transitions、詳細なオーケストレーションや中断可能な退場アニメーションには Framer Motion を採用し、startViewTransition の機能チェック（ガード）を必須とする。

トラブルシューティングを順序立てた 7 項目のチェックリストとしてまとめ、ラッパーの位置、key、直下の motion 子要素、mode="wait"、FrozenRouter、'use client'、単一子要素を網羅する。

skills/page-transition-animation/SKILL.md

**Stable, changing key.** The animated child needs `key={pathname}` (or similar) so removal is detected.

exit が発火しない現象を、散在した Tips ではなく 1 つずつ検証可能なチェックリストに落とし込む。

検証を単独再現可能な単一ファイルに落とし込む：2 つのスタブページと ?view=/phase= を用いて遷移フェーズを固定し、Next プロジェクトから切り離して遷移の挙動を先行検証する。

skills/page-transition-animation/SKILL.md

One file is the right tier for validating motion before wiring the router; don't stand up Next just to eyeball a fade.

View Transitions のスナップショットは一時的なものであるため、スクリーンショットは完了状態を取得すべきであること（または低速アニメーションでシミュレートすること）を明記する。

2コア機能

01App Router でのルート別入場アニメーション（template.tsx によるナビゲーションごとの再マウント）

02ルート退場アニメーション（pathname を key にした AnimatePresence と、コンテンツのちらつきを防ぐ FrozenRouter）

03ネイティブ View Transitions の導入（CSS 疑似要素と startViewTransition ガード付き router.push ラッパー）

04next-view-transitions のワンポイント導入（layout を ViewTransitions でラップし、専用 Link に差し替え）

05AnimatePresence が発火しない場合の 7 項目トラブルシューティングリスト

06方向性スライド、クロスフェード、共有要素遷移、loading.tsx 遷移バリアント

07遷移フェーズ固定用ハーネス（?view=b および ?phase=exit）

08ビルド不要（ゼロビルド）での検証（フェード確認のためだけに Next を起動せず、単一 HTML と 2 つのスタブページで事前確認）

09アクセシビリティ対応：reduced-motion 環境でスライド移動を短いクロスフェードへグレースフルデグレード

3外部依存関係

Kind	Dependency / Endpoint
package	framer-motion（AnimatePresence 与 motion，配合 template.tsx 与 FrozenRouter）
package	next-view-transitions（把 View Transitions 接进 App Router 客户端导航）
api	Next.js 内部模块 LayoutRouterContext（next/dist/shared/lib/app-router-context.shared-runtime）与 usePathname
api	浏览器原生 View Transitions API（document.startViewTransition、::view-transition-old/new、view-transition-name）
network	交付页从 CDN 取 motion 与 React（产物期引用，不判级；正文未点名具体域）
cli	npx / Playwright（宿主侧截图工具）与仓库根 scripts/ 助手（seek-shot.sh、contact-sheet.sh 依赖 ffmpeg）

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

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

Agent 向け

アクセス可能ドメインとキー範囲を宣言

管理者向け

最小権限のキー、リクエストログを保持

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

网络端点: 外部ネットワークアクセスの宣言: 実行時における外部通信はゼロ。生成されたデリバリーページが CDN から motion と React を取得（成果物フェーズの参照であり、本文中に特定ドメインの記載なし）
本地工作目录: ファイル読み書きおよび成果物出力: 本スキルディレクトリへの書き込みはゼロ。エージェントがユーザーの Next プロジェクト内に template.tsx、page-transition.tsx、frozen-router.tsx を出力

監査ノート： 判定はスキル自身のディレクトリ（skills/page-transition-animation/ = SKILL.md + 0 バイトの README.md + references/full-examples.md、find による全量突合済み）のみに基づきます。スクリプトなし、クレデンシャルなし、ディスク書き込みなし、実行時外部通信なし（fetch(/XMLHttpRequest/curl/wget/child_process/process.env/API_KEY|TOKEN|SECRET/.env/eval( のトークンスキャンで該当ゼロ）。本文で言及されている CDN（motion および React、ドメイン未指定）は出力規約内に現れる成果物フェーズの参照であり、第 4 バッチ基準に基づき判定対象外です。Next 内部モジュールのインポートはプロジェクトの依存関係（ユーザー環境で導入）であり、本スキルによる外部送信ではありません。

5二重目の独立検証

[discrepancy] description 声称的覆盖范围（Next.js App Router 与 general SPA routing）与正文实际覆盖面是否相符 — frontmatter 写 ... for Next.js App Router and general SPA routing.，但正文主体（根因分析、方案 A 的三个文件、7 条排查清单）全部是 App Router 专属；general SPA 只在 View Transitions API 与交付用 stub HTML 两处被顺带覆盖，既无 React Router/Remix 等通用 SPA 路由的接线，也无对应排查清单。属描述略宽于实现（非虚假，但按 description 期望通用方案会落空）。
[ok] FrozenRouter 依赖的 Next 内部 import 路径真实性 — SKILL.md 给出 import { LayoutRouterContext } from 'next/dist/shared/lib/app-router-context.shared-runtime'; 并在正文、notes、gotchas、references 四处重复提示 internal、跨版本可能变，references 还专列 FrozenRouter import note across versions 一节；即文档自己对该脆弱性做了标注，非隐瞒。
[ok] View Transitions 验收的可行性（快照是瞬态） — 正文承认 snapshots are transient，并给出替代（截结束态或用 emulate slow animations），验收步骤不依赖捕捉瞬态帧；startViewTransition 的能力守卫在正文与完成前清单第 1 条都要求。
[discrepancy] Packaged helper 的路径基准与语义 — SKILL.md 的 verify 段仍贴 scripts/seek-shot.sh anim.html 0 1.5 3（时间冻结、仓库根路径），但本 skill 的冻结参数是 ?view= 与 ?phase=（状态与相位），helper 不匹配；scripts/ 也在仓库根而非本 skill 目录。

6結論

最も頻発する exit 不発問題を、単なるテクニック集ではなく構造的根本原因と 3 つの必須条件として整理

両アプローチとも即コピー可能なコード（3 つの tsx ファイル、CSS 疑似要素とガード付きラッパー）を提供し、選定基準も明示

リファレンスが充実：完全なディレクトリ構成、方向性バリアント、共有要素、loading.tsx、決定マトリクスを網羅

自身の脆弱性に誠実：Next の内部インポートパスがバージョン変更に敏感であることを随所で明記

最適な用途： 最適：① ページやルートの出入りアニメーションを必要とする Next.js App Router プロジェクト（特に exit が発火せず旧ページが一瞬で消える現場）；② Framer Motion と View Transitions のどちらを採用すべきか判断を求めるチーム；③ 共有要素（view-transition-name）や方向性スライドアニメーションを必要とする場合；④ 遷移カーブを単一ファイルで事前検証してからプロジェクトへ組み込みたい場合。

不向きな用途： 非推奨：① Next 以外の一般的な SPA ルーティング（description に記載はあるが本文に具体的な実装例がなく、自力での補完が必要）；② ページ内要素のマイクロインタラクションのみを目的とする場合（micro-interaction 向けスキルを使用）；③ フレームワーク内部のプライベートパス依存を許容しないプロジェクト（FrozenRouter 方式はアップグレード時の破壊リスクがあるため View Transitions を検討すべき）；④ ガードなしで全ブラウザ対応を求める場合（View Transitions はブラウザ対応にばらつきがあるためフォールバックが必須）。

Install Agent-Ready

① Verified Mirror 2026-09-28

Option A · Direct DownloadDownload page-transition-animation.tar.gz

sha256: 083d4f27aaf44464…

Option B · Copy Guide for Agent

install.json

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

② Upstream GitHub

GitHub Repo ↗

Pinned to commit b6dba3eb75.