安全定位运动(Seek-safe motion)
HyperFrames 并非按顺序播放时间线,而是通过“定位”方式工作:对于每一帧,渲染器将时间线设置到该帧对应的时间点,并捕获页面内容。在 HyperFrames 0.8.x 版本中,这一过程由三个并行工作线程完成,每个线程处理每第三帧,并且每次定位都会先退回 1 毫秒再前进,以确保稳定。因此,每一帧必须是一个关于其时间的纯函数。任何依赖于先前渲染状态、系统时钟或随机性的操作,都会导致不同工作线程渲染出不同的结果,其表现为某些元素在每第三帧缺失。
这个 Bug 在 Studio 预览(按顺序播放)和单张快照中是看不见的。在创建本技能的生产环境中,这是唯一一个能传递到审阅者手中的缺陷:开场标题“连续七秒出现卡顿和闪烁”。
先进行静态检查
PVS_HOME="$(cd "$(cd "${CLAUDE_SKILL_DIR}" && pwd -P)/../.." && pwd)"
"$PVS_HOME/bin/pvs-py" "$PVS_HOME/skills/seek-safe-motion/scripts/lint_motion.py" <video_dir>/video
该脚本会读取 index.html、src/*.tpl 以及它们旁边的 *.js 文件(仅内联脚本),输出 file:line: severity RULE: why 格式的错误信息及修复建议,并在发现任何错误时以退出码 1 终止(使用 --strict 标志可让警告也导致失败,--json 标志则以 JSON 格式输出供工具使用)。每次编辑时间线后以及每次渲染前都应运行它。这是静态检查:它无法识别在运行时计算的变量(将其视为“不可检查”),也无法检测时间上重叠的两个补间。这些情况仍需开发者依靠下面的复现方法来处理。qa.py(渲染质量检查)也会自动运行该检查,并在发现错误时使报告失败。
规则及存在理由
- 每个
fromTo的fromVars中的每一个键也必须在toVars中出现(SS001,错误)。当工作线程的某一帧恰好落在补间开始时,1 毫秒的回退会将补间恢复到其开始之前的状态,此时仅存在于fromVars中的键将永远不会被再次写入。之前的标题补间是fromTo(sel, {yPercent: 110, opacity: 1}, {yPercent: 0}):opacity: 1仅存在于fromVars中,导致一个工作线程在整个补间期间都将标题的透明度保持在 0。应写为{yPercent: 110, opacity: 1}到{yPercent: 0, opacity: 1},或者使用tl.set()后跟tl.to()。同样的规则也适用于to()内部的startAt(SS002)。 - 每个时间点 0 之后的
fromTo都必须设置immediateRender: false(SS003,警告)。否则,补间会在时间线创建时立即写入其起始值,覆盖之前补间设置的值,导致定位到时间线中间时从错误的状态开始。 - 优先使用
fromTo而非from(SS004,警告)。from()的结束状态取决于元素在构建时的状态;一旦较早的补间修改了该元素,不同工作线程对该结束状态的判断就会不一致。 - 绝不动画
display或visibility属性(SS005,错误)。这两个属性无法进行插值;它们会在补间的某个随机点突然翻转。应使用零持续时间的tl.set()在明确的时间点更改它们,并使用opacity或autoAlpha实现淡入淡出效果。 - 不使用时钟、随机数或定时器(SS006,错误):对于任何可见元素,禁止使用
Date、performance.now()、Math.random()、setTimeout、setInterval或requestAnimationFrame。打字抖动或波形效果应使用种子随机数生成器;屏幕上显示的调用计时器应通过时间线内部的onUpdate回调中的tl.time()计算得到。 - 一个暂停的时间线,注册到全局对象,永不播放(SS007、SS011、SS012)。使用
gsap.timeline({ paused: true })创建时间线,完全构建它(当位置依赖文本度量时,应在document.fonts.ready内部构建),然后才赋值window.__timelines["<composition id>"] = tl。在构建完成前注册空时间线会导致空白视频;tl.play()会与渲染器的定位过程冲突。 - 滚动效果应使用
fromTo并显式指定起始和结束位置,以确保每个工作线程计算出相同的偏移量,并且偏移量应限制在真实内容范围内,避免任何线条或图标在边界处被截断。 - 绝不同时存在两个补间操控同一元素的同一属性。 如果某个光标重置操作落入了下一次移动的时间范围内,定位后指针将停留在错误的位置。此规则不通过静态检查检测:需要检查构建时的时序表。
- 动画变换属性,而不是布局属性(SS009,警告):使用
x、y、scale、clip-path替代left、top、width、margin。布局补间会在每一帧触发回流,并且hyperframes check会将其标记为gsap_non_transform_motion。如果某个真实产品控件(如侧边栏展开)的短暂宽度变化能够准确复现产品行为,则可以接受。 - 绝不动画
.clip元素内的内容(SS010,错误)。HyperFrames 通过data-start和data-duration属性拥有对 clip 可见性的控制权;应动画该 clip 内部的一个包装元素。 - 有限次重复(SS008,警告)。
repeat: -1仅允许在有限的根元素data-duration下使用;应通过Math.max(0, Math.floor(span / period) - 1)计算重复次数。 - 在时间点 0 显式设置每个初始状态。 一个执行
gsap.set(sel, vars)的辅助函数也应执行tl.set(sel, vars, 0),这样当定位回 0 时,能恢复第一帧的状态,而不是保留工作线程渲染的最后一帧的状态。
在渲染前复现可疑 Bug
静态检查可以识别模式;快照则能够证明像素级差异。对于从 t0 开始的怀疑有问题的补间:
npx --yes hyperframes@<pinned> snapshot . --at <t0 + 0.3> --no-end --describe false -o a
npx --yes hyperframes@<pinned> snapshot . --at <t0>,<t0 + 0.3> --no-end --describe false -o b
t0 + 0.3 时刻的帧在 a 和 b 中必须完全一样。如果不同,说明通过补间起始点的定位操作改变了状态。要精确重现单个工作线程的行为,可以按顺序对 0, 3, 6, ... 帧执行快照,一直持续到超过补间结束位置。通过不断将时间范围减半进行二分法查找,直到定位出唯一一个问题补间。渲染后,scan_render.py(渲染质量检查)会将同样的 Bug 报告为 WORKER PATTERN 运行:异常帧全部共享同一个帧索引模 3 的余数。
参考资料
references/patterns.md:每个规则的前后代码示例、保持模板安全的辅助函数(lineIn、init、打字效果、滚动效果、光点击等),以及静态检查能发现和不能发现的内容。在编写新辅助函数或修复静态检查发现的问题时,请阅读此文件。