hyperframes-keyframes

插件安装： 在设置或检查更新命令之前，如果此技能位于 HyperFrames 插件中，请遵循 插件执行规则。独立安装请按下方的更新说明操作。

HyperFrames 关键帧

关键帧是一份姿态契约：可见状态、主体身份连续、运行时支持安全跳转，以及经过验证的像素画面。

使用 hyperframes-animation 获取全面的场景配方。使用 hyperframes-cli 查看完整的命令文档。仅在选择实现机制而非视觉风格时，使用 references/keyframe-patterns.md。

创作者的编辑边界

关键帧负责视觉运动，不负责片段拼接。源范围的硬切、裁剪、 拼接和重排属于 /hyperframes-core：为每个保留的范围创作一个媒体元素， 使用 data-start 和 data-duration 放置，并使用 data-media-start 选择其源 偏移量。相邻范围会形成硬切。交叉淡化需要在不同轨道上重叠片段，并配合 视觉不透明度关键帧；声音淡化使用 /hyperframes-audio。

创作者需求	真实机制
Punch-in / punch-out	在片段内非定时的视觉／裁剪包装器上，为 scale 设置关键帧，并使用 x／y 或百分比位移。使用 set／短缓动实现快速推近，使用缓动实现平滑移动。
平滑的多状态缩放或重新构图	保持一个主体包装器持续有效，并将多个缩放／重新构图状态编排成姿态序列，为每个片段设置缓动。
平移、重新构图或 Ken Burns 运镜	为包装器的位移和缩放设置动画。几何参数由作者设定；这不是人脸跟踪或自动语义重新构图。
连续运镜	在一个已注册且支持安全定位的时间轴上，串联带标签的变换节拍。
匹配剪辑或甩镜转场	/hyperframes-animation 负责视觉衔接；/hyperframes-registry 提供基本构件；关键帧保留设定的几何参数、方向和速度。不会自动查找匹配帧。
裁剪和蒙版重新构图	对内部视觉包装器的 clip-path 或蒙版进行插值，以裁剪／重新构图而不改变源时间。多边形关键帧可形成多边形／蒙版转场。
定向擦除剪辑或光圈／揭示剪辑	在重叠的视觉片段上对蒙版／裁剪边界设置动画；/hyperframes-animation 负责衔接编排。
分屏衔接	保持两个视觉片段由核心放置，然后为其内部裁剪／蒙版包装器和分隔线几何参数设置关键帧。
恒定源速度重映射	/hyperframes-core 负责归一化的 data-playback-rate（0.1..10），以实现渲染安全的画面和保留音高的声音。整个媒体元素的速率保持恒定。
源速度渐变	在 <video>／<audio> 上的 data-automation 中设置 rate 通道（t 为片段秒数，v 为 0.1..10，对数插值）；其优先级高于恒定速率。
冻结／定格	可定格视觉姿态、源的最后一帧或已完成的子合成。不支持源中任意位置的冻结；请预处理静帧／派生片段，将其作为独立片段放置，然后从另一个源范围继续播放。

同时编辑画面和声音时，加载 /hyperframes-core、用于视觉动态的此技能，以及用于已放置轨道上的淡入淡出、交叉淡化、音量自动化、ducking／挖空或效果的 /hyperframes-audio。 视觉转场或裁剪处理并不等同于时间上的源素材修剪或剪接。/hyperframes-core 负责时间线、片段时长和源素材范围；关键帧只负责在这些片段内的包装元素上，为可见的衔接或裁剪添加动画。 如需可复制的画面与声音组合方案，请使用 /hyperframes-core → references/creator-editing-recipes.md。

流程

1. 确定动画主体、可见状态、最终状态和运行时长。
2. 选择能证明提示要求的最简单机制。只有机制不明确时，才阅读 references/keyframe-patterns.md。
3. 在声明的运行时长内编写可安全跳转的关键帧。构建完成后才注册运行时实例；在 document.fonts.ready 内构建也可以。
4. 使用 hyperframes check（会运行 lint）、hyperframes keyframes、一次针对性的 --shot 和证明时间点的快照进行验证。
5. 如果验证失败，修正源关键帧，并在渲染前重新运行最小范围的失败诊断。

约定

• 指明运动主体。
• 指明能证明预期运动所需的姿势，包括最终状态。
• 为可见通道设置关键帧，而不是为隐藏的辅助状态设置关键帧。
• 连贯性重要时，保持对象标识不变。
• 只有在预期运动是替换或溶解时才使用交叉淡化。
• 让可读状态或语义状态保持足够长时间，以便看清。
• 最后一帧是动画的一部分，不是收尾处理。
• 除非用户要求，否则不要重置到静止状态。
• 除非用户要求，否则不要以黑屏结束。
• 如果是在编辑起始场景，除非用户要求重新设计，否则应保留布局、文案、素材、颜色和最终状态。

运行时规则

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：

• duration 必须有限
• fill: "both"
• 构建过程必须确定
• 文本界面不会列出 WAAPI；请使用 --shot（它会跳转 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() 补间若会影响同一属性，请使用 immediateRender: false。

关键帧形式

• 数组关键帧：按姿势递进，每一步可设置时长／缓动。
• 百分比关键帧：在单个补间内精确控制时序。
• 属性数组：紧凑地定义多个变化节点。
• 如果每个节点都有自己的缓动，在父级使用 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 路径／描边值、摄像机变换、着色器 uniforms。

避免使用布局／生命周期通道：top/left/right/bottom、width/height、margin/padding、display、visibility、延迟创建 DOM、用辅助覆盖层驱动主体运动。

对于可见性变化，请在已注册的可寻址 GSAP 时间轴上使用 autoAlpha，或在明确的边界处使用零时长 tl.set()。只将目标设为非裁剪元素或裁剪区域内的包装元素；绝不要将 .clip 本身设为目标。绝不要对原始 visibility 做时长补间，也绝不要对 display 做补间。

机制选择

选择能证明提示要求的最小机制：

需求	机制
同一主体改变框或层级	共享元素／FLIP
主体沿可见路径移动	路径移动
描边延伸或描绘	描边绘制
一种形状变成另一种形状	形状插值
可见揭示边界	裁剪、蒙版或着色器 uniform
多个项目按顺序移动	错开／索引延迟
文本本身移动	按行、词、字符或带状区块细分
表面弯曲、拉伸或裁切	父／子级反向变换
UI 有状态	显式状态机
场景具有深度	DOM 3D、Three.js 或 WebGL 摄像机／对象关键帧

机制可以组合，但每种机制都必须让概念更清晰。装饰不能作为证明。

时序

• 只有在能阐明原因或方向时才加入预备动作。
• 加速后应留有静止时间。
• 在峰值处清晰展示机制。
• 后续动作应体现能量和方向。
• 仅当主体需要呈现弹性或触感时才使用过冲。
• 匀速路径移动通常需要 ease: "none"。
• 离散 UI 状态通常需要急促的缓出。
• 重复元素需要有序错开，而不是完全相同的时序。
• 最终定格画面的停留时间应长于过渡姿势。
• 流畅意味着同一主体的速度连续。
• 除非有意为之且经过验证，否则不要让多个补间同时写入同一变换属性。
• 当同一主视觉表面也在缩放或移动时，避免对大范围 clip-path／蒙版变化做动画；应在主要移动稳定后使用嵌套式揭示。

文本

保留行框、词间距、可读性和最终适配效果。如果文本内部发生移动，应移动字形或蒙版带，而不是只移动文本周围的装饰。捕获可读帧。

SVG

描边延伸优先使用 DrawSVGPlugin，其次使用 stroke-dasharray／stroke-dashoffset。形状插值优先使用 MorphSVGPlugin；必要时将基本图形转换为路径，并将复杂轮廓拆分成更简单的部分。

3D

仅靠缩放无法营造真实深度。应在稳定的父级上使用透视、transform-style: preserve-3d、z 轴移动、旋转、摄像机／世界运动、遮挡以及对象交叉时的图层顺序。

使用一到两个能展现深度关系的诊断视角。如果倾斜视角的证明没有体现深度交错，请改善 z 轴、摄像机或遮挡效果。

Canvas／WebGL

通过确定性状态为摄像机位置、摄像机目标、对象变换、材质不透明度、着色器 uniforms 和后处理强度设置关键帧。根据 HyperFrames 时间进行渲染。使用 --ghost，因为标记框无法显示 Canvas 内部运动。

CLI 证明

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	遮罩、文字可读性、完整状态、最终定版、黑屏/重置尾帧

如果选择器证明看起来不对：

1. 重新运行 --json
2. 找到实际的动画目标
3. 对该目标进行拍摄
4. 对完整帧进行快照
5. 相信绘制出的像素，而不是日志

诊断解读

flat 表示没有明确的中间姿态。keyframes 表示存在明确的停顿。motionPath 表示存在路径。trace 表示多笔画绘制。composed with 表示子级运动继承父级运动。

残影间距均匀表示速度恒定。残影聚集表示缓入或收尾。间距较大表示快速移动。

辅助选择器的镜头不构成证明。完整帧已损坏时，洋葱皮镜头也不构成证明。

错误处理

故障	修复
仅有端点	添加中间姿态，保持峰值证明帧，重新运行 --shot
主体一致性中断	保留同一个元素，使用共用的起始/最终边界框，移除替代性交叉淡化
假 3D	添加 z 轴/摄像机移动、遮挡和倾斜视角证明
最终状态错误	添加最终停留，对最终帧减去停留帧和精确的最终帧进行快照
运行时无法跳转	暂停自动播放，移除计时器，在构建完成后注册实例
文字不可读	保留行框，减小位移，添加最终停留，对文字帧进行快照

完成

运行 hyperframes check（会运行 lint）、hyperframes keyframes、一个针对特定目标的 --shot，以及快照。确认首帧、证明姿态、最终帧减去停留帧、精确的最终帧、主体自身的运动，以及不存在调试覆盖层。