OpenMontage HyperFrames 动画技能实战指南：原子规则、场景蓝图、转场与七种运行时适配器的编排体系

导读

本文面向需要在 OpenMontage 中为 HyperFrames 合成作品编写动画的工程师与 Agent。它逐层拆解仓库内 .agents/skills/hyperframes-animation/SKILL.md 定义的知识组织方式——从可按需拼接的原子动画规则（rules）、预先设计的多阶段场景蓝图（blueprints）、场景间转场（transitions）、通用动效技法（techniques）到 GSAP/Lottie/Three.js/Anime.js/CSS/WAAPI/TypeGPU 七类运行时适配器（adapters）。读完你将掌握 HyperFrames 动画的选型路径：默认"选 2–4 条规则用一条暂停的 GSAP 时间线拼装"，需要整场景编排时再加载蓝图，并能用 animation-map.mjs 审计编舞质量；同时了解这套动画知识如何被 OpenMontage 的 hyperframes_compose 渲染管线消费，受 hyperframes-core 确定性渲染契约约束。

---

一、技能定位：一张覆盖全部动画知识的导航图

在 OpenMontage 的技能分层中，.agents/skills/hyperframes-animation/SKILL.md 是描述性字段为 "All animation knowledge for HyperFrames" 的领域技能，与 hyperframes-core（合成契约）、hyperframes-creative（色彩/字体/旁白等非动画创意）、hyperframes-media（TTS/BGM/字幕）、hyperframes-cli（lint/validate/render）、hyperframes-registry（registry 块）互为兄弟模块。核心路由说明见 skills/core/hyperframes.md。

该技能把动画知识划分为五类，正文即五层导航：

1. rules（原子配方）——单条可复用的运动配方，覆盖文本、数据、镜头、布局、SVG、氛围与入场等类别；
2. blueprints（多阶段场景模板）——面向整个镜头的、带时间码的场景级模板（brand-reveal、social-proof 等"已被验证的形状"）；
3. transitions（场景转场）——CSS 驱动、发生于两条 clip 之间的衔接；
4. techniques（通用动效技法）——SVG 描线、Canvas 2D 程序化图形、CSS 3D、逐词 kinetic 文字等跨场景模式；
5. adapters（各运行时 API）——GSAP 默认 + Lottie / Three.js / Anime.js / CSS keyframes / Web Animations API / TypeGPU 等七类运行时。

与 hyperframes-core 的边界：合成的组成契约（data-* 时间属性、子合成、可确定性渲染规则）属于 hyperframes-core，本技能只在此之上补充"动画工艺"层约束。前置阅读顺序建议是 .agents/skills/hyperframes-core/SKILL.md → 本文。

默认工作流：组合原子规则

技能文档明确给出首选路径：从 rules-index.md 选 2–4 条规则，用一条 paused GSAP timeline 粘合。相比从蓝图起步，这一方式代码量更少、执行更快（这正是"组合优于模板"的默认姿势，详见 SKILL.md）。

何时该加载蓝图

只有以下两种情况才去读蓝图：

• 场景命中了现成的多阶段模板（brand-reveal、social-proof 等），复用其阶段管线能省下大量创作时间；
• 你需要一个可直接运行的 4–5 阶段复杂编排的 ground-truth 代码。

蓝图的索引与配方分别在 blueprints-index.md 与 blueprints/<id>.md。技能文档明确提醒：不要投机性地提前阅读蓝图，只有确定需要场景级编排时才加载（见 SKILL.md）。

---

二、快速路由表：需求 → 该读哪个文件

SKILL.md 内置一张"想要什么 → 读什么"的路由表，是实际创作时的第一入口，完整摘录并附仓库内路径如下：

想做的事	读取文件
按触发器/标签挑选原子运动模式	rules-index.md
读取某条规则的完整 HTML/CSS/GSAP 配方	rules/<name>.md（如 spring-pop-entrance.md）
挑选多阶段场景模板	blueprints-index.md
读取某蓝图的完整配方	blueprints/<id>.md（如 kinetic-type-beats.md）
编写场景转场（CSS 驱动、两 clip 之间）	transitions/overview.md、transitions/catalog.md
查阅更宏观的动效技法	techniques.md
分析既有合成的动画地图	scripts/animation-map.mjs
GSAP API——timeline/tweens/位置参数	adapters/gsap.md
GSAP——即插即用特效配方	rules/gsap-effects.md
GSAP——变换与性能	adapters/gsap-transforms-and-perf.md
GSAP——ease 与 stagger	adapters/gsap-easing-and-stagger.md
GSAP——timeline 与标签	adapters/gsap-timeline-and-labels.md
Lottie/dotLottie（AE 导出物，window.__hfLottie）	adapters/lottie.md
Three.js/WebGL（3D 场景、AnimationMixer、hf-seek）	adapters/three.md
Anime.js（window.__hfAnime）	adapters/animejs.md
CSS keyframes（delay/play-state/fill-mode）	adapters/css-animations.md
Web Animations API（element.animate()、currentTime 定位）	adapters/waapi.md
TypeGPU/WebGPU（navigator.gpu、WGSL、计算管线）	adapters/typegpu.md
HTML 作为纹理 + WebGL/GLSL 后期特效	adapters/html-in-canvas-patterns.md
具名文字动画特效（24 个 ID）	adapters/animate-text.md

---

三、原子规则库（rules）：按类别组织的运动配方

rules/ 目录下约 36 条规则按语义分为七大类，见 rules-index.md。每条规则文件都包含"How It Works + HTML + CSS + GSAP Timeline + 变体 + 参数选择"的完整配方，是可读、可复制的最小实现。

3.1 Text & Typography（文本与字体）

规则	说明	适用
hacker-flip-3d	字符级 3D 旋转 + 确定性字形替换（解密感），back.out + per-glyph onUpdate 制造闪动哈希	text/3d/reveal/decode
vertical-spring-ticker	老虎机式纵向滚动，遮罩列内 step GSAP tween	text/ticker/vertical
counting-dynamic-scale	计数器数字越大字号越大，单一数字代理上的 GSAP tween	counter/scale/number
discrete-text-sequence	在时间阈值整体替换文本状态（非线性的打字、typos、回退）	text/typing/threshold
asr-keyword-glow	按 ASR 词时间戳给关键词加 glow+scale+color，--glow 走 attack-decay-rest 包络	asr/audio-sync/highlight
3d-text-depth-layers	N 层偏移文本（(i*dx,i*dy) + 递减 alpha）制造堆叠 3D 挤压错觉	text/3d/depth/layers
context-sensitive-cursor	打字光标按分段边界切换颜色，方形波闪烁 (tl.time()%cycle)<cycle/2	cursor/typewriter
dynamic-content-sequencing	由内容驱动时长：{textMain,textAccent,charSpeed,hold} 预计算扁平时间窗	timeline/script-driven
kinetic-beat-slam	打击乐式 kinetic 文字：短语在共享 beat 数组上以不同入场方式"砸"入	text/kinetic/rhythm/punchy

其中一条值得展开的"方法论规则"是 dynamic-content-sequencing：它把"一个场景连续展示多个内容块"的时长计算从手写偏移变成内容驱动。每个条目只有 {text, speedFactor, hold}，绝对开始时间 start[i] = Σ durations(0..i-1)，在 onUpdate 里查找"start ≤ time 的最后一条"渲染。长文本天然获得更多银屏时间，公式为 baseDuration + textLength × msPerChar，彻底告别逐条手写 from/durationInFrames。

3.2 Data & Stats（数据与统计）

• counting-dynamic-scale（与 3.1 共用，seek-safe 的 onUpdate+Math.round+tabular-nums+多统计 chord）
• stat-bars-and-fills：增长柱（CSS scaleY stagger）、进度填充（scaleX 或量测过的 SVG 环）、星级打分擦除（clip-path）。只动 transform，seek-safe。

3.3 Camera & Viewport（虚拟镜头与视口）

规则	一句话原理
coordinate-target-zoom	通过外层 scale + 内层反向位移，推进到非居中元素；T = -offset
camera-cursor-tracking	两阶段虚拟镜头（静态构图 → 锁定打字光标焦点），document.fonts.ready 后用原生测量
multi-phase-camera	顺序式镜头推进（pull-back/focus/push）+ 连续微漂移
viewport-change	用单一 .world 包装层做 translate(x,y) scale(S) 模拟 zoom/pan；此处反向位移公式是 T = -offset×S（与 coordinate-target-zoom 不同！）
depth-of-field-blur	通过 --dof 变量对离焦层做 filter: blur() 的选择性跟焦，焦点元素保持清晰

规则库甚至以"两条不同公式"的对照方式，把 coordinate-target-zoom（T=-offset）与 viewport-change（T=-offset×S）刻意区分，说明"缩放包围盒内平移"与"整体视口放大"在数学上的差异——这类来自真实渲染的坑，正是该技能库的实用价值。

3.4 Layout & Network（布局与网络）

avatar-cloud-network（椭圆环头像+中心连线+stagger）、3d-page-scroll（网页做成倾斜 3D 卡再内滚）、center-outward-expansion（元素从中心聚类扩到最终位，共享驱动 tween x/y 归零）、split-tilt-cards（左右反向 rotateY 的对开卡片 + 反相浮动 Math.PI 相位差）、orbit-3d-entry（3D 空间翻转入场后在椭圆轨道持续运动，必须在轨道起点就位再翻入，不能用场景中心）、ai-tracking-box（AI 检测框：黄色 #facc15 L 角 + 95–99% 置信标签沿正弦弧跟随目标，框位置每帧由目标位重算、绝不单独 tween）、depth-scatter-assemble（N 元素从确定性下标推得的 3D 深度云中散开/重组，支持 tumble-swap 与 radial-explode 变体）。

3.5 SVG & Icons

• svg-icon-enrichment：让图标"活"起来的内部元素微动（旋转指针、摆动叶片、脉冲点、虚线流动）。关键：SVG 内部元素要用 setAttribute('transform','rotate(deg cx cy)') 显式中心，因为 CSS transform-origin + transform-box:fill-box 对细线会以 bbox 局部坐标为原点而偏离。
• svg-path-draw：用 stroke-dasharray/dashoffset 让轮廓逐笔自绘；setup 时用 getTotalLength() 量全长，初始 dashoffset=全长，GSAP tween 到 0。圆形进度环要把描边旋转 -90deg 让绘制从 12 点方向开始。

3.6 Idle & Ambient（静置与氛围）

• sine-wave-loop：呼吸/静置环境动。两种形态：GSAP sine.inOut yoyo 有限 repeat（独立用优先），或 onUpdate 读取 tl.time()（叠加到别的活动量上时用）。
• ambient-glow-bloom：非触发的柔光径向绽放 + 有界呼吸，或单程掠过高光的 sheen。峰值不透明度 ≤ ~0.45，有限/确定性，无点击无词同步。

3.7 Transition & Motion（物理与转场）

reactive-displacement（入场元素 tween 驱动退场元素位移的"碰撞因果"转场，受害元素时长取闯入者的 40–50%）、press-release-spring（按钮按压：线性压缩 + 弹性恢复两段相邻 tween）、physics-press-reaction（两个顺序 scale tween 模拟弹簧过冲，可传多 target 数组 ["#cta","#cursor"] 得到触点接触感）、cursor-click-ripple（光标移动→共同下压→扩展波纹）、scale-swap-transition（同屏中心两元素协调 morph：退场簇缩小淡出、入场 back.out(2) 弹出）、card-morph-anchor（容器在两次镜头间 morph 尺寸/圆角/表面处理——用统一 scale 替代被禁止的 width/height tween）、spring-pop-entrance（规范入场 pop，详见下文）、motion-blur-streak（入场/推进时伪造方向速度模糊：峰在最高速、落点归零；SVG feGaussianBlur 代理 tween 或确定性 ghost trail）。

规范入场 pop：spring-pop-entrance 深度拆解

这是整个动画体系的"入门 + 权威"规则，也是所有 blueprint 依赖的基础动作，见 spring-pop-entrance.md。其核心：

<script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
<script>
  window.__timelines = window.__timelines || {};
  const tl = gsap.timeline({ paused: true });

  // 单主体：fromTo 显式写出坍缩起始态，保证 t=0 被 seek 时状态正确
  tl.fromTo(
    "#hero",
    { scale: 0, opacity: 0 },
    {
      scale: 1,
      opacity: 1,
      duration: POP_DUR,
      ease: "power3.out", // 平滑优先于弹跳；expo.out 可做更快的前段
    },
    ENTRY_AT,
  );

  // 分组：确定性的 index 派生 stagger（禁 Math.random）
  // 窗口上限约束：ITEM_COUNT × STAGGER ≤ ~0.5s，让整组读作"一次到达"
  const items = gsap.utils.toArray(".pop-item");
  items.forEach((el, i) => {
    tl.fromTo(
      el,
      { scale: 0, opacity: 0, y: Y_RISE },
      {
        scale: 1,
        opacity: 1,
        y: 0,
        duration: POP_DUR,
        ease: "power3.out",
      },
      GROUP_ENTRY_AT + i * STAGGER,
    );
  });

  window.__timelines["pop-scene"] = tl;
</script>

设计要点（这也是技能文档的"品味守则"）：

• 平滑压倒弹跳：power3.out 长尾减速 + 无过冲是默认（"house style"）；back.out 弹跳被明确定性为 #1 instant turn-off，仅限明确的娱乐化/大众品牌语境，且过冲 ≤ ~2；
• 必须是 fromTo 而非 from：from() 朝当前 CSS 动画，与 opacity:0 搭配会成 0→0 noop 而永不显示（该禁忌在 transitions/overview.md 与 hyperframes-core 中被双重强调）；
• POP_DUR 建议 0.4–0.7s；主体必须在 t ≤ 0.5s 内到达可读中点；
• 分组 stagger：STAGGER 0.04–0.08s，整组窗口 ≤ ~0.5s；
• 与 press-release-spring（点击/按压反应，有按压阶段）明确区分——本规则没有按压阶段，元素直接"无中生有"地弹入，落地后最多交给 sine-wave-loop 做微小 jitter，不得内嵌无限呼吸环。

3.8 Effect Recipes（来自 hyperframes-creative 的特效配方）

• gsap-effects：即插即用的 GSAP timeline 模式——typewriter、audio visualizer 等可复用编舞块；
• css-marker-patterns：纯 CSS + GSAP 的马克笔高亮绘制模式（highlight 黄色横扫、circle 手绘椭圆、burst 放射线、scribble 乱涂、sketchout 粗糙矩形轮廓）。

每条规则都带 Tags 元数据，这是"按触发器/标签检索"的索引依据；blueprint 的 rule mapping 一节会显式引用具体规则（如 kinetic-type-beats 逐条映射到 discrete-text-sequence、kinetic-beat-slam、spring-pop-entrance、depth-scatter-assemble、css-marker-patterns 等），保证场景模板全部由已验证的原子配方支撑，见 kinetic-type-beats.md。

---

四、场景蓝图库（blueprints）：被验证的 15 种镜头形状

4.1 什么是 blueprint

blueprint 是一份产品无关、带时间码的镜头模板——Scene N (a–b s): … + [slots] + 一个命名 signature move（招牌动作）。它是从 50 支 golden product-launch 短片（外加 13 支反向翻译成同格式的 hyperframes-animation 蓝图）逆向提炼而来，见 blueprints-index.md。蓝图把整支镜头的揭示节奏铺到旁白上，而不是在 t=0 一次性倾倒内容。

4.2 15 个蓝图速览

ID	服务角色	时长	一句话概括
kinetic-type-beats	Hook/Problem/Product_Intro/Benefits/CTA/Brand_Outro	3.4–12s	运动的字就是主角：固定行原地换 token 或全屏分拍累积，落到 spring-pop 收尾（workhorse，6 角色）
typewriter-reveal	Hook/Brand_Outro	3.6–7s	真人般打字/编辑一行字后收起并 pop 品牌收尾
spatial-pan-stations	Hook/Problem	7–10s	一块超宽画布上的预置标签站，被单一虚拟镜头横向/斜向扫过
constellation-hub	Hook/Social_Proof	5–6s	图标节点弹入中心环后聚拢于核心（景深推进或卫星环绕的 held hub mark）
grid-card-assemble	Key_Feature/Benefits/Social_Proof	3.0–10.5s	N 个 tile/卡/logo 级联自组装进网格/竖排并 hold，可选 zoom-out
logo-assemble-lockup	Product_Intro/CTA/Brand_Outro	4.6–11s	品牌 mark 从零件自组装成居中的 lockup（可扩到 URL/CTA）
cursor-ui-demo	Product_Intro/Key_Feature	4.0–9.3s	可见自定义光标驱动重建的 UI，摄像机追每次交互
device-surface-showcase	Key_Feature（角色窄）	7.8–9.6s	设备 mockup/悬浮窗当 hero，屏内真实流程流转
dataviz-countup	Problem/Product_Intro	6–12s	数字与图表当主角，镜头推进穿过落地到 hero 指标
titlecard-reveal	Benefits/Social_Proof	3–5s	用恰好一个克制动作揭示的冷静标题/品牌卡（low motion 是卖点）
comparison-split	Key_Feature	4–6s	两等重项对开镜像"翻书"进入后并排，内缘 pill 徽章 pop
overwhelm-surround	Problem	6–9s	累积压迫：中心项 morph 成观众自己的头像，元素从四面合围
ticker-takeover	Hook/Brand_Outro	5–7s	轮换词被从画外砸入的 hero 物理撞开（collision 而非 fade）
video-text-pivot	Product_Intro/Key_Feature	6–8s	产品视频滑到侧边让位给 hero 指标，再 kinetic 文字落入空位
cta-morph-press	CTA	4–6s	品牌 mark 同中心凝缩为更亮的 CTA，光标落地一次"类人点击"

角色覆盖保证：每个角色 ≥2 个候选；每个蓝图服务 ≥1 角色。新增五支补齐语料的形状为 depth-of-field-blur、motion-blur-streak、depth-scatter-assemble、spring-pop-entrance、ambient-glow-bloom（blueprints-index.md 的 Motion coverage 节明确每个 blueprint 的 rule mapping 引用真实规则）。

4.3 挑选步骤与三档姿态

blueprints-index 给出了可操作的 4 步流程（见 blueprints-index.md）：

1. 在 Role → blueprint 菜单中定位当前帧的角色，挑"形状贴合的"那支（菜单是 软性 菜单：story truth 优先，菜单不是 checklist）；
2. 打开 blueprints/<id>.md 读时间码模板、[slots] 与命名 signature move；
3. 选择姿态：Reproduce（slots 干净映射）/ Adapt（结构适配但内容/表面不同，保留 signature move）/ Compose（什么都不合适 → 从运动词汇自由组合）；
4. 若菜单无匹配，宁可自由 compose，仍按 VO 把揭示铺满整支镜头，也不要硬套错误蓝图。

一个真实边界提醒：device-surface-showcase 的 3D 手势输入 + WebGL bloom/portal 需要 R3F/Three.js + WebGL，超出了规则库能力——要么省着用，要么选它的更简单变体。

---

五、场景转场（transitions）：CSS 驱动、语义驱动

5.1 铁律：转场是内容关系的语言

transitions/ 目录由 overview（策略）+ catalog（代码）+ 十几个 css-*.md（实现）构成，机器可读源是 TRANSITION-REGISTRY.md（PLV 场景转场的 JSON 注册表 + 注入器模板）。overview 开头定义四条多场景铁律：

1. 每个合成都必须使用转场——无转场 = jump cut；
2. 每个场景必须有入场动画（opacity/位置/scale），且必须用 gsap.fromTo() 而非 from()；
3. 退场动画被禁止（末场景除外）——转场本身即退场，出场景内容在转场触发时必须完全可见；
4. 唯一例外：最后场景允许淡出（如 fade to black）。

代码层面的正反例（见 overview.md）：

// ❌ BANNED —— 先淡出旧场景，再跑新场景入场 = 带暗场的 jump cut
tl.to("#s1", { opacity: 0, duration: 0.4 }, 4.0);
tl.from("#s2 .headline", { y: 40, opacity: 0 }, 4.4);

// ✅ CORRECT —— 出/入同时于时间 T 动画，运动本身就是交接
const T = 4.0;
tl.to("#s1", { yPercent: -100, filter: "blur(8px)", duration: 0.5, ease: "power3.in" }, T);
tl.fromTo("#s2", { yPercent: 100 }, { yPercent: 0, duration: 0.5, ease: "power3.out" }, T);

5.2 能量→主转场，情绪→转场类型

能量分级决定主转场与时长/缓动（见 overview.md）：

能量	CSS 主转场	时长	Easing
Calm（wellness/brand/luxury）	Blur crossfade、focus pull	0.5–0.8s	sine.inOut、power1
Medium（corporate/SaaS/explainer）	Push slide、staggered blocks	0.3–0.5s	power2、power3
High（promo/sports/music/launch）	Zoom through、overexposure	0.15–0.3s	power4、expo

原则是：选 1 个主转场（覆盖 60–70% 场景切换）+ 1–2 个 accent，绝不给每帧换不同转场。同时情绪必须匹配内容——例如 Mood→Type 映射表建议：Warm/inviting → light leak/blur crossfade；Tech/futuristic → grid dissolve/blinds/chromatic aberration；Dramatic/cinematic → zoom through/color dip to black；Premium/luxury → focus pull + cross-warp morph（克制）。

5.3 转场落地：位置→动画→交换

catalog 提供了完整模板与硬规则：Scene 1 默认可见（不设 opacity:0），Scene 2+ 容器设 opacity:0 由 GSAP 揭示；不用 visibility shim；字体直接写 font-family 交给编译器以 data-URI @font-face 内联；scene div 不加 class="clip"（只有根 div 有 data-*）；z-index 规则（gravity drop/zoom out/diagonal split 需要出场景在上层 zIndex:10）等，详见 catalog.md。shader 类转场由 @hyperframes/shader-transitions 包承接，但需遵守 overview 中的 shader-compatible CSS 规则。

警告：overview 末尾明确提醒——只读 overview 就写转场，正是产出上面 ❌ 模式的途径；动手前必须打开同目录 catalog.md 与对应 css-*.md。转场硬规则可概括为 position new scene → animate outgoing → swap → animate incoming → clean up overlays。

---

六、宏观动效技法（techniques.md）

techniques.md 收录 13 个生产级技法（非进阶、是每个合成至少该用 2–3 个的标准动效设计模式）：SVG path drawing、Canvas 2D 程序化图形、CSS 3D transforms、逐词 kinetic typography、Lottie、视频合成、逐字符打字、可变字体轴动画、GSAP MotionPathPlugin、速度匹配转场、音频响应动画、clip-path 揭示遮罩、WebGL fragment shader 艺术。

每个技法自带最小可改代码，例如 SVG path drawing：

<svg viewBox="0 0 400 200">
  <path class="draw-path" d="M 50 100 L 200 50 L 350 100"
        stroke="#c84f1c" stroke-width="4" fill="none" stroke-linecap="round"/>
</svg>
<style>
  .draw-path { stroke-dasharray: 280; stroke-dashoffset: 280; }
</style>
<script>
  tl.to(".draw-path", { strokeDashoffset: 0, duration: 0.7, ease: "power2.out" }, 0.5);
</script>

Canvas 2D 程序化图形则强调确定性哈希：hash(x,y) 采用固定整数运算，确保"同帧每次渲染相同"（drawFrame(t) 由 GSAP proxy tween 驱动，杜绝 wall-clock）。文件顶部还给出了三条外链参考：HTML-as-texture（重型能力，每个视频 1–3 个 hero beat 用，见 adapters/html-in-canvas-patterns.md）、easing 词汇表（每个合成至少 3 种 ease，见 adapters/gsap-easing-and-stagger.md）、具名文字动画 24 个 ID（见 adapters/animate-text.md）。

---

七、七种运行时与适配器契约

7.1 运行时选择原则

SKILL.md 明确给出（SKILL.md）：

• GSAP：95% 运动工作的默认运行时——timeline 编排、transform、easing、stagger 全覆盖，技能内所有原子规则均为 GSAP 实现；
• Lottie：资产自带预烘焙时间线时（典型如 After Effects 导出）；
• Three.js：3D 场景、镜头运动、shader 驱动视觉；
• Anime.js：GSAP 过重的轻量 tween；
• CSS：简单重复母题、装饰、shimmer——零 JS 动画成本；
• WAAPI：不想引入 GSAP 依赖时的原生浏览器关键帧；
• TypeGPU/WebGPU：GPU 渲染画布（粒子、liquid glass、自定义 shader）。

一个合成可以多运行时共存：每个运行时把自己的实例注册到专属全局上（如 window.__hfLottie、window.__hfAnime），HyperFrames 就能"一趟 seek 全部"。这与 adapters 的统一模式完全一致——"合成拥有动画对象，HyperFrames 拥有时钟"。

7.2 统一适配器契约（各 adapter 头文件摘录）

运行时	注册全局	由适配器 seek 的方式
GSAP	window.__timelines["<id>"]	框架 seek paused timeline（禁止 tl.play()）
Lottie/dotLottie	window.__hfLottie	goToAndStop(timeMs,false) / 帧/百分比 API
Anime.js	window.__hfAnime	instance.seek(timeMs)
WAAPI	document.getAnimations()	设置每动画 currentTime=time 后 pause
CSS keyframes	探测带 animation-name 的元素	优先浏览器 Animation 句柄，回退负 animation-delay 暂停
Three.js	window.__hfThreeTime + 派发 hf-seek 事件	组合从 HyperFrames 时间渲染
TypeGPU/WebGPU	window.__hfTypegpuTime + hf-seek	GPU 管线上传时间 uniform 后重渲染

GSAP 作为默认适配器，其契约细节（adapters/gsap.md）是理解整套体系的关键：

• 同步创建 gsap.timeline({ paused: true })，注册到 window.__timelines["<id>"]，key 必须等于组合根节点的 data-composition-id；
• 禁止在 async/定时器/事件处理器里构建 timeline（渲染器可能在你完成前就采样）；
• 循环必须有限：HyperFrames 渲染的是有限时长视频；
• 渲染时长来自根节点 data-duration，不是 GSAP timeline 长度——不要用空 tween 去"延长"；
• 属性名一律 camelCase。

Anime.js 与 Lottie 模式都强调 autoplay:false + 有限 duration/loop + 同步创建（示例代码见 animejs.md 与 lottie.md）。CSS 适配器要求 DOM 先就位、给定时元素 data-start、用有限 animation-iteration-count、偏好 fill-mode:both（见 css-animations.md）。WAAPI 直接给出 element.animate(...) + animation.pause() 的最小模式与 stagger 模式（waapi.md）。Three.js 与 TypeGPU 则通过监听 hf-seek 事件渲染"恰好那一帧"——Three.js 用 mesh.rotation.y = time*0.7，TypeGPU 把时间写进 uniform buffer；TypeGPU 另有一个重要前提：html-in-canvas + WebGPU 组合需要 PRODUCER_HEADLESS_SHELL_PATH 指向 Brave/Chrome canary（headless-shell 不支持二者叠加），见 typegpu.md。

---

八、动画工艺红线（在 core 契约之上的追加约束）

SKILL.md 的 Critical Constraints 在 hyperframes-core 不可协商规则之上追加了两条动画工艺红线（SKILL.md）：

1. 预计算布局常量：绝不在 tween 时用 getBoundingClientRect() 推导位置——因为渲染器是并行采样的，tween 时测 DOM 会失步。坐标应在组合 setup 阶段算一次并复用；
2. 空间运动只用 GSAP transform 别名（x/y/scale/rotation）。core 的 allowlist 另允许对非空间属性做 opacity/color/backgroundColor/borderRadius tween——但布局变更永远不能动 width/height/top/left。

这两条红线与 hyperframes-core 的确定性根基一脉相承。底层原则在 determinism-rules.md 说得很透："HyperFrames 逐帧 seek 合成，每帧必须只由时间值可复现——同一输入时间 → 同一像素"。因此：

• 渲染关键视觉状态禁用 Date.now()/performance.now()、非种子 Math.random()、渲染期网络拉取、悬停/滚动/指针/焦点状态、repeat:-1；
• 只动画 allowlist 属性，禁 display/visibility；
• 布局上：根节点固定像素帧、场景容器 width/height:100%; box-sizing:border-box、正文不用 <br>（会让自然折行多出一个断行）、被 transform 的元素必须 block 级且定尺寸（inline <span> 上 scale 是 no-op，auto 宽元素 scale 后显示为 0）；
• 文本适配可借助 window.__hyperframes.fitTextFontSize 与 window.__hyperframes.pretext（纯算术布局，~0.0002ms/次，可逐帧用）。

这些约束在 hyperframes-core 侧被实现为双轨验证：静态 npx hyperframes lint + 浏览器内 npx hyperframes validate（seek 进 paused 合成、截图、像素采样、WCAG 对比度、校验 window.__timelines 注册与 class="clip"），见 hyperframes-core/SKILL.md。也就是说，本文第 3–6 节的所有规则/蓝图/转场/技法，都必须在上述确定性红线内运行——这正是该技能库把"好看"与"可渲染"统一起来的方式。

---

九、动画地图审计脚本：animation-map.mjs

创作完成后，可用仓库自带的审计脚本核验编舞质量（见 SKILL.md）。其真实签名包含更多参数（scripts/animation-map.mjs）：

node skills/hyperframes-animation/scripts/animation-map.mjs <composition-dir> \
  [--frames N] [--out <dir>] [--min-duration S] [--width W] [--height H] [--fps N]

# SKILL.md 中的默认用法（frames=6, out=.hyperframes/anim-map,
# min-duration=0.15s, 1920x1080@30）：
node skills/hyperframes-animation/scripts/animation-map.mjs <composition-dir> \
  --out <composition-dir>/.hyperframes/anim-map

脚本做的事情：读取注册在 window.__timelines 上的每条 GSAP timeline → 枚举 tweens → 对每个 tween 采样 bbox → 计算 flags → 输出 animation-map.json。用于创作后审计编舞的 dead zones（空窗）、stagger 一致性、生命周期告警。其内部会通过 package-loader.mjs 按需引导 @hyperframes/producer 包以启动文件服务器与截帧会话，默认丢弃短于 --min-duration(0.15s) 的 tween，并输出包含 composition、tween 明细与时长数据的报告对象。

---

十、在 OpenMontage 管线中的落地位置

hyperframes-animation 并非孤立存在，而是 OpenMontage 双层概念下的 Layer-3 技能。OpenMontage 分离 renderer_family（创意语法，如 explainer-data/cinematic-trailer/product-reveal）与 render_runtime（技术引擎：remotion/hyperframes/ffmpeg），二者在提案阶段锁定并通过 decision_log 记录（skills/core/hyperframes.md）。

决策矩阵对"何时选 HyperFrames"给出清晰指引（skills/core/hyperframes.md）：kinetic 文字/重文本运动、产品宣传片/发布短片、website-to-video/UI 驱动合成、需要 registry 块（data chart、grain overlay、shimmer sweep、shader transition）时选 HyperFrames；现成 Remotion 组件栈、逐字烧字幕、虚拟人讲播仍留在 Remotion。若 brief 的 delivery_promise.motion_required=true，则提案选定的运行时是承诺，compose 不得降级为 FFmpeg Ken Burns。

工程侧由 tools/video/hyperframes_compose.py 端到端接管：当 edit_decisions.render_runtime=="hyperframes" 时被 video_compose 调用，负责 workspace 物化、hyperframes lint/check/validate 与 hyperframes render；而 playbook → CSS 变量 + DESIGN.md 的桥接由 lib/hyperframes_style_bridge.py 完成（:root 上的 --color-bg/--color-accent/--font-heading/--ease-primary/--duration-primary 等 CSS 自定义属性 + 一份人读的 DESIGN.md）。组合时它会把 edit_decisions 的每个 cut 翻译成 index.html 中带 data-composition-id/data-composition-src 的 div、把 in_seconds/out_seconds 映射为 data-start/data-duration、把旁白与音乐分别映射为 <audio> 元素并设置 data-volume——动画规则与蓝图正是在这些 HTML 合成文件中被 agent 组合进 window.__timelines 的。

pipeline 采用节奏也已写入文档：animation、animated-explainer、screen-demo 为 Wave 1（动画/HTML+GSAP 原生概念的动效优先选 HyperFrames），cinematic、hybrid、documentary-montage 为 Wave 2，talking-head/avatar-spokesperson 则依赖 TalkingHead parity 暂缓。

---

结语：三层心智模型

把本文内容压缩成可复用的心智模型，HyperFrames 动画创作就是三件事的迭代：

1. 选——先走默认路径：从 rules-index.md 挑 2–4 条标签匹配的原子规则，或按路由表在 blueprints-index.md、transitions/overview.md、techniques.md 与 adapters 中找到对应层级；
2. 写——一条 paused GSAP timeline 同步注册到 window.__timelines，遵守 core 的确定性契约与本技能的预计算/transform-alias 红线，场景内容沿 VO 节奏排布而非 t=0 倾倒；
3. 验——用 animation-map.mjs 审计编舞（dead zones/stagger 一致性），再用 npx hyperframes lint/validate 完成静态与运行时双重把关后再 render。

技能文档把"原子配方 → 场景模板 → 转场语言 → 宏观技法 → 运行时适配器"五层收进单一入口，配合 hyperframes-core 的确定性契约，构成了 OpenMontage 中 HTML-first + GSAP-native 渲染路径的完整动画知识栈。