hyperframes-keyframes

HyperFrames 关键帧

关键帧是一种姿态契约：可见状态、连续主体身份、可搜索运行时、已验证像素。

使用 hyperframes-animation 处理广泛的场景配方。
使用 hyperframes-cli 获取完整命令文档。
仅在实现机制不明确时使用 references/keyframe-patterns.md，而非视觉风格。

步骤

1. 确定动画主体、可见状态、最终状态和运行时。
2. 选择能证明提示的最小机制。仅当机制不明确时阅读 references/keyframe-patterns.md。
3. 在声明的运行时内编写可搜索的关键帧。同步构建并注册运行时实例。
4. 通过 lint、validate、hyperframes keyframes、一个聚焦的 --shot 以及在证明时刻的快照进行验证。
5. 如果证明失败，修复源关键帧并在渲染前重新运行最小的失败诊断。

契约

• 命名移动的主体。
• 命名证明预期运动所需的姿态，包括最终状态。
• 关键帧作用于可见通道，而非隐藏的辅助状态。
• 当连续性重要时保持对象身份。
• 仅当预期运动是替换或溶解时才使用交叉淡入淡出。
• 保持可读或语义状态足够长时间以便观察。
• 最后一帧是动画的一部分，而非清理。
• 除非要求，否则不要重置为静止状态。
• 除非要求，否则不要以黑色结束。
• 如果编辑起始场景，除非要求重新设计，否则保留布局、文案、资源、颜色和最终状态。

运行时规则

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（它可搜索 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 路径/虚线值、相机变换、着色器 uniform。

避免布局/生命周期通道：
top/left/right/bottom、width/height、margin/padding、display、visibility、后期 DOM 创建、执行主体运动的辅助叠加层。

机制选择

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

需求	机制
同一主体改变盒子或层级	共享元素 / 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

通过确定性状态关键帧化相机位置、相机目标、对象变换、材质透明度、着色器 uniform 和后处理强度。从 HyperFrames 时间渲染。使用 --ghost，因为标记框无法看到内部 canvas 运动。

CLI 证明

npx hyperframes lint
npx hyperframes validate
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/相机移动、遮挡、角度证明
错误最终	添加最终保持，快照最终减保持和精确最终
不可搜索运行时	暂停自动播放，注册实例，移除定时器，同步构建
不可读文本	保留行框，减少位移，添加最终保持，快照文本帧

完成

运行 lint、validate、keyframes、一个聚焦的 --shot 和快照。确认第一帧、证明姿态、最终减保持、精确最终、主体拥有的运动，且无调试叠加层。