hyperframes-keyframes 是 HyperFrames 智能体中的关键帧动效技能，用来为合成画面添加视觉运动。该技能把关键帧定义为一种“姿态契约”：明确的可见状态、连续的主体身份、可跳转（seek-safe）的运行时，以及经过验证的像素结果。
用途与边界 该技能只负责视觉运动，不负责剪辑组装。源范围硬切、裁剪、拼接和重排由 /hyperframes-core 负责；交叉淡化需要使用不同轨道上重叠的片段配合视觉不透明度关键帧，声音淡化使用 /hyperframes-audio。宽泛场景配方参考 hyperframes-animation，完整命令文档参考 hyperframes-cli。
主要能力
- 推镜头/拉镜头：在片段内的非定时视觉或裁剪包装层上，对 scale 配合 x/y 或百分比位移打关键帧，用 set/短补间实现硬推，用补间实现平滑移动。
- 平滑多状态缩放或重新取景：让单一主体包装层保持存活，把多个缩放/取景状态写成带分段缓动的姿态阶梯。
- 平移、重新取景或 Ken Burns：动画包装层的位移与缩放；几何由作者指定，不是人脸追踪或自动语义重构图。
- 链式摄像机运动：在一条注册过的可跳转时间线上串联带标签的变换节拍。
- 匹配剪辑或甩镜转场：视觉交接由 /hyperframes-animation 负责，本技能保留作者指定的几何、方向与速度；没有自动匹配帧发现。
- 裁剪与遮罩重构图：在内层视觉包装层上插值 clip-path 或遮罩，在不改变源时间的情况下裁剪或重构图；多边形关键帧可形成多边形/遮罩过渡。
- 方向擦除或光圈/揭示切换：在重叠的视觉片段上动画化遮罩/裁剪边界。
- 分屏交接：保留两个视觉片段的位置，再对它们的内层裁剪/遮罩包装层和分隔线几何打关键帧。
使用方式 流程为：先识别动画主体、可见状态、最终状态与运行时长；选择能证明提示的最小机制；在声明的运行时中编写 seek-safe 关键帧，构建完成后再注册运行时实例；用 hyperframes check（含 lint）、hyperframes keyframes、一次聚焦的 --shot 以及关键时刻的 snapshot 进行验证；若验证失败，先修复源关键帧再重跑最小失败诊断。
运行时规则
- GSAP：在页面加载或 document.fonts.ready 内构建，构建完成后再注册；使用 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：有限时长、fill: "both"、确定性构建，并用 --shot 与 snapshot 验证。 渲染关键运动禁止使用 Date.now()、performance.now()、无种子 Math.random()、悬停/滚动触发、定时器、异步构建完成前注册的时间线、未注册的 requestAnimationFrame 或无限循环。
通道选择 优先使用合成器/视觉通道：x/y/z、xPercent/yPercent、scale、rotationX/Y/Z、skew、transformOrigin、svgOrigin、opacity、autoAlpha、clip-path、遮罩、CSS 变量、SVG path/dash 值、摄像机变换、着色器 uniform。避免布局/生命周期通道：top/left/right/bottom、width/height、margin/padding、display、visibility、延迟 DOM 创建、用辅助覆盖层模拟主体运动。可见性变化用 autoAlpha 或显式边界处零时长的 tl.set()，只作用于非片段元素或片段内包装层，绝不作用于 .clip 本身。
机制选择 同一主体换盒或换层级用共享元素/FLIP；主体沿可见路径行进用路径旅行；描边生长用 stroke draw；形状变形用形状插值；有可见揭示边界用裁剪、遮罩或着色器 uniform；多元素有序运动用交错/索引延迟；文字本身运动用行、词、字符或带状细分；表面弯曲拉伸用父子反向变换；UI 有状态用显式状态机；场景有深度用 DOM 3D、Three.js 或 WebGL 摄像机/物体关键帧。机制可组合，但每个都须澄清意图，装饰不算证明。
时序与细节 仅在澄清因果或方向时使用预备动作；离开静止时加速；峰值证明要清晰展示机制；跟随动作强化能量与方向；仅当主体应有弹性或触感时过冲。匀速路径通常用 ease: "none"；离散 UI 状态通常用锐利 ease-out；重复元素需有序偏移而非相同时间；最终定格需比过渡姿态更长的保持。平滑意味着同一主体速度连续，不要重叠写入同一变换属性的补间。文字需保留行框、词距、可读性与最终适配，快照可读帧。SVG 描边优先 DrawSVGPlugin，其次 stroke-dasharray/stroke-dashoffset；变形优先 MorphSVGPlugin。3D 需透视、preserve-3d、z 位移、旋转、遮挡与图层顺序，并用一两个诊断角度证明深度。Canvas/WebGL 需通过确定性状态关键帧化摄像机、物体变换、材质不透明度、着色器 uniform 与后处理强度，并用 --ghost 验证。
CLI 验证 可运行 npx hyperframes check、npx hyperframes keyframes .、--json、--runtime all、--selector 配合 --shot/--samples/--layout strip/--from/--to、--ghost --angle，以及 npx hyperframes snapshot . --at <times>。用 keyframes 检查目标与显式停靠点，--shot 检查幽灵、路径形状与时间间距，--layout strip 检查原地运动与重叠，--ghost 检查 canvas/WebGL 运动，snapshot 检查遮罩、文字可读性与最终定格。若选择器验证有误，先重跑 --json 找到实际动画目标，再对其拍摄并快照全帧，以绘制像素为准。
适用场景与限制 适合需要推拉、缩放、重新取景、摄像机运动、遮罩切换和分屏交接的 HyperFrames 合成画面。该技能不负责时间线剪辑与源范围裁剪，不支持任意源中段冻结（需预处理为静帧片段再拼接），不提供自动匹配帧发现或人脸追踪。收费、价格、平台支持等信息暂未提供。