GSAP 是一套 JavaScript 动画库，而本条目介绍的是它在 HyperFrames 中的使用方式与约定，属于 HyperFrames 的动画参考文档。
用途与运行时约定 HyperFrames 通过其 gsap 运行时适配器控制 GSAP。使用时需要同步创建一个暂停的时间线（paused: true），并以与 composition 根节点上 data-composition-id 完全一致的键注册到 window.__timelines，然后由 HyperFrames 对该时间线进行 seek 播放。示例中通过 CDN 引入 gsap 3.14.2，并在同一段脚本内创建时间线、添加补间、写入 window.__timelines["main"]。文档强调：注册表的键必须与 composition 根节点的 data-composition-id 匹配；对于渲染关键的运动，不要调用 tl.play()；不要在异步代码、定时器或事件处理器内部构建时间线；循环必须有限，因为 HyperFrames 渲染的是有限时长的视频。
主要能力 文档覆盖的核心补间方法包括 gsap.to(targets, vars)（从当前状态动画到 vars，最常用）、gsap.from(targets, vars)（从 vars 动画到当前状态，用于入场）、gsap.fromTo(targets, fromVars, toVars)（显式指定起止状态）以及 gsap.set(targets, vars)（立即应用，时长为 0）。属性名一律使用 camelCase（如 backgroundColor、rotationX）。
常用配置项包括：duration（秒，默认 0.5）、delay（开始前的秒数）、ease（默认 "power1.out"，也支持 "power3.inOut"、"back.out(1.7)"、"elastic.out(1, 0.3)"、"none" 等）、stagger（数字如 0.1，或对象如 { amount: 0.3, from: "center" }、{ each: 0.1, from: "random" }）、overwrite（false 默认、true 或 "auto"）、repeat（必须是有限数字，在 HyperFrames 中绝不能用 -1，重复次数应根据可见时长计算）、yoyo（配合 repeat 交替方向）、以及 onComplete、onStart、onUpdate 回调。immediateRender 对 from()/fromTo() 默认为 true，若后续补间作用于同一元素的同一属性，可将其设为 false 以避免覆盖。
变换与 CSS 文档建议优先使用 GSAP 的变换别名而非原始 transform 字符串：x、y、z 对应 translateX/Y/Z（px）；xPercent、yPercent 对应百分比 translateX/Y；scale、scaleX、scaleY；rotation 对应 rotate（度）；rotationX、rotationY 对应 3D 旋转；skewX、skewY；transformOrigin 对应 transform-origin。autoAlpha 优于 opacity——值为 0 时还会设置 visibility: hidden。还支持 CSS 变量（如 "--hue": 180）、仅用于 SVG 的 svgOrigin（全局 SVG 坐标空间原点，不要与 transformOrigin 同时用于同一 SVG 元素）、方向性旋转（如 "360_cw"、"-170_short"、"90_ccw"）、clearProps（"all" 或逗号分隔，完成后移除内联样式）以及相对值（"+=20"、"-=10"、"*=2"）。
基于函数的值 可为属性传入函数，接收 (i, target, targets)，例如 x: (i) => i * 50 配合 stagger: 0.1。
缓动与默认值 内置缓动有 power1–power4、back、bounce、circ、elastic、expo、sine，每种都有 .in、.out、.inOut 变体。可通过 gsap.defaults({ duration: 0.6, ease: "power2.out" }) 设置全局默认值。
补间控制 补间返回值可用于控制：pause()、play()、reverse()、kill()、progress(0.5)、time(0.2)。
gsap.matchMedia() 用于响应式与无障碍：仅当媒体查询匹配时运行 setup，不再匹配时自动回退。示例中通过 mm.add 传入条件对象（isDesktop、reduceMotion），在回调内用 context.conditions 判断，例如根据是否为桌面端设置 rotation 为 360 或 180，并在 prefers-reduced-motion 时把 duration 设为 0。
时间线 可用 gsap.timeline({ defaults: { duration: 0.5, ease: "power2.out" } }) 创建时间线并链式添加补间。位置参数为第三个参数：绝对值（1，表示第 1 秒）、相对值（"+=0.5" 表示前一个结束后、"-=0.2" 表示前一个结束前）、标签（"intro"、"intro+=0.3"）、对齐（"<" 与上一个同时开始、">" 在前一个结束后、"<0.2" 在前一个开始后 0.2 秒）。标签可用 tl.addLabel("intro", 0) 添加，并可配合 tl.play("outro")、tl.tweenFromTo("intro", "outro") 使用。时间线选项包括 paused（创建时暂停，需调用 .play() 启动）、repeat、yoyo、defaults（合并到每个子补间）。嵌套时可通过 master.add(child, 0) 将子时间线加入主时间线。播放控制包括 play()、pause()、reverse()、restart()、time(2)、progress(0.5)、kill()。
性能 优先动画 transform 与 opacity（x、y、scale、rotation、opacity），它们可留在合成器上；当变换能达到相同效果时，避免使用 width、height、top、left。will-change: transform 只加在真正需要动画的元素上。频繁更新可用 gsap.quickTo()，示例中分别创建 xTo、yTo，并在 mousemove 事件里调用。多个元素用 stagger 优于手写延迟的多个补间。清理方面，应暂停或杀死离开屏幕的动画。
按需加载的参考 references/effects.md 提供即用效果：打字机文本、音频可视化器；在需要为 HyperFrames 提供现成效果模式时阅读。
适用场景与限制 本文档面向在 HyperFrames 中制作动画与视频合成、需要精确控制时间线与播放进度的场景，也适用于一般的 GSAP 补间、时间线、响应式与性能优化参考。限制与注意点包括：必须在 DOM 存在之后创建补间；不要用 delay 链式串联而应用时间线排序；同一 SVG 元素不要同时使用 svgOrigin 和 transformOrigin；不要跳过清理；在 HyperFrames 合成中不要使用无限 repeat 值，而应按可见时长计算有限的重复次数。
来源与参考 HyperFrames 适配器源码位于 packages/core/src/runtime/adapters/gsap.ts；GSAP 文档见 https://gsap.com/docs/v3/ ；时间线暂停与 seek 行为见 https://gsap.com/docs/v3/GSAP/Timeline/pause%28%29/ 。