插件安装： 在运行设置或刷新命令之前，如果此技能位于 HyperFrames 插件内部，请遵循 插件执行规则。独立安装则保留下面的更新说明。
HyperFrames 动画
所有动效知识汇集于一个技能：规则（原子配方）、蓝图（多阶段场景模板）、过渡（场景到场景）、技巧（更广泛的动效设计模式）以及适配器（各运行时 API）。
关于合成契约（数据属性、子合成、确定性的详细说明）请参阅 hyperframes-core。
默认方式：组合原子规则
从 rules-index.md 中挑选 2-4 条规则，将它们用一条暂停的 GSAP 时间线串联起来即可。这比从蓝图开始更快，生成的代码也更少。
何时加载蓝图
- 当场景匹配已有的预设计多阶段模板（品牌展示、社交证明等），且复用其阶段流程可以节省大量创作时间。
- 当你需要针对复杂的 4-5 阶段编排获得可运行的真实基准代码时。
蓝图位于 blueprints-index.md。每个条目指向 blueprints/<id>.md（配方）。不要凭空读取；只有在确定需要场景级编排时才应加载它。
路由表
| 目标 | 读取内容 |
|---|---|
| 按触发器/标签挑选原子动画模式 | rules-index.md |
| 阅读某个规则的完整 HTML / CSS / GSAP 配方 | rules/<name>.md |
| 挑选多阶段场景模板 | blueprints-index.md |
| 阅读某个蓝图的完整配方 | blueprints/<id>.md |
| 编写场景过渡（CSS 驱动，在两个片段之间） | transitions/overview.md, transitions/catalog.md |
| 查阅更广泛的动效设计技巧 | techniques.md |
| 运动模糊——元素上的快门拖影效果，以及何时不应使用 | references/motion-blur.md |
| 分析现有合成的动画映射 | scripts/animation-map.mjs |
| GSAP API —— 时间线 / 补间 / 位置参数 | adapters/gsap.md |
| GSAP —— 即用型效果配方 | rules/gsap-effects.md |
| GSAP —— 变换 / 性能 | adapters/gsap-transforms-and-perf.md |
| GSAP —— 缓动 / 交错 | adapters/gsap-easing-and-stagger.md |
| GSAP —— 时间线 / 标签 | adapters/gsap-timeline-and-labels.md |
Lottie / dotLottie（After Effects 导出，window.__hfLottie） | adapters/lottie.md |
| 角色动画（行走循环、吉祥物、关节木偶、手势） | adapters/lottie.md → Characters |
Three.js / WebGL（3D 场景，AnimationMixer，hf-seek） | adapters/three.md |
Anime.js（window.__hfAnime） | adapters/animejs.md |
CSS 关键帧（animation-delay / play-state / fill-mode） | adapters/css-animations.md |
Web 动画 API（element.animate()，currentTime 寻址） | adapters/waapi.md |
TypeGPU / WebGPU（navigator.gpu，WGSL，计算管线） | adapters/typegpu.md |
HTML 纹理 + WebGL/GLSL 后期特效（通过 drawElementImage 捕获实时 DOM） | adapters/html-in-canvas-patterns.md |
命名字本动画效果（24 个 ID，通过外部 animate-text 技能实现） | adapters/animate-text.md |
运行时选择指南
- GSAP 是 95% 动效工作的默认选择——涵盖时间线编排、变换、缓动、交错。本技能中的所有原子规则均基于 GSAP。
- Lottie 用于资源自带预烘焙时间线的情况（通常是 After Effects 导出），包括行走、做手势或反应的角色。
- Three.js 用于 3D 场景、相机运动、着色器驱动的视觉效果。
- Anime.js 用于轻量级补间动画，当 GSAP 显得过度时使用。
- CSS 用于简单的重复图案、装饰、闪烁效果——无需 JavaScript 动画开销。
- WAAPI 用于无需 GSAP 依赖的原生浏览器关键帧。
- TypeGPU / WebGPU 用于 GPU 渲染的画布（粒子、液态玻璃、自定义着色器）。
多个运行时可以共存于一个合成中。每个运行时将其实例注册到特定于该运行时的全局变量上，以便 HyperFrames 可以通过单次寻道同时控制所有实例。
关键约束
前置条件：hyperframes-core → 一条暂停的时间线 + 不可协商的规则（单条暂停时间线，data-duration 控制长度，不能使用 Math.random / Date.now / performance.now，不能在没有有限根 data-duration 的情况下使用 repeat: -1，不能对后场景片段使用页面加载时的 gsap.set，不能使用 display 或原始 visibility 补间，并且必须在时间线完全构建后才注册它，包括在构建运行于异步回调（如 document.fonts.ready）内部时）。GSAP 的 autoAlpha 以及在明确的时间线边界处设置的零时长可见性仍被核心允许。仅可对非片段元素或片段包装器使用这些例外；框架拥有 .clip 的生命周期。此处不再重述完整契约。
在核心契约基础上增加的动画创作约束：
- 预先计算的布局常量 —— 切勿在补间时刻从
getBoundingClientRect()推导位置。补间时的 DOM 测量会导致反序列化，因为渲染器会并行采样；在合成设置时一次性计算坐标并重复使用。 - 空间运动仅使用 GSAP 变换属性别名（
x、y、scale、rotation）。核心的允许列表也允许opacity/color/backgroundColor/borderRadius用于非空间属性的补间——但绝不允许使用width/height/top/left来实现布局变化。
脚本
node <SKILL_DIR>/scripts/animation-map.mjs <composition-dir> \
--out <composition-dir>/.hyperframes/anim-map
读取注册在 window.__timelines 上的所有 GSAP 时间线，枚举补间，采样边界框，计算标志，输出 animation-map.json。用于在创作后审计编排（空白区域、交错一致性、生命周期警告）。
animation-map.mjs 首先从当前项目解析辅助包，然后可以引导捆绑的 HyperFrames 包版本。仅在技能在捆绑的 CLI/技能安装之外运行，并且你需要显式固定引导版本时，设置 HYPERFRAMES_SKILL_PKG_VERSION=<version>。
参见
hyperframes-core—— 合成结构、数据属性、子合成、确定性渲染契约hyperframes-creative—— 调色板、排版、叙述、节拍规划（非动画创意方向）hyperframes-cli——npx hyperframes lint / check / snapshot / preview / render