用途:为 HyperFrames 合成编写可寻址的关键帧视觉运动,覆盖推近/拉远、平滑多状态缩放或重构、平移与 Ken Burns 运镜、链式运镜、匹配剪辑/甩镜、裁剪与遮罩重构、方向擦除或光圈揭示、分屏交接等。关键帧只负责可见运动,不负责剪辑装配;源范围硬切、修剪、拼接与重排属于 /hyperframes-core,交叉淡化用不同轨道重叠片段加透明度关键帧,声音淡化用 /hyperframes-audio。
主要能力:以姿态阶梯(数组/百分比/属性数组关键帧)表达多状态;优先使用合成器/视觉通道(x/y/z、xPercent/yPercent、scale、rotation、skew、transformOrigin、opacity、autoAlpha、clip-path、mask、CSS 变量、SVG path/dash、相机变换、shader uniform),避免布局/生命周期通道(top/left、width/height、display、visibility 等)。机制选择包括共享元素/FLIP、路径运动、描边绘制、形状插值、clip/mask/shader 揭示、错峰延迟、文字细分、父子反向变换、显式状态机、DOM 3D/Three.js/WebGL 相机关键帧。
使用方式:运行时须可寻址。GSAP 在页面加载时同步构建,使用 gsap.timeline({ paused: true }),注册为 window.__timelines[compositionId],registry key 与 data-composition-id 一致,渲染关键运动不调用 tl.play(),重复次数有限。CSS 关键帧需有限时长与迭代、确定性延迟、animation-fill-mode: both。Anime.js 同步创建、autoplay: false、有限时长与循环、实例推入 window.__hfAnime。WAAPI 需有限时长、fill: "both"、确定性构建。禁止用于渲染关键运动:Date.now()、performance.now()、未播种 Math.random()、hover/scroll 触发、定时器、异步创建时间线、未注册 requestAnimationFrame、无限循环。
验证:使用 npx hyperframes lint、npx hyperframes check、npx hyperframes keyframes .(可加 --json、--runtime all、--selector、--shot、--samples、--layout strip、--from/--to、--ghost、--angle)以及 npx hyperframes snapshot . --at <times>。选择真实动画主体作为 selector,时间点覆盖首帧、证明姿态、结束前保持与精确末帧。
限制:不支持源速度渐变(无时变播放速率包络),需预处理派生媒体;不支持任意源中冻结,需预处理静帧或派生片段;无自动匹配帧发现;几何为手工编写,非人脸跟踪或自动语义重构;缩放本身不构成真实景深,需透视、z 位移、遮挡与角度证明。若证明失败,先修源关键帧再重跑最小失败诊断。