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 随路由变化、退出期间旧子树仍需渲染旧内容。

方案 A 等于 template.tsx（每次导航重挂载）加 pathname 作 key 的 AnimatePresence 加 FrozenRouter（快照 LayoutRouterContext 让旧树继续渲旧内容）

skills/page-transition-animation/SKILL.md

const frozen = useRef(context).current;

给出三个文件的完整代码（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 不触发这一现象拆成可逐条排除的清单，而不是散落的技巧。

验收降级为可独立复现的单文件：用两个 stub 页面加 ?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过渡阶段冻结 harness（?view=b 与 ?phase=exit）

08零 build 交付（先用单 HTML 两个 stub 页面验证转场，不必为看一眼淡入而搭 Next）

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（产物期引用，正文未点名域）
本地工作目录: 文件读写与工件输出: 本 skill 目录零写盘；由 agent 在用户 Next 工程写 template.tsx、page-transition.tsx、frozen-

审计说明： 。判级只依据 skill 自身目录（skills/page-transition-animation/ = SKILL.md + 0 字节 README.md + references/full-examples.md，find 全量核对）：零脚本、零凭证、零写盘、执行期零外发（token 扫描 fetch(/XMLHttpRequest/curl/wget/child_process/process.env/API_KEY|TOKEN|SECRET/.env/eval( 零命中）。正文点名的 CDN（motion 与 React，未点名域）出现在输出契约里，属产物期引用，按批4 口径不判级；对 Next 内部模块的 import 属工程依赖（由用户工程安装），非本 skill 外发。

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 不触发写成结构性根因与三个必需条件，而不是零散技巧

两个方案都落到可抄代码（三个 tsx 文件、CSS 伪元素加守卫包装），并给选型判据

对照料足：references 给完整目录布局、方向性变体、共享元素、loading.tsx 与决策表

对自身脆弱点诚实：Next 内部 import 路径在多处被显式标记为版本敏感

适合： 适合：① Next.js App Router 项目要做页面与路由进出场（尤其 exit 一直不触发、旧页瞬间消失的现场）；② 需要判断该用 Framer Motion 还是 View Transitions 的团队；③ 需要共享元素（view-transition-name）或方向性滑动转场；④ 想先把转场曲线在单文件里验证、再回工程接线。

不适合： 不适合：① 非 Next 的通用 SPA 路由（description 提及但正文无具体接线，需自行补）；② 只需要页面内元素微交互（走 micro-interaction）；③ 不接受依赖框架内部私有路径的项目（FrozenRouter 方案有升级风险，应改用 View Transitions）；④ 需要浏览器全覆盖的无守卫实现（View Transitions 支持面不齐，必须带 fallback）。

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.