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 trilha.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 在 GSAP 已動畫的同一元素上寫入 style.transform。抖動部分放到子元素（#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 來置中 |