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外部依赖
| 类型 | 依赖 |
|---|---|
| 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风险提醒 风险提醒：绿色 · 放心使用
风险提醒：绿色 · 放心使用
- description 的覆盖面大于正文实现（general SPA routing 无具体接线） — 见 second_pass：非 App Router 的 SPA（React Router 等）只有 View Transitions 一条泛化路径，需自行补接线与排查。
- 依赖框架内部模块，升级即可能断裂 — FrozenRouter 走 next/dist/shared/... 私有路径；Next 版本升级后若路径变动，过渡会直接报错（文档已标注，但无版本兼容矩阵或自动探测）。
- mode="wait" 的时延体验风险 — 等待退场完成才挂载新页，慢退场会让导航显得迟钝；文档要求时长约 0.2–0.4s，但没有性能预算或超时跳过退场的兜底。
- 交付验证与真实工程脱节，且 Packaged helper 不匹配（见 second_pass） — stub HTML 能验证曲线形状，但不覆盖 router 上下文、Suspense 与 layout 层级等真实失败面；helper 的秒制时间冻结与本 skill 的状态、相位冻结也不同调。
风险提醒：绿色，放心使用。判级只依据 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结论
适合：适合：① Next.js App Router 项目要做页面与路由进出场（尤其 exit 一直不触发、旧页瞬间消失的现场）；② 需要判断该用 Framer Motion 还是 View Transitions 的团队；③ 需要共享元素（view-transition-name）或方向性滑动转场；④ 想先把转场曲线在单文件里验证、再回工程接线。
不适合：不适合：① 非 Next 的通用 SPA 路由（description 提及但正文无具体接线，需自行补）；② 只需要页面内元素微交互（走 micro-interaction）；③ 不接受依赖框架内部私有路径的项目（FrozenRouter 方案有升级风险，应改用 View Transitions）；④ 需要浏览器全覆盖的无守卫实现（View Transitions 支持面不齐，必须带 fallback）。
安装 agent 直装可复制
① 本站镜像 更新 2026-09-28
方式 A · 人下载镜像包下载 page-transition-animation.tar.gz
sha256:
方式 B · JSON 格式安装指南，复制给 agent083d4f27aaf44464…agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。
② 上游 GitHub · 原始来源
来源信息 GitHub 原始
作者 / 仓库iart-ai / iart-ai/web-animation-skills
原始 GitHubiart-ai/web-animation-skills ↗
Stars28
最近推送2026-06-22
本 skill commit
b6dba3eb75许可MIT（仓库根 LICENSE 为 MIT License, Copyright (c) 2026 iart.ai；.claude-plugin/plugin.json 的 license 字段同为 MIT）
本站信息
收录日期2026-09-06
分类设计
侦查报告AI 侦查 · 2 遍 · 2026-09-06
本站镜像与 GitHub 原始是不同来源：本站锁定 commit 快照经 /r2 分发；GitHub 为实时上游，内容可能已更新。