HyperFrames 关键帧（Keyframes）
关键帧是一种姿势合约：可见状态、连续主体身份、可寻址运行时、验证后的像素。
使用 hyperframes-animation 处理广泛的场景配方。使用 hyperframes-cli 获取完整的命令文档。仅在需要选择实现机制而非视觉风格时，才使用 references/keyframe-patterns.md。
创作者编辑边界
关键帧拥有视觉运动，而非剪辑装配。源范围硬切、修剪、拼接和重新排序属于 /hyperframes-core：为每个保留范围创作一个媒体元素，用 data-start 和 data-duration 放置它，并用 data-media-start 选择其源偏移量。相邻范围构成硬切。交叉淡入淡出使用不同轨道上的重叠剪辑加上视觉透明度关键帧；声音淡入淡出使用 /hyperframes-audio。
| 创作者请求 | 真实机制 |
|---|---|
| 推近 / 拉远 | 在剪辑内部的非计时视觉/裁剪包装器上，使用 scale 配合 x/y 或百分比平移的关键帧。使用 set/短 tween 实现硬推近，使用 tween 实现平滑移动。 |
| 平滑多状态缩放或重新取景 | 保持一个主体包装器存活，并将多个缩放/重新取景状态编写为带有每段缓动的姿势阶梯。 |
| 平移、重新取景或肯·伯恩斯相机移动 | 动画化包装器平移加缩放。几何体是创作的；这不是面部追踪或自动语义重新取景。 |
| 连锁相机移动 | 在一个已注册的可寻址时间线上，链条化带有标签的变换节拍。 |
| 匹配剪辑或扫视平移 | /hyperframes-animation 拥有视觉交接所有权；/hyperframes-registry 提供原语；关键帧保留已创作的几何体、方向和速度。没有自动的匹配帧发现。 |
| 裁剪和遮罩重新取景 | 在内部视觉包装器上插值 clip-path 或遮罩，以进行裁剪/重新取景而不更改源时间。多边形关键帧可以形成多边形/遮罩过渡。 |
| 定向擦除剪辑或光圈/揭示剪辑 | 在重叠的视觉剪辑上动画化遮罩/剪辑边界；/hyperframes-animation 拥有交接编排的所有权。 |
| 分屏交接 | 保持两个视觉剪辑由核心放置，然后对它们内部的裁剪/遮罩包装器和分隔几何体添加关键帧。 |
| 恒速源重定时 | /hyperframes-core 拥有标准化的 data-playback-rate（0.1..5），用于渲染安全的图像和音高保持的声音。对于整个媒体元素来说是恒定的。 |
| 源速度斜坡 | 不支持：没有时变播放速率包络。预处理一个派生的媒体资产，然后通过核心放置。 |
| 冻结 / 保持 | 视觉姿势、最终源帧或完成的子合成可以保持。不支持任意的中间源冻结；预处理一个静态/派生的片段，将其作为自己的剪辑放置，然后使用另一个源范围继续。 |
同时编辑图像和声音时，加载 /hyperframes-core、此技能用于视觉运动，以及 /hyperframes-audio 用于淡入淡出、交叉淡入淡出、音量自动化、闪避/雕刻或对已放置轨道的效果。
视觉过渡或裁剪处理不是临时源修剪或拼接。/hyperframes-core 拥有时间线、剪辑时序和源范围；关键帧仅在这些剪辑内部的包装器上动画化可见的交接或裁剪。对于可复制的组合图像/声音配方，使用 /hyperframes-core → references/creator-editing-recipes.md。
步骤
- 识别动画主体、可见状态、最终状态和运行时长。
- 选择能证明提示的最小机制。仅在机制不明确时阅读
references/keyframe-patterns.md。 - 在声明的运行时长内编写可寻址关键帧。同步构建并注册运行时实例。
- 使用
hyperframes lint、hyperframes check、hyperframes keyframes、一个聚焦的--shot以及在证明时刻的屏幕快照进行验证。 - 如果证明失败，修复源关键帧并重新运行最小的失败诊断，然后再进行渲染。
合约
- 命名移动主体。
- 命名证明预期运动所需的姿势，包括最终状态。
- 对可见通道添加关键帧，而非隐藏的辅助状态。
- 当连续性重要时，保持对象身份。
- 仅当预期运动是替换或溶解时使用交叉淡入淡出。
- 保持可读或语义状态足够长时间以供查看。
- 最终帧是动画的一部分，不是清理。
- 除非请求，否则不要重置回静止状态。
- 除非请求，否则不要以黑色结束。
- 如果正在编辑起始场景，除非要求重新设计，否则保留布局、副本、资产、颜色和最终状态。
运行时规则
GSAP：
- 在页面加载时同步构建
- 使用
gsap.timeline({ paused: true }) - 注册为
window.__timelines[compositionId] - 注册键必须匹配
data-composition-id - 对于渲染关键的运动，不要调用
tl.play() - 保持重复次数有限
CSS 关键帧：
- 有限的持续时间和迭代次数
- 确定的延迟
animation-fill-mode: both- 当时序属于剪辑时使用
data-start
Anime.js：
- 同步创建
autoplay: false- 有限的持续时间和循环
- 将每个实例推送到
window.__hfAnime
WAAPI：
- 有限的
duration fill: "both"- 确定的构建
- 文本表面不列出 WAAPI；使用
--shot（它 seek WAAPI）和屏幕快照进行验证
对于渲染关键的运动，切勿使用：
Date.now()performance.now()- 未播种的
Math.random() - 悬停/滚动触发器
- 定时器
- 异步创建的时间线
- 未注册的
requestAnimationFrame - 无限循环
GSAP 骨架
const root = document.querySelector("[data-composition-id]");
const compositionId = root.dataset.compositionId;
const tl = gsap.timeline({ paused: true });
tl.addLabel("state-a", 0);
tl.to(".subject", {
keyframes: [
{ x: 0, opacity: 1, duration: 0.2 },
{ x: 120, opacity: 1, duration: 0.4, ease: "power2.out" },
{ x: 100, opacity: 1, duration: 0.2, ease: "power2.inOut" },
],
ease: "none",
});
window.__timelines = window.__timelines || {};
window.__timelines[compositionId] = tl;
使用标签表示语义状态。使用位置参数代替链式延迟。对于后续接触相同属性的 from()/fromTo() tween，使用 immediateRender: false。
关键帧形式
- 数组关键帧：带有每步持续时间/缓动的姿势阶梯。
- 百分比关键帧：单个 tween 内的精确时序。
- 属性数组：紧凑的多停止变化。
- 当每个停止自带缓动时，父元素使用
ease: "none"。 easeEach当每个片段应共享相同感觉时使用。
不要从示例中复制数值距离或时序。从实际合成几何体和持续时间中推导它们。
对于一个在两个方框之间移动的主体，首选一个连续的变换 tween 或 FLIP。仅当观看者应感觉到不同的节拍时，才将 x/y/scale 拆分为多个缓动关键帧；每个片段都会改变速度，并可能被理解为卡顿。
通道
优先使用合成器/视觉通道：x/y/z、xPercent/yPercent、scale、rotationX/Y/Z、skew、transformOrigin、svgOrigin、opacity、autoAlpha、clip-path、遮罩、CSS 变量、SVG 路径/虚幻值、相机变换、着色器 uniform。
避免使用布局/生命周期通道：top/left/right/bottom、width/height、margin/padding、display、visibility、延迟 DOM 创建、执行主体运动的辅助叠加层。
对于可见性变化，在已注册的可寻址 GSAP 时间线上使用 autoAlpha，或在显式边界处使用零持续时间的 tl.set()。仅针对非剪辑元素或剪辑内部的包装器；切勿针对 .clip 本身。切勿对原始的 visibility 进行持续时间 tween，也切勿对 display 进行 tween。
机制选择
选择能证明提示的最小机制：
| 需求 | 机制 |
|---|---|
| 同一主体改变方框或层级 | 共享元素 / FLIP |
| 主体沿可见路线移动 | 路径漫游 |
| 描边增长或勾勒 | 描边绘制 |
| 一个形状变成另一个形状 | 形状插值 |
| 揭示边界可见 | 剪辑、遮罩或着色器 uniform |
| 许多元素按顺序移动 | 交错 / 索引延迟 |
| 文本本身移动 | 行、词、字符或带状细分 |
| 表面弯曲、拉伸或裁剪 | 父/子反向变换 |
| UI 具有状态 | 显式状态机 |
| 场景具有深度 | DOM 3D、Three.js 或 WebGL 相机/对象关键帧 |
机制可以组合，但每个机制必须阐明想法。装饰不是证明。
时序
- 仅当能阐明原因或方向时使用预期。
- 加速度离开静止。
- 峰值证明 unmistakably 展示机制。
- 后续动作展现能量和方向。
- 仅当主体应感觉有弹性或触感时使用过冲。
- 恒速路径漫游通常需要
ease: "none"。 - 离散 UI 状态通常需要锐利的缓出。
- 重复元素需要有序偏移，而非相同时序。
- 最终锁定需要比过渡姿势更长的保持。
- 平滑意味着同一主体上的连续速度。
- 除非重叠是故意的并经过验证，否则不要重叠写入相同变换属性的 tween。
- 避免在同一个英雄表面也在缩放或移动时，动画化大的
clip-path/遮罩变化；在主移动稳定后使用嵌套揭示。
文本
保留行框、词间距、可读性和最终适配。如果文本内部移动，移动字形或遮罩带，而不仅仅是文本周围的装饰。对可读帧进行快照。
SVG
对于描边增长，优先使用 DrawSVGPlugin，然后使用 stroke-dasharray/stroke-dashoffset。对于形状插值，优先使用 MorphSVGPlugin；在需要时将基本形状转换为路径，并将复杂轮廓拆分为更简单的部分。
3D
单独的缩放是伪深度。在稳定的父元素上使用透视、transform-style: preserve-3d、Z 轴移动、旋转、相机/世界运动、遮挡以及对象交叉时的层顺序。
使用一个或两个诊断角度来暴露深度关系。如果角度证明没有显示深度交叉，改进 Z/相机/遮挡。
Canvas / WebGL
通过确定性状态对相机位置、相机目标、对象变换、材质不透明度、着色器 uniform 和后处理强度添加关键帧。从 HyperFrames 时间渲染。使用 --ghost，因为标记框无法看到内部画布运动。
CLI 证明
npx hyperframes lint
npx hyperframes check
npx hyperframes keyframes .
npx hyperframes keyframes . --json
npx hyperframes keyframes . --runtime all
npx hyperframes keyframes . --selector "<selector>" --shot "<file>" --samples <n>
npx hyperframes keyframes . --selector "<selector>" --shot "<file>" --layout strip --from <t0> --to <t1>
npx hyperframes keyframes . --shot "<file>" --ghost --angle <angle>
npx hyperframes snapshot . --at <times>
为真实的动画主体选择 <selector>。为第一帧、证明姿势、最终保持前和精确最终帧选择 <times>。仅当必须证明深度时选择 <angle>。
| 工具 | 证明内容 |
|---|---|
keyframes | 目标、显式停止、路径、轨迹、组合的父/子运动、CSS 停止、Anime 注册 |
--shot | 重影、路线形状、时间间距、DOM 3D 投影、聚焦选择器证明 |
--layout strip | 原位运动、重叠、接触、细微缩放/透明度、文本波动 |
--ghost | Canvas、WebGL、着色器运动、渲染的 3D |
snapshot --at | 遮罩、文本可读性、完整状态、最终锁定、黑色/重置尾部 |
如果选择器证明看起来错误：
- 重新运行
--json - 找到实际的动画目标
- 拍摄该目标
- 快照完整帧
- 相信绘制的像素胜过日志
诊断读取
flat 表示没有显式的中间姿势。keyframes 表示存在显式停止。`m
…
[因内容截断而截断]