HyperFrames 关键帧
关键帧是一种姿态契约：可见状态、连续的主体身份、可安全 seek 的运行时、经过验证的像素。
使用 hyperframes-animation 处理广泛的场景配方。使用 hyperframes-cli 获取完整命令文档。仅在选择实现机制而非视觉风格时使用 references/keyframe-patterns.md。
创作者编辑边界
关键帧负责视觉运动，不负责剪辑组装。源区间的硬切、修剪、 拼接和重新排序属于 /hyperframes-core：为每个保留区间创作一个媒体元素， 使用 data-start 和 data-duration 放置它，并使用 data-media-start 选择其源 偏移。相邻区间形成硬切。交叉淡入淡出 使用不同轨道上的重叠剪辑以及视觉不透明度关键帧；声音 淡入淡出使用 /hyperframes-audio。
| 创作者请求 | 真实机制 | | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 推入 / 推出 | 在剪辑内部的非时间驱动视觉/裁剪包装元素上，对 scale 进行关键帧处理，并带有 x/y 或百分比平移。硬推入使用 set/短补间，平滑移动使用补间。 | | 平滑的多状态缩放或重新取景 | 保持一个主体包装元素存活，并将多个缩放/重新取景状态创作成带有每段缓动的姿态阶梯。 | | 平移、重新取景或 Ken Burns 运镜 | 对包装元素的平移加上缩放进行动画。几何形状由创作者指定；这不是人脸追踪或自动语义重新取景。 | | 链式运镜 | 在一个已注册的可安全 seek 时间轴上串联带标签的变换节拍。 | | 匹配剪辑或甩镜 | /hyperframes-animation 负责视觉交接；/hyperframes-registry 提供原语；关键帧保留创作者指定的几何形状、方向和速度。没有自动的匹配帧发现。 | | 裁剪和遮罩重新取景 | 在内部视觉包装元素上对 clip-path 或遮罩进行插值，以便在不改变源时间的情况下裁剪/重新取景。多边形关键帧可以形成多边形/遮罩过渡。 | | 方向擦除剪辑或光圈/揭示剪辑 | 在重叠的视觉剪辑上对遮罩/裁剪边界进行动画；/hyperframes-animation 负责交接编排。 | | 分屏交接 | 让两个视觉剪辑都由 core 放置，然后对其内部裁剪/遮罩包装元素和分隔线几何形状进行关键帧处理。 | | 恒定源变速 | /hyperframes-core 负责归一化的 data-playback-rate（0.1..5），以获得渲染安全的画面和保持音高的声音。它在整个媒体元素上保持恒定。 | | 源速度斜坡 | 不支持：不存在随时间变化的播放速率包络。预处理派生媒体资源，然后通过 core 放置它。 | | 冻结 / 保持 | 视觉姿态、最终源帧或已完成的子合成可以保持。不支持任意源中间冻结；预处理静帧/派生片段，将其作为自己的剪辑放置，然后使用另一个源区间继续。 |
当同时编辑画面和声音时，加载 /hyperframes-core、本技能用于 视觉运动，以及 /hyperframes-audio 用于已放置轨道上的淡入淡出、交叉淡入淡出、音量自动化、 闪避/让位或效果。
视觉过渡或裁剪处理不是时间上的源修剪或 拼接。/hyperframes-core 负责时间轴、剪辑时间和源区间； 关键帧只在这些剪辑内部的包装元素上动画可见的交接或裁剪。 对于可复制的画面/声音组合配方，使用 /hyperframes-core → references/creator-editing-recipes.md。
流程
- 识别被动画化的主体、可见状态、最终状态和运行时。
- 选择能够证明提示的最小机制。仅在机制不清楚时阅读
references/keyframe-patterns.md。 - 在声明的运行时中创作可安全 seek 的关键帧。同步构建并注册运行时实例。
- 使用
hyperframes lint、hyperframes check、hyperframes keyframes、一个聚焦的--shot，以及在证明时间点进行快照来验证。 - 如果证明失败，修复源关键帧，并在渲染前重新运行最小失败诊断。
契约
- 命名移动主体。
- 命名证明预期运动所需的姿态，包括最终状态。
- 对可见通道进行关键帧处理，而不是隐藏的辅助状态。
- 当连续性重要时，保留对象身份。
- 仅当预期运动是替换或溶解时才使用交叉淡入淡出。
- 让可读或语义状态保持足够长时间以便看见。
- 最终帧是动画的一部分，而不是清理。
- 除非被要求，否则不要重置到静止状态。
- 除非被要求，否则不要以黑场结束。
- 如果编辑起始场景，除非被要求重新设计，否则保留布局、文案、资产、颜色和最终状态。
运行时规则
GSAP:
- 在页面加载时同步构建
- 使用
gsap.timeline({ paused: true }) - 注册为
window.__timelines[compositionId] - 注册表键必须匹配
data-composition-id - 对于渲染关键运动，不要调用
tl.play() - 保持重复次数有限
CSS keyframes:
- 有限的持续时间和迭代次数
- 确定性延迟
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() - hover/scroll 触发器
- 定时器
- 异步创建的时间轴
- 未注册的
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() 补间，使用 immediateRender: false。
关键帧形式
- 数组关键帧：带有每步 duration/ease 的姿态阶梯。
- 百分比关键帧：单个补间内的精确时序。
- 属性数组：紧凑的多停靠点变化。
- 当每个停靠点都带有自己的缓动时，在父级上使用
ease: "none"。 - 当每个分段都应共享相同感觉时使用
easeEach。
不要从示例中复制数值距离或时序。根据实际合成几何形状和持续时间推导它们。
对于在两个盒子之间移动的一个主体，优先使用一个连续变换补间或 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 创建、执行主体运动的辅助叠加层。
对于可见性变化，在已注册的可 seek GSAP 时间轴上使用 autoAlpha，或在显式边界上使用零持续时间的 tl.set()。只针对非剪辑元素或剪辑内部的包装元素；切勿针对 .clip 本身。切勿按持续时间补间原始 visibility，也切勿补间 display。
机制选择
选择能够证明提示的最小机制：
| 需求 | 机制 | | ------------------------------------- | -------------------------------------------------- | | 同一主体改变盒子或层级 | 共享元素 / FLIP | | 主体沿可见路径行进 | 路径运动 | | 笔画增长或描摹 | 描边绘制 | | 形状变成另一个形状 | 形状插值 | | 揭示边界可见 | 裁剪、遮罩或着色器 uniform | | 许多项目按顺序移动 | 交错 / 索引延迟 | | 文本本身移动 | 行、词、字符或条带细分 | | 表面弯曲、拉伸或裁剪 | 父/子反向变换 | | UI 有状态 | 显式状态机 | | 场景有深度 | DOM 3D、Three.js 或 WebGL 相机/对象关键帧 |
机制可以组合，但每个机制都必须阐明想法。装饰不是证明。
时序
- 仅当它阐明原因或方向时才使用预备动作。
- 加速离开静止状态。
- 峰值证明要清楚展示机制。
- 跟随动作表现能量和方向。
- 仅当主体应感觉有弹性或可触时，才使用过冲。
- 恒定速度路径运动通常需要
ease: "none"。 - 离散 UI 状态通常需要锐利的 ease-out。
- 重复元素需要有序偏移，而不是完全相同的时序。
- 最终锁定需要比过渡姿态更长的保持时间。
- 平滑意味着同一主体上的连续速度。
- 除非重叠是有意且已验证，否则不要重叠写入同一变换属性的补间。
- 当同一主视觉表面也在缩放或移动时，避免动画大幅
clip-path/遮罩变化；在主运动稳定后使用嵌套揭示。
文本
保留行框、词距、可读性和最终适配。如果文本内部移动，移动字形或遮罩条带，而不仅仅是文本周围的装饰。对可读帧进行快照。
SVG
对于笔画增长，优先使用 DrawSVGPlugin，然后是 stroke-dasharray/stroke-dashoffset。对于形状插值，优先使用 MorphSVGPlugin；必要时将基本形状转换为路径，并将复杂轮廓拆分为更简单的部分。
3D
仅缩放是伪深度。在稳定父级上使用 perspective、transform-style: preserve-3d、z 运动、旋转、相机/世界运动、遮挡，以及当对象交叉时的图层顺序。
使用一到两个能够暴露深度关系的诊断角度。如果角度证明没有显示深度交叉，改进 z/相机/遮挡。
Canvas / WebGL
通过确定性状态对相机位置、相机目标、对象变换、材质不透明度、着色器 uniform 和后处理强度进行关键帧处理。从 HyperFrames 时间渲染。使用 --ghost，因为标记框无法看到内部 canvas 运动。
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 表示存在显式停靠点。motionPath 表示存在路径。trace 表示多笔画绘制。composed with 表示子运动继承父运动。
均匀的鬼影间隔表示恒定速度。聚集的鬼影表示缓入或稳定。大间隔表示快速运动。
辅助选择器拍摄不是证明。破损完整帧上的洋葱拍摄不是证明。
错误处理
| 失败 | 修复 | | ------------------ | ---------------------------------------------------------------------------------- | | 仅端点 | 添加中间姿态，保持峰值证明，重新运行 --shot | | 身份断裂 | 保持一个元素存活，使用共享源/最终盒子，移除替代交叉淡入淡出 | | 伪 3D | 添加 z/相机运动、遮挡、角度证明 | | 最终错误 | 添加最终保持，对最终减去保持时间和精确最终进行快照 | | 不可 seek 的运行时 | 暂停自动播放，注册实例，移除定时器，同步构建 | | 文本不可读 | 保留行框，减少位移，添加最终保持，对文本帧进行快照 |
完成
运行 hyperframes lint、hyperframes check、hyperframes keyframes、一个聚焦的 --shot，以及快照。确认第一帧、证明姿态、最终减去保持时间、精确最终、主体拥有的运动，并且没有调试叠加层。