FAÍSCA
触发词：faísca。用户写下 "faísca" 并描述视频（主题、句子、格式）； 此技能将创建项目、搭建时间线并渲染 MP4。
SKILL_DIR = 本文件所在目录。合成基于 HyperFrames（HTML + GSAP），时间线
拉伸 SLOW 倍并以 60 fps 渲染；render-faisca.sh 对每 SLOW 个子帧取平均，
结果为真实运动模糊，效果类似 After Effects。
- 预制特效目录、时间及代码位置：
referencias/efeitos.md - 研究参考视频（拆解、测量字体和颜色、对比）：
referencias/recriar-referencia.md - 原创音乐轨道（由代码生成且动态响应音频）：
referencias/trilha-propria.md， 模板在trilha/ - HyperFrames 协议：如果已安装
hyperframes技能，请先阅读相关文档再修改结构； 也可运行npx hyperframes docs gsap和npx hyperframes docs data-attributes。
开始之前
- 作品归属。 使用发布方的品牌颜色和字体。若无明确品牌，则保留模型的柠檬绿色。
- 文案内容。 每屏 2-4 个字的短冲击句，外加一段连续字幕。仅使用用户要求的内容，不编造。
- 格式与时长。 默认为 16:9；Reels 和 TikTok 用 9:16（参见
referencias/efeitos.md末尾）。无配音时风格适合 4-15 秒；有配音时可延长，但每屏切换间隔仍为 0.4-0.8 秒。 - 文件夹。 每个视频一个独立文件夹，尽量放在非同步目录（如 iCloud、Dropbox）外。
- 无署名。 一切本地运行。
步骤 1 · 创建项目
SKILL_DIR/scripts/novo-faisca.sh <项目文件夹>
运行 hyperframes init，复制模型（含 4 秒可工作合成及本地字体），并确保 lint 零错误。未输出 OK: 则停止并修复。
步骤 2 · 视觉标识
- 强调色：在
:root中定义四个变量--acento、--acento-rgb、--acento-claro、--acento-escuro。所有效果（发光、火花、激光、药丸、平板、3D）均由此派生。 - 字体：放在
assets/fonts/中，通过@font-face在文件中本地引用（lint 要求本地文件）。 仅将标题字体替换为粗体且紧凑的字体；使用前先测量（参见 recriar-referencia）。 - HUD（
#hudBrand）：显示作品所属品牌名称。绝不可显示其他公司品牌。
步骤 3 · 剧本与时间线
- 编写分镜表：事件列表，包含时刻（实际秒数）、文字和目录中的效果名称。 每 0.4-0.8 秒一个创意点。
- 调整
DUR，并同时将#root和#stage的data-duration设为DUR × SLOW（render-faisca.sh会在不匹配时报错）。 - 在
// ---------- linha do tempo块中替换文字和时刻。如需新场景，从目录中复制效果模板。 需要实时跟随位置的效果写在draw(t)中。 SLOW = 8适用于大多数情况。极快的缩放或穿越会导致 8 个样本下出现“环纹”： 请增加到 16（渲染时间翻倍）。- 有配音时：使用 Whisper 等工具提取每个词语的时间，并将效果绑定到这些时刻，而非估算。
步骤 4 · 逐帧审查
SKILL_DIR/scripts/quadros.sh <项目> 0.3,0.9,1.3,1.6,2.3,2.7,3.2,3.6,3.9
时刻为实际秒数（脚本会自动乘以 SLOW）。检查截图：文字是否被截断、单词位置是否正确、效果是否出现。这些截图是单帧样本，不含运动模糊。
步骤 5 · 渲染与验证
SKILL_DIR/scripts/render-faisca.sh <项目> <项目>/renders/<名称>.mp4 [--audio 音轨.wav]
SKILL_DIR/scripts/render-faisca.sh <项目> /tmp/sabotagem.mp4 --sabotar # 必须失败
渲染会检查三项：data-duration == DUR × SLOW、60 fps 时的帧数以及是否存在运动模糊（最终视频必须在有运动的部分与单帧样本不同）。--sabotar 会生成无模糊的视频，并必须以 ERRO: sem desfoque 结尾：证明检查机制能够正确报错。4 秒视频渲染通常耗时 1-4 分钟，视机器性能而定。
npx hyperframes check 也会运行，但其布局审计可能会因设计原因报告问题：尚未出现的字幕单词（透明、text_not_painted）以及重叠的 3D 图层（content_overlap）。要求：lint 零错误；布局审计中的这些发现是预期的。
步骤 6 · 交付
- 提供 MP4 文件并告知其位置。
- 说明与原始需求有何差异，不隐瞒。
- 研究其他人的视频：仅用于并排对比学习，不得公开发布。
已解决的陷阱
| 症状 | 原因与修复 |
|---|---|
| 程序化效果在某些帧消失或卡顿 | draw(t) 保留了状态或测量了 DOM。应是 t 的纯函数；测量放在 build() 中 |
| 进度条抖动并停止上升 | draw 在同一元素上既写 style.transform 又让 GSAP 动画。抖动部分放在子元素（#rbInner）中 |
| 隐藏元素在渲染中始终不出现 | fromTo 中仅在起点设置 opacity: 1。也应在终点设置 opacity: 1 |
| 字幕药丸不可见 | 在没有层叠上下文的元素上使用了 z-index: -1。在单词上设置 isolation: isolate |
| 测试帧的时刻错误 | 快照的 --at 是拉伸时间线的时间。请使用 quadros.sh，它会自动乘以 SLOW |
| 最终缩放出现环纹 | 8 个样本不足以应对指数缩放。设置 SLOW = 16（并同时更新 data-duration） |
| 拍摄的参考颜色看起来不对 | 相机拍摄屏幕会导致颜色溢出。请使用原始颜色值，而非屏幕采样 |
| 测试帧全部相同（仅背景不同） | 工具在 build() 完成前截图了。quadros.sh 已等待 20 秒 |
| 渲染缓慢或卡死 | 临时文件位于同步目录中。脚本使用 MOTION_TMP 或系统临时目录 |
| 渲染需要数十 GB 磁盘空间 | 并行捕获逐帧保存。render-faisca.sh 已启用 HF_CAPTURE_PARALLEL_STREAM=true |
GSAP 无法更改 className 或 textContent | GSAP 3 set 不支持这些属性。请在 draw(t) 中作为 t 的函数手动更改 |
用 translateX(-50%) 居中的元素位置偏移 | GSAP 的缩放会重写 transform。请使用 xPercent: -50 居中 |