HyperFrames 质量门控
概述
一次出色的 HyperFrames 运行与平庸运行之间的差距并非创造力——而是 验证纪律。出色的运行将每一帧都视为未经证实，直到其像素在多个 seek 时间点被检查过。平庸的运行信任检查器，并交付第一个通过 lint 检查的产品。
核心原则：lint 检查矩形和属性；只有渲染出的像素才说出真相。未经检查，永远不要宣称一帧已完成。
不可协商的门控
对于你构建或编辑的每一帧，请按此顺序完成以下检查。因“改动很小”而跳过某一门控正是质量下降的原因。
- 阅读故事板自身的
## Video direction块，并遵循它，超越预设模板。 当故事板要求句子大小写而预设的 frame.md 要求全大写时，故事板获胜。项目方向 > 预设默认值。 - 每帧只有一个主导动画。 如果你的帧同时有两个元素解析，删掉一个。同时发生所有元素然后冻结（“幻灯片模式”）以及所有元素都漂浮（“屏保模式”）都属于失败。
- 通过在整个文件中搜索来自查机械性陷阱（下表），然后才能声称完成。
- 在浏览器中执行 seek 测试，然后才能报告完成。 克隆
<template>，注册时间线，并在以下时间点执行timeline.seek(t, false)：t=0、每个场景边界 ±0.05s、以及最后一帧。截取每个画面。仔细查看它们。没有经过 seek 测试的帧报告是未经证实的声明。suppressEvents陷阱：裸.seek(t)会抑制onUpdate回调——计数器/打字效果在你的 harness 中看起来坏了，但在渲染器中却正常。始终传递false。
- 在执行任何重定时后，重新推导受影响片段上的
data-start/data-duration。 GSAP 补间时间和片段可见性窗口是两个独立的系统；只重定时其中一个而不重定时另一个会导致不可见元素或静默间隙。这是 #1 回归源。 - 在组装后，在每个切割边界和每帧的中点对完整视频进行快照，并亲自阅读联系表图像。 修复看起来错误的内容，重新快照，然后才能渲染。
机械性陷阱表（在自己的文件中搜索这些）
| 陷阱 | 症状 | 修复 |
|---|---|---|
id 以数字开头 + querySelector("#...") | SyntaxError 静默地杀死时间线注册→空白帧 | 在 id 前加字母，或先使用 getElementById |
在 GSAP 动画元素上使用 CSS transform: | GSAP 在第一次补间时覆盖 CSS 偏移 | 将偏移烘焙到 left/top 中；转换只属于 GSAP |
在带填充的卡片上缺少 box-sizing: border-box | 宽度膨胀，居中对齐偏移，卡片碰撞 | 在每个带填充的卡片上设置它 |
@font-face 指向 fonts.gstatic.com / 任何 CDN | 非确定性渲染；离线后崩溃 | 使用 assets/fonts/ 下的本地文件，项目根相对路径 |
| 肉眼估算重叠数学 | 后期卡片掩埋早期卡片的文本 | 在保持时间使用 getBoundingClientRect() 计算矩形；验证每个堆叠元素的关键文本在屏幕截图中可见 |
| 检查器在裁剪/紧密行高的文本上发现重叠 | 误报（矩形重叠，字形不重叠） | 先验证像素，然后设置 data-layout-allow-overlap——永远不要盲目抑制 |
| 在手机模拟器中屏幕截图被拉伸/重新着色 | 不真实的设备效果 | 始终使用原生宽高比；使用 overflow:hidden 裁剪，绝不要非均匀缩放 |
外部卷上的 ._* AppleDouble 文件 | 破坏构建/渲染 | 在组装/渲染前执行 find . -name '._*' -delete |
| Node < 22 | CLI 失败 | 前缀：export PATH="$HOME/.nvm/versions/node/v22*/bin:$PATH"（或 nvm use 22） |
编排模式（多帧构建）
- 每帧一个工人，每个工人一个文件；工人永不同时触碰共享文件。
- 在派遣工人前准备共享资源（字体、徽标、屏幕截图）；数据包命名确切路径。
- 每个数据包包含：该帧的故事板块原文、全局方向块、上述陷阱表以及 seek 测试要求。
- 编排器在组装后重新运行 lint + check + 联系表检查，无论工人报告了什么——工人自我报告是声称，不是证据。
红旗——停止并验证
- “Lint 和 check 通过了，所以帧是正确的”→检查不会发现埋藏的文本或静默间隙。查看像素。
- “我重定了补间；完成了”→你也重定了片段
data-*窗口吗？ - “我会跳过 seek 测试，代码很简单”→空白帧错误（数字 id 选择器）就出现在简单的代码中，只有 seek 测试能发现它。
- “这张卡片可能不会覆盖另一张”→计算矩形；然后截图。
- “就这一次，CDN 字体没问题”→它不行；渲染必须无网络。
所有这些都意味着：运行你正打算跳过的那个门控。