HyperFrames 动画

将全部运动知识整合于一项技能中：规则（原子级配方）、蓝图（多阶段场景模板）、转场（场景到场景的衔接）、技法（更广义的动效设计模式），以及 适配器（面向各运行时的 API 封装）。

关于组合契约（数据属性、子组合、确定性）请参阅 hyperframes-core。

默认方式：组合原子规则

从 rules-index.md 中选取 2–4 条规则，用单个已暂停的 GSAP timeline 将其串联即可。此方式比从蓝图起步更快，且生成代码量更少。

何时加载蓝图

• 当前场景恰好匹配某个已有预设的多阶段模板（如品牌亮相、社交证明等），复用其阶段流水线可显著节省实际创作时间
• 你需要一段可直接运行的、作为“真实基准”的复杂 4–5 阶段编排代码

蓝图清单位于 blueprints-index.md。每个条目指向 blueprints/.md（配方文件）。请勿预先通读；仅当已明确需要场景级编排能力时再加载。

导航指引

运行时选型指南

• GSAP 是 95% 动效工作的默认选择——覆盖 timeline 编排、变换、缓动、错序等全部核心能力。本技能中所有原子规则均基于 GSAP 构建。
• Lottie 适用于自带预烘焙时间轴的资源（通常为 After Effects 导出）。
• Three.js 适用于 3D 场景、摄像机动画、着色器驱动的视觉效果。
• Anime.js 适用于轻量级补间需求，当 GSAP 显得过于厚重时选用。
• CSS 适用于简单重复的装饰性动效（如闪烁、微动），零 JavaScript 动画开销。
• WAAPI 适用于无需引入 GSAP 依赖的原生浏览器关键帧动画。
• TypeGPU / WebGPU 适用于 GPU 渲染的 Canvas 场景（粒子系统、液态玻璃、自定义着色器等）。

多个运行时可在同一组合中共存。每个运行时将其实例注册至对应全局对象（如 window.__timelines），以便 HyperFrames 在一次遍历中统一 seek 所有实例。

关键约束条件

前提条件：hyperframes-core → 不可协商的规则（必须使用单个已暂停的 timeline；data-duration 控制总时长；禁止使用 Math.random / Date.now / performance.now；禁止设置 repeat: -1；禁止在后续场景片段上于页面加载时调用 gsap.set；禁止对 display 或原始 visibility 属性执行补间；禁止在 async / setTimeout / Promise 内部构建 timeline）。GSAP 的 autoAlpha 及在明确 timeline 边界处设置的零时长 visibility 补间仍被 core 允许。但仅限用于非片段元素或片段内部的包装器；框架完全掌控 .clip 生命周期。此处无需重复全文契约内容。

在 core 契约基础上补充的动效工程规范：

• 预计算布局常量 —— 禁止在补间执行时刻调用 getBoundingClientRect() 推导位置。因渲染器并行采样，运行时 DOM 测量会导致不同步；务必在组合初始化阶段一次性计算坐标，并全程复用。
• 空间运动仅使用 GSAP 变换别名（x、y、scale、rotation）。core 的白名单还允许对非空间属性进行补间（opacity / color / backgroundColor / borderRadius），但严禁使用 width / height / top / left 等影响布局的属性。

脚本工具

node skills/hyperframes-animation/scripts/animation-map.mjs  
  --out /.hyperframes/anim-map

读取注册在 window.__timelines 上的所有 GSAP timeline，枚举其中补间、采样包围盒（bboxes）、计算各类标志位，最终输出 animation-map.json。建议在完成创作后运行该脚本，用于审计编排质量（例如检测空白区间、错序一致性、生命周期警告等）。

animation-map.mjs 优先从当前项目解析辅助包，随后可回退至内置的 HyperFrames 包版本。仅当在非捆绑 CLI/技能安装环境下运行该技能，且需显式锁定引导版本时，才需设置 HYPERFRAMES_SKILL_PKG_VERSION=。

参见

• hyperframes-core —— 组合结构、数据属性、子组合、确定性渲染契约
• hyperframes-creative —— 色板、排版、旁白、节拍规划（非动画类创意指导）
• hyperframes-cli —— npx hyperframes lint / check / snapshot / preview / render