CSS 关键帧动画接入 HyperFrames：css 运行时适配器模式与确定性 Seek 实战指南（OpenMontage）

CSS @keyframes 动画轻量、零 JS 依赖，非常适合装饰性循环动效，但它默认按播放时钟推进，与 HyperFrames"每一帧都是一次全新 Seek"的确定性渲染模型天然冲突。本文以 OpenMontage 仓库中 .agents/skills/hyperframes-animation/adapters/css-animations.md 为骨架，完整讲解 css 运行时适配器的工作契约、基础模式与错峰（Stagger）模式、适用场景与红线清单，并结合 hyperframes-core 的 data-* 时序契约与确定性规则，让你能写出在预览与最终渲染中均可被精确 Seek 的 CSS-only 动效。读完你将掌握：如何用有限迭代 + 负延迟回退让 CSS 动画与剪辑时间对齐，何时应改用 GSAP，以及如何用 npx hyperframes lint / validate 验证作品。

为什么 CSS 动画需要"适配器"：从时间值到像素的确定性渲染

HyperFrames 的核心理念是用 HTML 作为视频的"底稿"——一个 Composition 就是一个 HTML 文件，DOM 通过 data-* 属性声明时序，动画运行时可以被任意 Seek，媒体播放由框架接管（见 hyperframes-core/SKILL.md）。渲染器的工作方式是：拿到一个时间值，直接产出对应像素缓冲，不存在"播放"概念，每一帧都是一次从时间值出发的全新采样。

这条模型写死在 determinism-rules.md 中：Date.now()、performance.now()、渲染期网络请求、悬停/滚动/焦点状态、repeat: -1 这类无限循环全部被禁止——凡是"必须经由前一帧才能到达当前状态"的机制（定时器、累积状态、事件驱动动画）都会在乱序或并行采样时失步。

纯 CSS 关键帧动画的问题正在于此：它的时间默认由浏览器的动画时钟驱动。因此 HyperFrames 提供了 css 运行时适配器：由框架发现 DOM 中 animation-name 已被解析（computed）的元素，优先 Seek 浏览器暴露的 Animation 句柄；在不支持 WAAPI 托管 CSS 动画的环境中，则回退到先暂停、再用负值 animation-delay 模拟时间进度。从当前技能树的源码契约描述看（见下文 "适配器在技能树中的位置"），这一双重策略正是 css 适配器区别于 GSAP / WAAPI 适配器的核心实现点。

一句判断准则：场景编舞交给 GSAP，单元素固定时长的运动才交给 CSS。 当动效属于某一个元素、时长固定时，CSS 是零运行时成本的选择；当多个元素需要交错、嵌套、跨场景编排时，hyperframes-animation 的默认建议是使用单条暂停 GSAP 时间线（见 hyperframes-animation/SKILL.md 的运行时挑选表）。

五条确定性契约：CSS 元素在 HyperFrames 中的存活条件

css-animations.md 以契约（Contract）开篇，这五条是任何 CSS 动画元素进入 Composition 前必须满足的前提，结合 data-attributes.md 可逐条展开：

1. 动画元素必须在运行时初始化完成前进入 DOM。 适配器在初始化阶段完成元素发现与 Animation 句柄接管。这也呼应核心契约里"禁止对后续场景的 clip 调用 gsap.set"的约束——后景元素在页面加载时根本不在 DOM 中（详见 determinism-rules.md）。

2. 给受时元素一个 data-start，让"本地动画时间"与剪辑对齐。 data-start 的单位是秒，也支持受支持的剪辑时间引用（见 data-attributes.md）。CSS 动画的本地时间起点与剪辑在时间线上的起点并不天然一致，必须通过 data-start 把二者绑定。

3. 使用有限的 animation-duration 与 animation-iteration-count。 这是硬性要求而非风格建议：在缺乏 WAAPI 托管 CSS 动画的环境中，负延迟回退机制无法表达无界时长——无限循环意味着无法把一个具体时间点映射到动画内的进度。因此要么直接给有限迭代次数，要么遵循确定性规则给出可计算出的有限次数。

4. 优先使用 animation-fill-mode: both。 这样 Seek 到动画起点之前或终点之后时，元素分别保持起始帧与结束帧状态，不会因处于动画区间之外而"裸奔"到默认样式。这也与 HyperFrames 的可见窗口语义吻合：clip 的可见窗口两端都含端点（start ≤ t ≤ start + duration），末帧仍需呈现动画的解析终态。

5. 禁止墙钟 JS、悬停触发状态、依赖用户事件的 class 切换。 渲染器没有输入事件，hover、focus、scroll 状态在渲染环境中不存在；依赖它们的动效在预览中可能正常、在渲染中却不会触发。

在 DOM 结构层，CSS 动画元素同时受通用 clip 契约约束：可见的受时元素必须带 class="clip"（否则运行时忽略 data-start/data-duration，让元素整段可见），且必须是 Composition 根元素的直接子元素。老项目中可能见到的 data-layer、data-end 属于已废弃命名，应分别改用 data-track-index 与 data-duration（属性全表见 data-attributes.md）。

基础模式：单个元素的脉冲光环

当一段运动只属于一个元素且有固定时长时，CSS 是最直接的表达。原文的脉冲光环示例完整如下——它在第 2 轨上、从 0s 开始持续 4s：

<div
  id="pulse-ring"
  class="clip pulse-ring"
  data-start="0"
  data-duration="4"
  data-track-index="2"
></div>

<style>
  .pulse-ring {
    width: 280px;
    height: 280px;
    border: 4px solid rgba(255, 255, 255, 0.7);
    border-radius: 50%;
    animation-name: pulse-ring;
    animation-duration: 1200ms;
    animation-timing-function: cubic-bezier(0.2, 0, 0, 1);
    animation-iteration-count: 3;
    animation-fill-mode: both;
  }

  @keyframes pulse-ring {
    from {
      opacity: 0;
      transform: scale(0.82);
    }
    35% {
      opacity: 1;
    }
    to {
      opacity: 0;
      transform: scale(1.18);
    }
  }
</style>

逐个解读它为何符合契约：

• animation-iteration-count: 3：1200ms × 3 = 3.6s，落在 data-duration="4" 之内，剩余 0.4s 由 fill-mode: both 保持在 to 终态（透明、放大到 1.18），动画既不越界也不需要在可见窗口内无限跑。
• animation-duration: 1200ms 固定：负延迟回退可以精确计算：Seek 到本地时刻 t 时，暂停并以 animation-delay: -t 重放，即可让动画呈现"仿佛已经跑了 t 毫秒"的中间帧。时长固定是有界的前提。
• data-track-index="2"：声明时间线轨道，同轨 clip 不允许重叠（轨道语义见 data-attributes.md 与 tracks-and-clips 参考）。
• 只动 opacity 与 transform: scale()：正好落在确定性规则允许的属性清单内（opacity、x、y、scale、rotation、颜色类与 transform 别名），而非会触发重排的布局属性。

错峰模式：用 CSS 自定义属性替代重复 keyframes

当多个同类元素需要依次弹入时，不必复制多份 keyframes，也不需要引入 JS 编排——用 CSS 自定义属性（custom properties）做 --i 索引，配合 animation-delay: calc(var(--i) * 120ms) 即可。原文的点阵弹入示例：

<div class="clip dots" data-start="1" data-duration="3" data-track-index="3">
  <span style="--i: 0"></span>
  <span style="--i: 1"></span>
  <span style="--i: 2"></span>
</div>

<style>
  .dots span {
    display: inline-block;
    width: 18px;
    height: 18px;
    margin-right: 10px;
    border-radius: 50%;
    background: currentColor;
    animation: dot-pop 900ms ease-out both;
    animation-delay: calc(var(--i) * 120ms);
  }

  @keyframes dot-pop {
    from {
      opacity: 0;
      transform: translateY(18px) scale(0.75);
    }
    to {
      opacity: 1;
      transform: translateY(0) scale(1);
    }
  }
</style>

要点分析：

• 该 clip 从 1s 开始、持续 3s，三个点的 animation-delay 分别为 0、120ms、240ms，加上 900ms 本体时长，整个弹入序列在可见窗口内可完整收敛。
• 关键帧只写一份，N 个元素仅靠行内 --i 区分，这与 GSAP 的 stagger 达到的效果类似，但完全不需要 JS 时间线——在"运动属于同一元素族、时长固定"的语境下是更省的模式。需要更复杂的交错（不等间距、非线性的索引）时，再转向 GSAP 的 stagger（见 adapters/gsap-easing-and-stagger.md）。

适用场景（Good Uses）与红线清单（Avoid）

推荐使用 CSS 适配器的场景（原文 + 技能路由语义）：

• 已知重复次数的装饰性循环——脉冲、呼吸、旋转装饰；
• 遮罩（mask）、辉光（glow）、微光（shimmer）、颗粒（grain）、细微视差层等背景性动效，它们不该占用一条 JS 时间线；
• 简单的单元素入场——为一个图标、一块文字配一个收敛的进入动作，为它单独搭一条完整 GSAP 时间线反而过度设计。

必须回避的行为：

1. 无限 CSS 动画：除非已确认浏览器会为 CSS 动画暴露可 Seek 的 WAAPI Animation 句柄（此时适配器走第一条路径），否则不要用 infinite。优先用覆盖可见时长的有限迭代次数。这与确定性规则中"用 repeat: Math.max(0, Math.floor(duration / cycleDuration) - 1) 计算有限次数（取 floor 不取 ceil，ceil 会越出 data-duration）"是一套互补的表达。
2. 用 top / left / width / height 这类布局属性做动画：能表达成 transform 与 opacity 的就别触发重排；布局变化请交给 CSS 静态布局 + transform。
3. 依赖 hover、focus、scroll 或媒体查询触发渲染关键动效：渲染器没有指针与视口交互。
4. 在启动之后切换动画 class：除非该 class 切换由另一条确定性时间线控制，否则状态会脱离时间轴而无法被 Seek。

把第 3、4 条与确定性规则放一起看会更清楚：任何由"用户事件"或"运行期副作用"驱动的视觉状态都不满足"同一输入时间 → 同一像素"，这正是 css 适配器要解决的适配问题的反面。

混合形态参考：纯 CSS 静态标记 + GSAP 时间线驱动

仓库里另一个典型用法可以视为 CSS 适配器的"近邻对照"：.agents/skills/hyperframes-animation/rules/css-marker-patterns.md 提供的是纯 CSS + GSAP 的高亮笔划、圆环、爆散线、波浪划线、划掉线等 MarkerHighlight 绘制模式——它们用 CSS 构建静态形态，但用单条 GSAP 时间线做 scaleX / strokeDashoffset 的确定性驱动。与本文的"纯 CSS 动画 + css 适配器"路线不同：前者把运动控制权交给 GSAP 时间线，后者把运动声明留在 @keyframes 里由适配器 Seek。场景编舞复杂、需要与其它 clip 对齐时就向 GSAP 一侧靠拢；单元素固定时长、纯装饰就向 CSS 一侧靠拢。

验证：改完 CSS 动画组合后做什么

css-animations.md 给出的验证流程是编辑完 CSS 动画组合后运行：

npx hyperframes lint
npx hyperframes validate

配合核心技能的全量校验清单（见 hyperframes-core/SKILL.md 与 hyperframes-cli 的 lint-validate-inspect 参考），完整流程还包括：

• npx hyperframes inspect（0 错误，检查溢出等布局问题）；
• 含子合成（sub-composition）的项目：npx hyperframes snapshot --at <midpoints> 并目检各帧；
• npx hyperframes preview 供人工审阅；
• 仅在用户批准后执行 npx hyperframes render。

需要注意的盲区：lint / validate / inspect 抓不到所有问题——例如根元素必须被显式尺寸化（否则 flex / 100% 子元素塌缩为 0、内容堆到左上角）、display/visibility 禁止动画、后景元素 gsap.set 禁令等静默故障（determinism-rules.md 与 data-attributes.md 中有完整清单）。CSS 元素的 Seek 行为建议通过 snapshot 抽帧目检确认 fill-mode 与负延迟回退在关键帧上呈现正确。

适配器在技能树中的位置：七个运行时之一

在本仓库中，本文对应的文档位于 .agents/skills/hyperframes-animation/adapters/ 目录，与 gsap.md、lottie.md、three.md、animejs.md、waapi.md、typegpu.md 并列——hyperframes-animation 技能明确列出 GSAP（默认，覆盖约 95% 动效工作）、Lottie、Three.js、Anime.js、CSS、WAAPI、TypeGPU 七个运行时适配器，并允许在同一 Composition 内多运行时共存：每个运行时把自身实例注册到专属全局对象上，HyperFrames 即可在一次 Seek 中统一驱动（见 hyperframes-animation/SKILL.md）。

从能力路由上，"CSS 关键帧（animation-delay / play-state / fill-mode）"正是 css-animations.md 这条适配器的查询入口；而跨场景的 CSS 驱动转场（transition）由 .agents/skills/hyperframes-animation/transitions/ 下的 CSS 系列（css-push、css-dissolve、css-cover 等）承接。CSS 动效的兄弟适配器 WAAPI 模式见 adapters/waapi.md——它在 element.animate() 创建动画后用 currentTime 直接 Seek，是"想要浏览器原生关键帧 + JS 创建时序、又不想引入 GSAP 依赖"时的替代选择。

在 OpenMontage 更大的图景里，HyperFrames 作者技能以 .agents/skills/hyperframes* 系列的形式内嵌在仓库中，并由 hyperframes 作为"先读此技能"的入口路由器分发到 hyperframes-core（结构契约）、hyperframes-animation（动效）、hyperframes-cli（开发回路）等域（见 .agents/skills/hyperframes/SKILL.md）。仓库同时提供运行时集成侧的代码与测试，如 tools/video/hyperframes_compose.py 与 tests/qa/test_09_hyperframes_compose.py、tests/tools/test_hyperframes_compose.py，可用于把 HTML 合成接入实际视频生产流水线时验证。

说明：原文 Credits 中提到的适配器实现文件 packages/core/src/runtime/adapters/css.ts 属于 HyperFrames 上游包，当前 OpenMontage 仓库不包含该路径；上文关于适配器"发现动画名 → Seek Animation 句柄 → 负延迟回退"的实现描述，均忠实转述自本仓库 css-animations.md 的契约说明，未在本仓库内另行考证。

小结

把一段 CSS 关键帧动画放进 HyperFrames 合成，本质是把它从"浏览器时钟驱动"改造成"可由任意时间值采样"的确定性状态：动画元素在初始化前就位、以 data-start 对齐剪辑时间、用有限时长与迭代次数保证有界、用 animation-fill-mode: both 兜住 Seek 区间之外的状态、杜绝墙钟与事件依赖。做到这五点，@keyframes 就能作为零 JS 成本的装饰层，与 GSAP 场景编舞共存于同一条确定性时间轴上；做完后用 lint + validate + snapshot 收尾，即可放心进入预览与渲染。