optimize-web-animations

name	optimize-web-animations
description	剖析、审计并优化前端页面性能，重点关注动画工作、内存泄漏风险、长会话变慢、CSS 动画、canvas/WebGL 的 requestAnimationFrame 循环、marquee、skeleton、GSAP/Three/Matter 效果、定时器、监听器和 observer。当用户要求让动画高性能、暂停离屏动画、查找内存泄漏、剖析随时间拖慢电脑的页面、修复卡顿滚动、降低 CPU/GPU 占用，或在 React/Vite/Next/前端页面上用 Codex Browser 复用"仅在视野内播放"优化时使用。

优化 Web 动画

核心规则

编辑前先测量真实页面。目标不是移除动效；而是让离屏工作停止、让可见动效正确恢复，并让路由/卸载清理释放长期存活的资源。

尽可能使用 Codex Browser，尤其对 localhost 页面。除非用户明确要求，否则不要用 Chrome。

工作流程

1. 检查仓库上下文。

   • 阅读 AGENTS.md 或本地指令。
   • 尽早运行 git status --short。
   • 找到页面组件、动画 hook、CSS keyframes、requestAnimationFrame、setInterval、setTimeout、canvas/WebGL/物理组件、媒体元素、GSAP 时间线/tween，以及已有的可见性工具。
   • 搜索 effect 清理中的事件监听器、observer、RAF 循环、interval、定时器、外部脚本、媒体流、WebGL 纹理/材质/几何体/渲染器，以及可能在卸载后完成的异步工作。
   • 如果工作树是脏的，从一开始就规划窄范围的暂存。

2. 在浏览器中采集基线。

   • 打开用户点名的确切路由。
   • 在顶部、页面中部、页脚/靠下内容处剖析，并在布局可能不同时加一个移动端视口。
   • 按计算得到的 animationName、animationPlayState 和可见性统计 CSS 动画。包含 ::before 和 ::after。
   • 单独检查 canvas/WebGL 元素；CSS 剖析并不能证明 RAF 循环已停止。
   • 记录哪些动画名在离屏运行，以及负责它们的 DOM 所有者。
   • 对内存/泄漏问题，还要记录 element/canvas/image/iframe 计数、可用时暴露的 JS 堆指标、10-30 秒后的一个空闲采样，以及一段短的路由循环采样。如果堆 API 返回 null 或 Browser 沙箱阻止 monkey-patching，就说明这点，并依赖稳定的可观测计数加上源码审计。
   • 让压力测试保持有界。剖析期间 Browser 标签页崩溃是过载的证据，但除非用最小测试复现，否则不要过度归因。
   • 可复用的 Codex Browser 求值器见 references/browser-profiling.md。

3. 给控制该动效的最小所有者打补丁。

   • 如果应用有已存在的页面 reveal/可见性 hook，优先用它。
   • 否则加一个 IntersectionObserver，在板块和被动画的子元素上切换一个稳定的类，如 is-offscreen。
   • 用有针对性的规则暂停 CSS 动画：

main > section.is-offscreen .expensive-animation,
.expensive-animation.is-offscreen {
  animation-play-state: paused !important;
}

• 对重复的卡片或占位符，观察卡片外壳和被动画的后代元素，而不是整个文档。
• 对 marquee/ticker 轨道，当其板块离屏时暂停轨道。
• 对 skeleton 加载器和伪元素微光，在需要处包含 ::before 和 ::after 的暂停选择器。
• 对 canvas/WebGL/物理循环，直接闸控 RAF 循环：
  • 当 canvas/容器相交时启动。
  • 离屏时取消 requestAnimationFrame。
  • 重新进入时恢复。
  • 清理时断开 observer 并取消帧。
  • 当有助于浏览器校验时，加一个非视觉的调试标记如 data-animation-active。
• 如果组件已经这样做了，尊重 prefers-reduced-motion，并避免为滚动/动画状态引入 React 渲染循环。
• 对泄漏加固：
  • 清除该 effect 创建的每个 timeout/interval。
  • 在卸载前以及重启循环前取消 RAF。
  • 断开 IntersectionObserver、ResizeObserver、MutationObserver 和自定义订阅。
  • 用相同的 handler 引用移除 global/window/document 监听器。
  • 释放 Three/WebGL 的纹理、材质、几何体、渲染器，并移除渲染器 DOM 节点。
  • 杀掉针对 DOM 节点和可变对象（如 shader uniform）的 GSAP tween/时间线。
  • 停止媒体流，暂停已分离的 video/audio 源。
  • 用一个 isDisposed 标志守护异步加载器，如果它们在卸载后 resolve，就释放已加载的资源。
  • 在 React 清理中，如果 lint 警告 ref 可能变化，在返回清理函数前于 effect 内捕获 ref.current 的值。
  • 在可见性暂停后为物理或模拟帧的 delta 封顶，使被延迟的帧不会运行过大的更新。

4. 校验行为，而不只是构建。

   • 重新加载路由并重跑相同的 顶部/中部/页脚/移动端 剖析。
   • 目标结果：被测页面板块的 offscreenRunningCount: 0。
   • 确认可见动画在滚入视野时仍在运行或恢复。
   • 确认 RAF/canvas 循环在离屏时报告非活动、在视野内报告活动，或以其他方式从源码/运行时状态证明取消。
   • 对泄漏审计，对比前后的路由循环和空闲采样。反复导航后，DOM/canvas/image 计数应回到相同基线，允许预期内的小幅异步内容变化。
   • 执行一次正常的页面交互，如搜索/筛选/导航，使 observer 不会破坏动态内容。
   • 检查全新标签页的 console 警告/错误。

5. 运行本地检查。

   • 使用仓库的常规关卡。对 React/Vite 应用通常是：

git diff --check
npm run lint
npm run build

• 把已知的非致命警告与失败分开说明。

6. 在仓库/用户指令要求时窄范围提交。
   • 如果存在不相关的脏改动，使用一个隔离的 index：

rm -f /tmp/<task>-index
GIT_INDEX_FILE=/tmp/<task>-index git read-tree HEAD
# Apply only the intended hunks to the temporary index.
GIT_INDEX_FILE=/tmp/<task>-index git diff --cached --check
GIT_INDEX_FILE=/tmp/<task>-index git commit -m "Pause offscreen <page> animations"
git restore --staged <files> 2>/dev/null || true

• 除非每个 hunk 都属于本任务，否则绝不从脏工作树暂存大范围文件。

7. 带证据报告。
   • 以发现开头：什么还在运行、什么看起来易泄漏、什么无法测量。
   • 把源码审计风险与 live Browser 测量分开。
   • 包含确切采样的路由、离屏动画计数、DOM/canvas 计数稳定性、路由循环结果，以及本地检查。
   • 直白地说明局限，尤其是不可用的堆计数器或被阻塞的 Browser 插桩。

好的修复模式

• 板块级 is-offscreen 加元素级 is-offscreen，用于那些首屏以下子动画仍可能运行的长板块。
• 每路由共享的可见性选择器常量，如 COURSES_PAGE_ANIMATION_VISIBILITY_SELECTOR。
• 动画闸控用 IntersectionObserver，阈值约 0.01。
• 对 WebGL/canvas 效果直接控制 RAF 循环；CSS animation-play-state 无法暂停 JavaScript 渲染循环。
• 对在暂停或延迟帧后恢复的物理循环，做帧 delta 封顶。
• 为 GSAP/WebGL 效果使用的 React ref 捕获清理节点。
• 为可能在卸载后 resolve 的 image/video/texture/data 加载器加 isDisposed 守护。
• 用短的空闲和路由循环探针，捕捉累积的 DOM 节点、canvas、iframe 或未释放的媒体。

避免

• 为让剖析通过而移除所有动画。
• 因为祖先选择器太宽泛而暂停了可见的 hero 动效。
• 假设 animation-play-state 覆盖伪元素或 JavaScript RAF 循环。
• 在长页面上只信一次页顶测量。
• 把不可用的堆计数器当作没有内存泄漏的证据。
• 在 Browser 中运行无界的压力循环；用有界循环，并在不夸大因果的前提下记录崩溃。
• 只用截图作为性能证据。
• 让不相关的本地 hunk 搭车进入提交。